telemetry-events

Stability: 2 - Stable

Helper for creating and emitting telemetry events.

Contributors

@tristanls, @lpearson05

Contents

• Installation
• Usage
• Tests
• Documentation
  • TelemetryEvents
• Releases

Installation

npm install telemetry-events

Usage

To run the below example run:

npm run readme

"use strict";
 
var events = require('events');
var pkg = require('../package.json');
var TelemetryEvents = require('../index.js');
 
var emitter = new events.EventEmitter();
 
var telemetry = new TelemetryEvents({emitter: emitter, package: pkg});
 
emitter.on('telemetry', function (event) {
    console.dir(event);
});
 
telemetry.emit({type: 'log', level: 'info', message: 'hello info level'});
telemetry.emit({type: 'metric', name: 'web requests', target_type: 'counter', unit: 'Req', value: 1});
 
var _commonEventData = {
    method: "readme",
    provenance: [{module: "my-module"}]
};
telemetry.emit(_commonEventData,
{
    type: "log",
    level: "info",
    message: "info message using common event data"
});
telemetry.emit(_commonEventData,
{
    type: "metric",
    name: "metric with common event data",
    target_type: "counter",
    unit: "Call",
    value: 1
});
 

Tests

npm test

Documentation

• TelemetryEvents

TelemetryEvents

Public API

• new TelemetryEvents(config)
• telemetry.emit([common], event)

new TelemetryEvents(config)

• config: Object
  • package: Object Contents of package.json.
    • name: String Module name.
    • version: String Module version.
  • emitter: EventEmitter (Default: undefined) An optional event emitter to emit events when emit() is called.
  • eventName: String (Default: 'telemetry') An optional event name used for event emission if emitter is specified.

Creates a new TelemetryEvents instance.

telemetry.emit([common], event)

• common: Object (Default: undefined) Optional common data to clone and extend with the event data.
• event: Object Event to be emitted.
• Return: Object The event.

Adds or extends event.provenance. It is worth highlighting that event.provenance is a notion similar to a stack in a stack trace. In the case of telemetry-events, event.provenance is the stack of telemetry emitters. event.provenance is not intended to be used as a tracing feature. For tracing see telemetry-events-trace.

Adds event.timestamp if not present.

If emit(event) is given a single argument, it will be treated as event and common will be undefined.

If emitter is not defined, this method does not emit the event. When emitter is defined, calling this method will emit the event using eventName, if provided, or "telemetry" (by default).

Releases

We follow semantic versioning policy (see: semver.org):

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.