# registerHoneycombInstrumentation

Initializes an instance of Honeycomb Web SDK with Workleap's default settings for web applications.

# Reference 

registerHoneycombInstrumentation(serviceName, apiServiceUrls: [string | Regex], options?: {})

# Parameters

  • serviceName: Honeycomb application service name.
  • apiServiceUrls: A RegExp or string that matches the URLs of the application's backend services. If unsure, use the temporary regex /.+/g, to match all URLs.
  • options: An optional object literal of predefined options.

# Returns

Nothing

# Default instrumentation

The registerHoneycombInstrumentation function registers the following OpenTelemetry instrumentations by default:

For more details, refer to the registerHoneycombInstrumentation.ts file on GitHub.

# Customize backend URLs

Specify values for the apiServiceUrls argument that matches your application's backend URLs. For example, if your backend services are hosted at https://workleap.com/api:

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(
    runtime, "sample", 
    [/https:\/\/workleap.com\/api\.*/], 
    { endpoint: "https://sample-collector" }
);

# Predefined options

The registerHoneycombInstrumentation(serviceName, apiServiceUrls, options) function can be used as shown in the previous example, however, if you wish to customize the default configuration, the function also accept a few predefined options to help with that 👇

# endpoint

  • Type: string
  • Default: undefined

Set the URL to an OpenTelemetry collector. Either endpoint or apiKey option must be provided.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector"
});

# apiKey

Set an Honeycomb ingestion API key. Either endpoint or apiKey option must be provided.

  • Type: string
  • Default: undefined
import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    apiKey: "123"
});

# instrumentations

Append the provided instrumentation instances to the configuration.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";
import { LongTaskInstrumentation } from "@opentelemetry/instrumentation-long-task";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    instrumentations: [
        new LongTaskInstrumentation()
    ]
});

# spanProcessors

Append the provided span processor instances to the configuration.

CustomSpanPressor.ts
export class CustomSpanProcessor implements SpanProcessor {
    onStart(span: Span): void {
        span.setAttributes({
            "processor.name": "CustomSpanPressor"
        });
    }

    onEnd(): void {}

    forceFlush() {
        return Promise.resolve();
    }

    shutdown() {
        return Promise.resolve();
    }
}
import { registerHoneycombInstrumentation } from "@workleap/honeycomb";
import { CustomSpanProcessor } from "./CustomSpanProcessor.ts";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    spanProcessors: [
        new CustomSpanProcessor()
    ]
});

# fetchInstrumentation

  • Type: false or (defaultOptions: FetchInstrumentationConfig) => FetchInstrumentationConfig
  • Default: { ... }

Replace the default @opentelemetry/instrumentation-fetch options by providing a function that returns an object literal with the desired options. This function will receive an object literal containing the default options, which you can either extend or replace.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    fetchInstrumentation: (defaultOptions) => {
        return {
            ...defaultOptions,
            ignoreNetworkEvents: false
        }
    }
});

To disable @opentelemetry/instrumentation-fetch, set the option to false.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    fetchInstrumentation: false
});

# documentLoadInstrumentation

  • Type: false or (defaultOptions: DocumentLoadInstrumentationConfig) => DocumentLoadInstrumentationConfig
  • Default: { ... }

Replace the default @opentelemetry/instrumentation-document-load options by providing a function that returns an object literal with the desired options. This function will receive an object literal containing the default options, which you can either extend or replace.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    documentLoadInstrumentation: (defaultOptions) => {
        return {
            ...defaultOptions,
            ignoreNetworkEvents: false
        }
    }
});

To disable @opentelemetry/instrumentation-document-load, set the option to false.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    documentLoadInstrumentation: (defaultOptions) => {
        return {
            ...defaultOptions,
            ignoreNetworkEvents: false
        }
    }
});

# xmlHttpRequestInstrumentation

  • Type: boolean or (defaultOptions: XMLHttpRequestInstrumentationConfig) => XMLHttpRequestInstrumentationConfig
  • Default: false

By default, @opentelemetry/instrumentation-xml-http-request is disabled. To enable this instrumentation, provide a function that returns an object literal with the desired options. This function will receive an object literal of default options, which you can extend or replace as needed.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    xmlHttpRequestInstrumentation: (defaultOptions) => {
        return {
            ...defaultOptions,
            ignoreNetworkEvents: false
        }
    }
});

Or set the option to true to enable @opentelemetry/instrumentation-xml-http-request with the default options.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    xmlHttpRequestInstrumentation: true
});

# userInteractionInstrumentation

  • Type: boolean or (defaultOptions: UserInteractionInstrumentationConfig) => UserInteractionInstrumentationConfig
  • Default: false

By default, @opentelemetryinstrumentation-user-interaction is disabled. To enable this instrumentation, provide a function that returns an object literal with the desired options. This function will receive an object literal of default options, which you can extend or replace as needed.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    userInteractionInstrumentation: (defaultOptions) => {
        return {
            ...defaultOptions,
            eventNames: ["submit", "click", "keypress"]
        }
    }
});

Or set the option to true to enable @opentelemetryinstrumentation-user-interaction with the default options.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    userInteractionInstrumentation: true
});

# debug

  • Type: boolean
  • Default: false

Indicates whether or not debug information should be logged to the console.

import { registerHoneycombInstrumentation } from "@workleap/honeycomb";

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    debug: true
});

# Configuration transformers

The predefined options are useful to quickly customize the default configuration of the Honeycomb Web SDK, but only covers a subset of the options. If you need full control over the configuration, you can provide configuration transformer functions through the transformers option of the registerHoneycombInstrumentation function. Remember, no locked in ❤️✌️.

To view the default configuration of registerHoneycombInstrumentation, have a look at the registerHoneycombInstrumentation.ts file on GitHub.

# transformers

  • Type: ((options: HoneycombSdkOptions, context: HoneycombSdkOptionsTransformerContext) => HoneycombSdkOptions)[]
  • Default: []
transformer(options: HoneycombSdkOptions, context: HoneycombSdkOptionsTransformerContext) => HoneycombSdkOptions;
import { registerHoneycombInstrumentation, type HoneycombSdkOptionsTransformer } from "@workleap/honeycomb";

const skipOptionsValidationTransformer: HoneycombSdkOptionsTransformer = config => {
    config.skipOptionsValidation = true;

    return config;
}

registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
    endpoint: "https://sample-collector",
    transformers: [skipOptionsValidationTransformer]
});

# Execution context

Generic transformers can use the context argument to gather additional information about their execution context, like if they are operating in debug mode:

transformer.js
import type { HoneycombSdkOptionsTransformer } from "@workleap/honeycomb";

const skipOptionsValidationTransformer: HoneycombSdkOptionsTransformer = (config, context) => {
    if (context.debug) {
        config.skipOptionsValidation = true;
    }

    return config;
}
  • debug: boolean