auth0-instrumentation
The goal of this package is to make it easier to collect information about our services through logs, metrics and error catching.
Logs
With the right configuration, logs will go from the local server to "THE CLOUD", then a bunch of awesome stuff will happen and they'll become available on Kibana.
The logger is powered by bunyan, check their documentation for best practices.
Usage:
var serializers = ; // See https://github.com/trentm/node-bunyan#serializersvar pkg = ;var env = ;var agent = ;agent;var logger = agentlogger; logger;// logs something along the lines of:// {"name":"foo","process":{"app":"my-app","version":"0.0.1","node":"v5.7.1"},"hostname":"dirceu-auth0.local","pid":24102,"level":30,"msg":"Foo","time":"2016-03-22T19:39:21.609Z","v":0}logger;// The first field can optionally be a "fields" object, which// is merged into the log record.
Metrics
Using the right configuration, you can use a metrics collector to... well, collect metrics.
Usage:
var pkg = ;var env = ;var agent = ;agent;var metrics = agentmetrics; var tags = 'user': 'foo' 'endpoint': '/login'; metrics;metrics; // increment by 1metrics; // increment by 5metrics;
Errors
You can use the error reporter to send exceptions to an external service. You can set it up on your app in three ways, depending on what framework is being used.
Hapi
For hapi
, the error reporter is a plugin. To use it, you can do something like this:
var pkg = ;var env = ;var agent = ;agent; var hapi = ;var server = ; // to capture hapi exceptions with contextserver; // to capture a specific error with some extra informationagenterrorReporter;
For hapi
version 17 and above there's a specific plugin for this. You may setup this using:
var hapi = ;var server = ;agent; await server;
Express
For express
, the error reporter is composed of two middlewares. To use it, you can do something like this:
var pkg = ;var env = ;var agent = ;agent; var express = ;var app = ; // before any other request handlersapp; // before any other error handlersapp; // to capture a specific error with some extra informationagenterrorReporter;
Other
If you don't use hapi
or express
- maybe it's not an HTTP API, it's a worker process or a command-line application - you can do something like this:
var pkg = ;var env = ;var agent = ;agent; // to capture all uncaughtsagenterrorReporter; // to capture a specific error with some extra informationagenterrorReporter;
Configuration
Configuration is done through an object with predefined keys, usually coming from environment variables. You only need to configure the variables you want to change.
These are the variables that can be used, along with their default values:
const env = // general configuration 'CONSOLE_LOG_LEVEL': 'info' // log level for console // AWS configuration for Kinesis 'AWS_ACCESS_KEY_ID': undefined 'AWS_ACCESS_KEY_SECRET': undefined 'AWS_REGION': undefined // Kinesis configuration (single stream) 'LOG_TO_KINESIS': undefined // Kinesis stream name 'LOG_TO_KINESIS_LEVEL': 'info' // log level for Kinesis 'LOG_TO_KINESIS_LOG_TYPE': undefined // bunyan stream type 'KINESIS_OBJECT_MODE': true 'KINESIS_TIMEOUT': 5 'KINESIS_LENGTH': 50 // Kinesis configuration (pool of streams for failover) 'KINESIS_POOL': // if any of this config options are undefined will take root level, // if exists 'LOG_TO_KINESIS': undefined // Kinesis stream name 'LOG_TO_KINESIS_LEVEL': 'info' // log level for Kinesis 'LOG_TO_KINESIS_LOG_TYPE': undefined // bunyan stream type 'AWS_ACCESS_KEY_ID': undefined 'AWS_ACCESS_KEY_SECRET': undefined 'AWS_REGION': undefined 'IS_PRIMARY': undefined // set as true for the kinesis instance you want to work as primary // Error reporter configuration 'ERROR_REPORTER_URL': undefined // Sentry URL 'ERROR_REPORTER_LOG_LEVEL': 'error' // Metrics collector configuration 'METRICS_API_KEY': undefined // DataDog API key 'METRICS_HOST': hostname 'METRICS_PREFIX': pkgname + '.' 'METRICS_FLUSH_INTERVAL': 15 // seconds;
Docker Testing
To test auth0-instrumentation
locally in a simple container simply run
docker-compose up && docker-compose rm -f