beaver-logger

Front-end logger, which will:

• Buffer your front-end logs and periodically send them to the server side
• Automatically flush logs for any errors or warnings

This is a great tool to use if you want to do logging on the client side in the same way you do on the server, without worrying about sending off a million beacons. You can quickly get an idea of what's going on on your client, including error cases, page transitions, or anything else you care to log!

Overview

Setup

1var $logger = beaver.Logger({
2  url: "/my/logger/url",
3});

Basic logging

$logger.info(<event>, <payload>);

Queues a log. Options are debug, info, warn, error.

For example:

$logger.error('something_went_wrong', { error: err.toString() })

$logger.track(<payload>);

Call this to attach general tracking information to the current page. This is useful if the data is not associated with a specific event, and will be sent to the server the next time the logs are flushed.

$logger.metricCounter(<event>, <payload>);

Queues a counter metric, helper wrapping logger.metric

logger.metricCounter({
  namespace: "pp.team.product.feature",
  event: "button_click",
  dimensions: {
    type: "paypal"
  }
})

Using a namespace prefix

const logger = new Logger({...options, metricNamespacePrefix: "company.team.app"})

logger.metricCounter({
  namespace: "product.feature",
  event: "button_click",
})

// creates metric with namespace of
// company.team.app.product.feature

$logger.metricGauge(<event>, <payload>);

Queues a gauge metric, helper wrapping logger.metric

logger.metricGauge({
  namespace: "pp.team.product.feature",
  event: "request_latency",
  value: 100,
  dimensions: {
    method: "GET"
  }
})

Using a namespace prefix

const logger = new Logger({...options, metricNamespacePrefix: "company.team.app"})

logger.metricGauge({
  namespace: "product.feature",
  event: "request_latency",
  value: 100
})

// creates metric with namespace of
// company.team.app.product.feature

Deprecated - $logger.metric(<event>, <payload>);

Queues a metric. We suggest using the metricCount or metricGauge interface for better type safety and clearer intention in your code.

Advanced

$logger.addMetaBuilder(<function>);

Attach a method which is called and will attach general information to the logging payload whenever the logs are flushed

1$logger.addMetaBuilder(function () {
2  return {
3    current_page: getMyCurrentPage(),
4  };
5});

$logger.addMetricDimensionBuilder(<function>);

Attach a method which is called and will attach values to each metric's dimensions whenever the logs are flushed

1$logger.addMetricDimensionBuilder(() => ({
2  token_used: true,
3  type: "user_id_token",
4}));

$logger.addPayloadBuilder(<function>);

Attach a method which is called and will attach values to each individual log's payload whenever the logs are flushed

1$logger.addPayloadBuilder(function () {
2  return {
3    performance_ts: window.performance.now(),
4  };
5});

$logger.addTrackingBuilder(<function>);

Attach a method which is called and will attach values to each individual log's tracking whenever the logs are flushed

1$logger.addTrackingBuilder(function () {
2  return {
3    pageLoadTime: getPageLoadTime(),
4  };
5});

$logger.addHeaderBuilder(<function>);

Attach a method which is called and will attach values to each individual log requests' headers whenever the logs are flushed

1$logger.addHeaderBuilder(function () {
2  return {
3    "x-csrf-token": getCSRFToken(),
4  };
5});

$logger.flush();

Flushes the logs to the server side. Recommended you don't call this manually, as it will happen automatically after a configured interval.

Installing

• Install via npm

npm install --save beaver-logger

• Include in your project

1<script src="/js/beaver-logger.min.js"></script>

or

1let $logger = require("beaver-logger");

Configuration

Full configuration options:

1var $logger = beaver.Logger({
2  // Url to send logs to
3  url: "/my/logger/url",
4
5  // Prefix to prepend to all events
6  prefix: "myapp",
7
8  // Log level to display in the browser console
9  logLevel: beaver.LOG_LEVEL.WARN,
10
11  // Interval to flush logs to server
12  flushInterval: 60 * 1000,
13
14  // Use sendBeacon if supported rather than XHR to send logs; defaults to false
15  enableSendBeacon: true,
16});

Server Side

beaver-logger includes a small node endpoint which will automatically accept the logs sent from the client side. You can mount this really easily:

1let beaverLogger = require("beaver-logger/server");
2
3myapp.use(
4  beaverLogger.expressEndpoint({
5    // URI to recieve logs at
6    uri: "/api/log",
7
8    // Custom logger (optional, by default logs to console)
9    logger: myLogger,
10
11    // Enable cross-origin requests to your logging endpoint
12    enableCors: false,
13  })
14);

Or if you're using kraken, you can add this in your config.json as a middleware:

1      "beaver-logger": {
2          "priority": 106,
3          "module": {
4              "name": "beaver-logger/server",
5              "method": "expressEndpoint",
6              "arguments": [
7                  {
8                      "uri": "/api/log",
9                      "logger": "require:my-custom-logger-module"
10                  }
11              ]
12          }
13      }

Custom backend logger

Setting up a custom logger is really easy, if you need to transmit these logs to some backend logging service rather than just logging them to your server console:

1module.exports = {
2  log: function (req, level, event, payload) {
3    logSocket.send(
4      JSON.stringify({
5        level: level,
6        event: event,
7        payload: payload,
8      })
9    );
10  },
11};

Data Flow

1flowchart TD
2    A[Client-Side Log statement] --> B[beaver-logger/client]
3    B[beaver-logger/client] --> C[beaver-logger/server]
4    C[beaver-logger/server] --> D[your-custom-logger]
5    D[your-customer-logger] --> E[Backend 1]
6    D[your-customer-logger] --> F[Backend 2]
7    G[Server-Side Log statement] --> D[your-custom-logger]