telemetry-events-trace

Stability: 1 - Experimental

Helper for creating and emitting TelemetryEvents for tracing.

Contributors

@tristanls

Contents

• Installation
• Usage
• Tests
• Documentation
  • TraceTelemetryEvents
• Releases

Installation

npm install telemetry-events-trace

Usage

To run the below example run:

npm run readme

"use strict";

const events = require("events");
const pkg = require("../package.json");
const TelemetryEvents = require("telemetry-events");

const TraceTelemetryEvents = require("../index.js");

const emitter = new events.EventEmitter();

const telemetry = new TelemetryEvents(
    {
        emitter,
        package: pkg
    }
);
const tracing = new TraceTelemetryEvents(
    {
        telemetry
    }
);

emitter.on("telemetry", event => console.dir(event));

let rootSpan1 = tracing.trace("rootSpan1", undefined, {user: "tristan"});
setTimeout(() => rootSpan1.finish(), 5);

let rootSpan2 = tracing.trace("rootSpan2", {server: "001"}, {user: "tristan"});
let childSpan1 = rootSpan2.childSpan("childSpan1", {db: "020"});
let childSpan2 = rootSpan2.childSpan("childSpan2", {db: "021"});
let childSpan3 = childSpan1.childSpan("childSpan3");
let childSpan4 = childSpan2.followingSpan("childSpan4", {consumer: "me"});
childSpan4.tags(
    {
        "some": "tag",
        "some_other": "tag"
    }
);

let headers = childSpan3.inject("http_headers", {});
console.log(headers);
let extractedSpan = tracing.extract("http_headers", headers);

let childSpan5 = extractedSpan.childSpan("childSpan5");
childSpan5.tag("error", true);

setTimeout(() => childSpan3.finish(), 10);
setTimeout(() => childSpan2.finish(), 11);
setTimeout(() => childSpan1.finish(), 12);
setTimeout(() => rootSpan2.finish(), 13);
setTimeout(() => childSpan4.finish(), 22);

setTimeout(() => childSpan5.finish(), 20);

Tests

No tests at this time.

Documentation

• TraceTelemetryEvents

TraceTelemetryEvents

Public API

• new TraceTelemetryEvents(config)
• tracing.extract(type, carrier)
• tracing.trace(name, [tags], [baggage], [start])
• span.childSpan(name, [tags], [baggage], [start])
• span.finish([finish])
• span.followingSpan(name, [tags], [baggage], [start])
• span.inject(type, carrier)
• span.tag(key, value)
• span.tags(tags)

new TraceTelemetryEvents(config)

• config: Object
  • telemetry: Object TelemetryEvents instance.
• Return: Object Instance of TraceTelemetryEvents.

Creates a new TraceTelemetryEvents instance.

tracing.extract(type, carrier)

• type: String One of ["http_headers", "text_map"]
• carrier: Object JavaScript object to extract span from.
• Return: TraceTelemetryEvents.Span Span initialized from information in the carrier.

Creates a localy copy of the parent span extracted from the carrier. This local Span instance can then be used to generate child or following spans.

tracing.trace(name, [tags], [baggage], [start])

• name: String Operation name to trace.
• tags: Object (Default: {}) Tags to attach to the span.
• baggage: Object (Default: {}) Baggage to attach to all the spans in the trace.
• start: Date (Default: new Date()) Start time.
• Return: TraceTelemetryEvents.Span Newly created root span for the trace.

Creates a root span.

span.childSpan(name, [tags], [baggage], [start])

• name: String Operation name to trace.
• tags: Object (Default: {}) Tags to attach to the span.
• baggage: Object (Default: {}) Baggage to attach to this and all following spans in the trace.
• start: Date (Default: new Date()) Start time.
• Return: TraceTelemetryEvents.Span Newly created child span.

Creates a child span that has a childOf reference to the span.

span.finish([finish])

• finish: Date (Default: new Date()) Finish time.
• Return: TraceTelemetryEvents.Span Finished span.

Finishes the span and emits a trace telemetry event.

span.followingSpan(name, [tags], [baggage], [start])

• name: String Operation name to trace.
• tags: Object (Default: {}) Tags to attach to the span.
• baggage: Object (Default: {}) Baggage to attach to this and all following spans in the trace.
• start: Date (Default: new Date()) Start time.
• Return: TraceTelemetryEvents.Span Newly created "follows from" span.

Creates a child span that has a followsFrom reference to the span.

span.inject(type, carrier)

• type: String One of ["http_headers", "text_map"]
• carrier: Object JavaScript object to inject span information into.
• Return: carrier with injected span information.

Injects span information into the carrier.

span.tag(key, value)

• key: String Tag key.
• value: String Tag value.
• Return: TraceTelemetryEvents.Span Span where tags were updated.

Creates or updates a tag in a span.

span.tags(tags)

• tags: Object Keys and values of tags to create or update.
• Return: TraceTelemetryEvents.Span Span where tags were updated.

Creates or updates tags in a span.

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.

caveat: Major version zero is a special case indicating development version that may make incompatible API changes without incrementing MAJOR version.