Skip to content

Boomerang Plugin for collecting spans and exporting them to an OpenTelemetry Collector

License

Notifications You must be signed in to change notification settings

Dimi-Ma/boomerang-opentelemetry-plugin

 
 

Repository files navigation

Boomerang-OpenTelemetry Plugin

This is a Boomerang plugin for collecting spans using the OpenTelemetry framework and exporting them, e.g., to an OpenTelemetry collector. The plugin is based on the opentelemetry-js implementation. The plugin version always corresponds to the opentelemetry-js version that's being used internally.

alt text Example Screenshot of recorded spans using Jaeger and the Ocelot EUM Server

Using with Angular

This module provides Zone Context Manager with a dependency for zone-js for Web applications. If you use Angular you already have the zone-js. In this case, this might case some problems and you should use a custom build of this library where zone-js has been removed.

Features

Currently implemented features:

  • Automatic instrumentation of the asynhrounous XMLHttpRequest API and Fetch API, including B3 header propagation. More details ↗
  • Automatic tracing of the initial page load including resource timings.
  • Automatic instrumentation of user interactions.
  • Automatic local context propagation using Zone Context Manager. More details ↗
  • Exporting collected spans to an OpenTelemetry collector.
  • Providing access to the OpenTelemtry Tracing-API for manual instrumentation.

OpenTelemetry Plugins

A list of OpenTelemetry instrumentation and non-instrumentation plugins that are currently included in this Boomerang plugin:

Setup

The basic setup requires only to include the boomerang-opentelemetry.js file to the list of the boomerang plugins to run. This setup works out-of-the-box with the inspectit-ocelot EUM server.

By default, collected spans will be sent to an URL relative to the defined beacon_url Boomerang property in case your beacon_url ends with /beacon. In this case, an endpoint for spans is used, where /beacon is replaced by /spans. However, if you use different URLs, the collector URL must be configured accordingly.

Configuration

The plugin is configured using the standard Boomerang configuration. All available configuration options are optional.

BOOMR.init({
  beacon_url: 'http://localhost:8080/beacon/',
  
  OpenTelemetry: {
    samplingRate: 1.0, // an optional sampling rate
    corsUrls: ['https://my.backend.com'],
    consoleOnly: false, // an optional flag whether spans should only be printed to the console
    collectorConfiguration: {
      url: 'http://localhost:55681/v1/trace' // an optional url for an OpenTelemetry collector
      headers: {}, // an optional object containing custom headers to be sent with each request
      concurrencyLimit: 10, // an optional limit on pending requests
    },
    plugins: {
      instrument_fetch: true,
      instrument_xhr: true,
      instrument_document_load: true,
      instrument_user_interaction: true
    },
    exporter: {
      maxQueueSize: 100,
      maxExportBatchSize: 10,
      scheduledDelayMillis: 500,
      exportTimeoutMillis: 30000,
    },
    commonAttributes: {
        "application": "demo-app",
        "stage": "prod"
    },
    serviceName: () => BOOMR.getVar("page_name") || "unknown_service", // an optional service name for the spans
    prototypeExporterPatch: false // patches the OpenTelemetry collector-span-exporter in case the Prototype framework is used
    propagationHeader: "TRACE_CONTEXT",
  }
});

Available options are:

Option Description Default value
samplingRate Sampling rate to use when collecting spans. Value must be between 0 and 1. 1
corsUrls Array of CORS URLs to take into consideration when propagating trace information. By default, CORS URLs are excluded from the propagation. []
collectorConfiguration Object that defines the OpenTelemetry collector configuration, like the URL to send spans to. See CollectorExporterNodeConfigBase interface for all options. undefined
consoleOnly If true spans will be logged on the console and not sent to the collector endpoint. false
plugins Object for enabling and disabling OpenTelemetry plugins.
plugins.instrument_fetch Enabling the OpenTelemetry plugin for insturmentation of the fetch API. This will only be used in case the fetch API exists. true
plugins.instrument_xhr Enabling the OpenTelemetry plugin for insturmentation of the XMLHttpRequest API. true
plugins.instrument_document_load Enabling the OpenTelemetry plugin for insturmentation of the document load (initial request). true
plugins.instrument_user_interaction Enabling the OpenTelemetry plugin for insturmentation of user interactions. true
exporter Object for configuring the span exporter. Only used if consoleOnly is not enabled.
exporter.maxQueueSize The maximum queue size. After the size is reached spans are dropped. 100
exporter.maxExportBatchSize The maximum batch size of every export. It must be smaller or equal to maxQueueSize. 10
exporter.scheduledDelayMillis The interval between two consecutive exports. 500
exporter.exportTimeoutMillis How long the export can run before it is cancelled. 30000
commonAttributes An Object defining common span attributes which will be added to each recorded span. {}
serviceName A string or function which can be used to set the spans' service name. A function can be defined for dynamically providing the service name, e.g. based on Boomerang values. undefined
prototypeExporterPatch Patches the OpenTelemetry collector-span-exporter, so it is compatible with the Prototype framework. This is only necessary and should only be activated, when the Prototype framework is used. For more information see the linked file. false
propagationHeader Defines the format of the context propagation header. Available formats: TRACE_CONTEXT, B3_SINGLE, B3_MULTI TRACE_CONTEXT

Manual Instrumentation

The boomerang OpenTelemetry Plugin also exposes a part of the OpenTelemetry tracing API for manual instrumentation:

const tracer = window.BOOMR.plugins.OpenTelemetry.getTracer("my-library-name", "v1.0");

const span = tracer.startSpan("doSomething");
// do something
span.end();

For execution of functions within a span context, the plugin provides the following convenient function: withSpan(span, fn)

const OT = window.BOOMR.plugins.OpenTelemetry;
const tracer = OT.getTracer("my-library-name", "v1.0");

const span = tracer.startSpan("doSomething");
OT.withSpan(span, () => {
  // do something
});
span.end();

The plugin also provides direct access to the OpenTelemetry API via the following function: getOpenTelemetryApi(). This returns the OpenTelemetry API and can be used for more advanced data collection.

Asynchronous inclusion of Boomerang

Make sure to check that window.BOOMR.plugins.OpenTelemetry actually exists prior to using it in your code in case you load boomerang asynchronously.

Development

During development, the plugin can be compiled and automatically recompiled whenever a file is changed using: yarn watch

The plugin can be built using the command: yarn build

Release

To create a release, create a new Tag following the structure *.*.*. Write a meaningful message for the tag, since that will be the release's text as well. Then push the tag. The GitHub Action "Create new Release" will build the plugin and its software bill of materials, and then create a new release automatically.

About

Boomerang Plugin for collecting spans and exporting them to an OpenTelemetry Collector

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 92.2%
  • JavaScript 7.8%