DTP Logan API

This is the official Node.js client API for the DTP Logan application support suite, which enables developers to instrument, monitor, manage, diagnose, and automate their web-based applications.

What Is Logan?

Logan (Log analyzer) is an application instrumentation HTTP API intended for use in the development, maintenance, diagnostics and debugging, monitoring, management, and automation of web applications, application servers, and a variety of other processes running on a variety of devices.

Logan provides this Node.js client for recording Events. At the website, Logan offers Agents which define Sensors that implement Tests to be executed against matching Events as they are being received in real time. Agents can then execute Actions when the the Tests on their Sensors receive a "hit" (meet their defined criteria).

Agent actions include:

1. Send a notification
2. Send an email to one or more recipients
3. POST a webhook to your application
4. Platform automation (calling other APIs and/or executing scripts)

Optionally, LoganClient supports the use of Bull job queues for sending events from a worker instead of having the Logan HTTP request in your client's request path. This can help absorb spikes in traffic and prevent log event data loss.

Getting Started

Install as a dependency using NPM:

npm i dtp-logan-api

Or install as a dependency using Yarn:

yarn add dtp-logan-api

Then, import the classes you'll need:

import {
  LoganClient,
  LoganComponent,
  LoganError,
  LoganWorker,
} from 'dtp-logan-api';

and initialize the Logan client:

const options = {
  firewall: {
    enabled: process.env.DTP_LOGAN_FIREWALL === 'enabled',
    dbPath: '/var/lib/dtp/logan-firewall.sqlite3',
    blockDuration: '14 day',
  },
  api: {
    enabled: process.env.DTP_LOGAN === 'enabled',
    key: process.env.DTP_LOGAN_API_KEY,
    scheme: process.env.DTP_LOGAN_SCHEME,
    host: process.env.DTP_LOGAN_HOST,
  },
  request: {
    userField: 'user',
    userIdField: '_id',
    usernameField: 'username',
  },
  flags: {
    includeHostname: true,
    includeClientIpAddress: true,
    includeUser: true,
  },
  queue: {
    enabled: true,
    name: 'logan',
    redis: {
      host: process.env.REDIS_HOST,
      port: process.env.REDIS_PORT,
      username: process.env.REDIS_USERNAME, // requires Redis >= 6
      password: process.env.REDIS_PASSWORD,
      keyPrefix: process.env.REDIS_PREFIX,
    },
    defaultJobOptions: {
      attempts: 3,
      priority: 10,
      removeOnComplete: true,
      removeOnFail: true,
    },
  },
};

const logan = new LoganClient(options);

Now, you can use the client to record events in Logan.

async onGetNouns (req, res, next) {
  try {
    /*
     * Your business logic
     */
    res.locals.nouns = await nounService.getNouns();

    /*
     * Write event to Logan to describe what you did. The use of await is
     * optional and not recommended.
     */
    logan.sendRequestEvent(component, req, {
      level: 'info',
      event: 'onGetRequest',
      message: 'serving up some nouns',
      data: {
        nounCount: res.locals.nouns.length,
      },
    });

    /*
     * Render the view
     */
    res.render('noun/index');
  } catch (error) {
    logan.sendRequestEvent(component, req, {
      level: 'error',
      event: 'onGetNouns',
      message: error.message,
      data: { error },
    });
    return next(error);
  }
}

Client Options

The LoganClient accepts various options to control its behavior.

firewall

Options that control the Logan host firewall interface to enable blocking and un-blocking malicious hosts by IP address with asynchronous processing and centralized reporting.

enabled

When true, Logan host firewall services will be enabled and attempt to make changes to the Uncomplicated Firewall on localhost.

dbPath

The absolute pathed filename locating the Logan Firewall sqlite3 database file (used for tracking which IPs have been blocked and when).

blockDuration

The duration of malicious IP blocks expressed as would be expected by sqlite3's date function (ex: '14 day').

api

Visit DTP Logan to sign up, register your application(s), get an API Key, and start instrumenting your apps in minutes.

api.enabled (Boolean) default: true

true to enable reporting, false to disable reporting.

api.scheme (String) default: 'https'

The scheme to be used for API requests ('http' or 'https').

api.host (String) default: 'logan.digitaltelepresence.com'

The hostname of the API server to which events will be reported.

request

Specifies options for how to reference User information on an ExpressJS request object when using LoganClient.sendRequestEvent.

request.userField (String) default: 'user'

Specifies the name of the field on the ExpressJS request object to reference for the authenticated user's information.

request.userIdField (String) default: '_id'

Specifies the name of the field on the req[userField] object to reference for the authenticated user's ID.

request.usernameField

Specifies the name of the field on the req[userField] object to reference for the authenticated user's username. This should not be set to an email address field unless that's all you have.

flags

Specifies various flags/switches for controlling some core features of the API.

flags.includeHostname (Boolean) default: true

When true, os.hostname() is used to include the hostname of the server hosting your application. Some analytics features aren't available in Logan if this is disabled.

flags.includeClientIpAddress (Boolean) default: true

When true and calling LoganClient.sendRequestEvent the value of req.ip is automatically sent as part of the event. Some analytics features aren't available in Logan if this is disabled.

flags.includeUser (Boolean) default: true

When true and calling LoganClient.sendRequestEvent, req.user._id and req.user.username are automatically sent as part of the event data. Some analytics features aren't available in Logan if this is disabled.

queue

Specifies options for the LoganClient job queue, which is based on Bull.

queue.enabled (Boolean) default: false

When true, the Bull job queue will be initialized and used for sening Logan events to the analytics platform.

queue.name (String) default: 'logan'

The name of the job queue to create and use within Bull/Redis. If logan conflicts with a queue name you're already using, you can change it here.

queue.redis

Specifies options Bull Queue will use when connecting to Redis.

queue.redis.host

The IP address or hostname of the Redis server being used to manage the job queue for LoganClient.

queue.redis.port

The TCP port number of the Redis server being used to manage the job queue for LoganClient.

queue.redis.username (String)

The username to provide when authenticating to Redis. Requires Redis >= 6.

queue.redis.password (String)

The password to provide when authenticating to Redis.

queue.redis.keyPrefix (String) default: 'logan'

The prefix to prepend to all keys used for managing Bull Queue jobs in Redis.

queue.defaultJobOptions

Specifies the Bull Queue default options for the client's use when adding event transmit jobs to the queue.

queue.defaultJobOptions.attempts (Number) default: 3

The total number of attempts to try the job until it completes.

queue.defaultJobOptions.priority (Number) default: 10

Optional priority value. ranges from 1 (highest priority) to MAX_INT (lowest priority). Note that using priorities has a slight impact on performance, so do not use it if not required.

queue.defaultJobOptions.removeOnComplete (Boolean) default: true

When true, finished jobs will be automatically removed from the job queue.

queue.defaultJobOptions.removeOnFail (Boolean) default: false

When true, failed jobs will be automatically removed from the job queue.

Software License

Copyright © 2023 Rob Colbert <[email protected]>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.