Skip to content

Latest commit

 

History

History
141 lines (100 loc) · 4.46 KB

API.md

File metadata and controls

141 lines (100 loc) · 4.46 KB
Raw

API

Contents

Creating Loggers

To get started, first you'll need to create a HttpLogger instance. Here there are options to specify a URL (for where JSON messages will be sent) and/or a specific set of logging rules (for what privacy protections to apply). Default values will be used for either of these if specific values are not provided.

const resurfaceio = require('resurfaceio-logger');
const HttpLogger = resurfaceio.HttpLogger;

// with default url and rules
let logger = new HttpLogger();

// with specific url and default rules
logger = new HttpLogger({url: 'https://...'});

// with specific url and rules
logger = new HttpLogger({url: 'https://...', rules: 'include strict'});

// with specific url and rules from local file
logger = new HttpLogger({url: 'https://...', rules: 'file://./rules.txt'});

Logging HTTP Calls

Now that you have a logger instance, let's do some logging. Here you can pass standard request/response objects, as well as response body and request body content when these are available.

const HttpMessage = resurfaceio.HttpMessage;

// with standard objects
HttpMessage.send(logger, request, response);

// with response body
HttpMessage.send(logger, request, response, 'my-response-body');

// log with response and request body
HttpMessage.send(logger, request, response, 'my-response-body', 'my-request-body');

If standard request and response objects aren't available in your case, create mock implementations to pass instead.

// define request to log
const request = new HttpRequestImpl();
request.addHeader('Content-Type', 'application/json');
request.method = 'POST';
request.body['B'] = '234';  // POST param
request.url = 'http://resurface.io';

// define response to log
const response = new HttpResponseImpl();
response.addHeader('Content-Type', 'text/html; charset=utf-8');
response.statusCode = 200;

// log objects defined above
HttpMessage.send(logger, request, response);

Setting Default Rules

If no rules are provided when creating a logger, the default value of include strict will be applied. A different default value can be specified as shown below.

HttpRules.defaultRules = 'include debug';

When specifying multiple default rules, put each on a separate line. This is most easily done with a template literal.

HttpRules.defaultRules = `
    include debug
    sample 10
`;

Setting Default URL

If your application creates more than one logger, or requires different URLs for different environments (development vs testing vs production), then set the USAGE_LOGGERS_URL environment variable as shown below. This value will be applied if no other URL is specified when creating a logger.

# from command line
export USAGE_LOGGERS_URL="https://..."

# for Heroku cli
heroku config:set USAGE_LOGGERS_URL=https://...

Enabling and Disabling Loggers

Individual loggers can be controlled through their enable and disable methods. When disabled, loggers will not send any logging data, and the result returned by the log method will always be true (success).

All loggers for an application can be enabled or disabled at once with the UsageLoggers class. This even controls loggers that have not yet been created by the application.

UsageLoggers.disable();    // disable all loggers
UsageLoggers.enable();     // enable all loggers

All loggers can be permanently disabled with the USAGE_LOGGERS_DISABLE environment variable. When set to true, loggers will never become enabled, even if UsageLoggers.enable() is called by the application. This is primarily done by automated tests to disable all logging even if other control logic exists.

# from command line
export USAGE_LOGGERS_DISABLE="true"

# for Heroku app
heroku config:set USAGE_LOGGERS_DISABLE=true

© 2016-2024 Graylog, Inc.