initializeTelemetry

Reference

const client = initializeTelemetry(productFamily, options?: { logRocket?, honeycomb?, mixpanel?, verbose?, loggers? });

Parameters

productFamily: wlp or sg.
options: An optional object literal of options:
- logRocket: An optional LogRocket instrumentation registration options object. If provided, LogRocket instrumentation is registered, if omitted, it is skipped.
  - appId: The LogRocket application id.
  - options: An optional object literal of options:
    - rootHostname: A root hostname to track sessions across subdomains.
    - privateFieldNames: Names of additional fields to exclude from session replays. These fields will be removed from network requests, responses using a fuzzy-matching algorithm.
    - privateQueryParameterNames: Names of additional fields to exclude from session replays. These fields will be removed from query parameters using a fuzzy-matching algorithm.
    - transformers: An array of transformer functions to update the default LogRocket options.
- honeycomb: An optional Honeycomb instrumentation registration options object. If provided, Honeycomb instrumentation is registered, if omitted, it is skipped.
  - namespace: The service namespace. Will be added to traces as a service.namespace custom attribute.
  - serviceName: Honeycomb application service name.
  - apiServiceUrls: A RegExp or string that matches the URLs of the application's backend services. If unsure, start with the temporary regex /.+/g, to match all URLs.
  - options: An optional object literal of options:
    - proxy: Set the URL to an OpenTelemetry collector proxy. Either proxy or apiKey option must be provided.
    - credentials: The credentials mode of the trace requests sent to the proxy. The default value is "include".
    - apiKey: Set an Honeycomb ingestion API key. Either proxy or apiKey option must be provided.
    - instrumentations: Append the provided instrumentation instances to the configuration.
    - spanProcessors: Append the provided span processor instances to the configuration.
    - fetchInstrumentation: 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.
    - documentLoadInstrumentation: 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.
    - xmlHttpRequestInstrumentation: 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.
    - userInteractionInstrumentation: 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.
    - transformers: An array of transformer functions to update the default Honeycomb options.
- mixpanel: An optional Mixpanel initialization options object. If provided, Mixpanel is initialized, if omitted, it is skipped.
  - envOrTrackingApiBaseUrl: The environment to get the navigation url from or a base URL. The base URL inferred from the provided environment, or the provided base URL will be appended by the tracking endpoint.
  - options: An optional object literal of options:
    - productId: The product id.
    - trackingEndpoint: An optional tracking endpoint. The default value is tracking/track.
- verbose: If no loggers are configured, verbose mode will automatically send logs to the console. In some cases, enabling verbose mode also produces additional debug information.
- loggers: An optional array of RootLogger instances.

Returns

A TelemetryClient instance.

Initialize all telemetry platforms

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    logRocket: {
        appId: "my-app-id"
    },
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy"
        }
    },
    mixpanel: {
        envOrTrackingApiBaseUrl: "development"
    }
});

LogRocket

Set a root hostname

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    logRocket: {
        appId: "my-app-id",
        options: {
            rootHostname: "an-host.com"
        }
    }
});

Remove custom private fields

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    logRocket: {
        appId: "my-app-id",
        options: {
            privateFieldNames: ["a-custom-field"]
        }
    }
});

To view the default private fields, have a look at the registerLogRocketInstrumentation.ts file on GitHub.

Remove custom query parameters

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    logRocket: {
        appId: "my-app-id",
        options: {
            privateQueryParameterNames: ["a-custom-param"]
        }
    }
});

To view the default private query parameters, have a look at the registerLogRocketInstrumentation.ts file on GitHub.

Use transformer functions

The predefined options are useful to quickly customize the default configuration of the LogRocket 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 logrocket.transformers option of the initializeTelemetry function. Remember, no locked in ❤️✌️.

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

import { initializeTelemetry, type LogRocketSdkOptionsTransformer } from "@workleap/telemetry/react";

const disableConsoleLogging: LogRocketSdkOptionsTransformer = config => {
    config.console = ...(config.console || {});
    config.console.isEnabled = false;

    return config;
};

const client = initializeTelemetry("sg", {
    logRocket: {
        appId: "my-app-id",
        options: {
            transformers: [disableConsoleLogging]
        }
    }
});

Generic transformers can use the context argument to gather additional information about their execution context:

transformer.ts
import type { LogRocketSdkOptionsTransformer } from "@workleap/telemetry/react";

const disableConsoleLogging: LogRocketSdkOptionsTransformer = (config, context) => {
    if (!context.verbose) {
        config.console = ...(config.console || {});
        config.shouldDebugLog = false;

        context.logger.debug("Disabling LogRocket SDK debug logs.");
    }

    return config;
}

Honeycomb

Use a proxy

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy"
        }
    }
});

When a proxy option is provided, the trace requests are sent with the current session credentials (credentials: "include"), which allows the proxy to authenticate the requests with the session cookies.

When the proxy is hosted on a different origin than the application, the browser only accepts the responses to credentialed requests if they include the following CORS headers:

Access-Control-Allow-Origin set to the application origin. A wildcard (*) is refused for credentialed requests.
Access-Control-Allow-Credentials: true

Since the trace requests are sent with a Content-Type: application/json header, the proxy must also answer the CORS preflight (OPTIONS) requests. To let the exporter honor the Retry-After header of the 429 and 503 responses, the proxy must also expose it with Access-Control-Expose-Headers: Retry-After, otherwise the retries fall back to an exponential backoff.

The credentials mode can be changed with the credentials option:

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            credentials: "same-origin"
        }
    }
});

In proxy mode, only traces are sent to the proxy. The default metric and log exporters of the Honeycomb SDK are disabled. To send metrics or logs through a proxy, provide your own exporters with a transformer function.

Use an API key

Prefer using an OpenTelemetry collector with an authenticated proxy over an ingestion API key, as API keys can expose Workleap to potential attacks.

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            apiKey: "123"
        }
    }
});

Use custom instrumentations

import { initializeTelemetry } from "@workleap/telemetry/react";
import { LongTaskInstrumentation } from "@opentelemetry/instrumentation-long-task";

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            instrumentations: [
                new LongTaskInstrumentation()
            ]
        }
    }
});

Use custom span processors

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 { initializeTelemetry } from "@workleap/telemetry/react";
import { CustomSpanProcessor } from "./CustomSpanProcessor.ts";

const client = initializeTelemetry("sg", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            spanProcessors: [
                new CustomSpanProcessor()
            ]
        }
    }
});

Customize `fetchInstrumentation`

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            fetchInstrumentation: (defaultOptions) => {
                return {
                    ...defaultOptions,
                    ignoreNetworkEvents: false
                }
            }
        }
    }
});

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

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            fetchInstrumentation: false
    }
});

Customize `documentLoadInstrumentation`

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            documentLoadInstrumentation: (defaultOptions) => {
                return {
                    ...defaultOptions,
                    ignoreNetworkEvents: false
                }
            }
        }
    }
});

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

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            documentLoadInstrumentation: false
        }
    }
});

Customize `xmlHttpRequestInstrumentation`

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            xmlHttpRequestInstrumentation: (defaultOptions) => {
                return {
                    ...defaultOptions,
                    ignoreNetworkEvents: false
                }
            }
        }
    }
});

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

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            xmlHttpRequestInstrumentation: true
        }
    }
});

Customize `userInteractionInstrumentation`

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            userInteractionInstrumentation: (defaultOptions) => {
                return {
                    ...defaultOptions,
                    eventNames: ["submit", "click", "keypress"]
                }
            }
        }
    }
});

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

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            userInteractionInstrumentation: true
        }
    }
});

Use transformer functions

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 honeycomb.transformers option of the initializeTelemetry function. Remember, no locked in ❤️✌️.

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

import { initializeTelemetry, type HoneycombSdkOptionsTransformer } from "@workleap/telemetry/react";

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

    return config;
};

const client = initializeTelemetry("wlp", {
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy",
            transformers: [skipOptionsValidationTransformer]
        }
    }
});

Generic transformers can use the context argument to gather additional information about their execution context:

transformer.ts
import type { HoneycombSdkOptionsTransformer } from "@workleap/telemetry/react";

const debugTransformer: HoneycombSdkOptionsTransformer = (config, context) => {
    if (context.verbose) {
        config.debug = true;
        context.logger.debug("Debug mode has been activated.");
    }

    return config;
}

Mixpanel

Initialize with a predefined environment

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    mixpanel: {
        envOrTrackingApiBaseUrl: "development"
    }
});

Initialize with a base url

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    mixpanel: {
        envOrTrackingApiBaseUrl: "https://my-tracking-api"
    }
});

Initialize with a product id

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    mixpanel: {
        envOrTrackingApiBaseUrl: "https://my-tracking-api",
        options: {
            productId: "wlp"
        }
    }
});

Use a custom tracking endpoint

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("sg", {
    mixpanel: {
        envOrTrackingApiBaseUrl: "development",
        options: {
            trackingEndpoint: "custom/tracking/track"
        }
    }
});

Verbose mode

import { initializeTelemetry } from "@workleap/telemetry/react";

const client = initializeTelemetry("wlp", {
    logRocket: {
        appId: "my-app-id"
    },
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy"
        }
    },
    mixpanel: {
        envOrTrackingApiBaseUrl: "development"
    },
    verbose: true
});

Use loggers

import { initializeTelemetry, LogRocketLogger } from "@workleap/telemetry/react";
import { BrowserConsoleLogger, LogLevel } from "@workleap/logging";

const client = initializeTelemetry("sg", {
    logRocket: {
        appId: "my-app-id"
    },
    honeycomb: {
        namespace: "sample",
        serviceName: "my-app-name",
        apiServiceUrls: [/.+/g],
        options: {
            proxy: "https://sample-proxy"
        }
    },
    mixpanel: {
        envOrTrackingApiBaseUrl: "development"
    },
    loggers: [new BrowserConsoleLogger(), new LogRocketLogger({ logLevel: LogLevel.information })]
});

initializeTelemetry

Reference

Parameters

Returns

Initialize all telemetry platforms

LogRocket

Set a root hostname

Remove custom private fields

Remove custom query parameters

Use transformer functions

Honeycomb

Use a proxy

Use an API key

Use custom instrumentations

Use custom span processors

Customize fetchInstrumentation

Customize documentLoadInstrumentation

Customize xmlHttpRequestInstrumentation

Customize userInteractionInstrumentation

Use transformer functions

Mixpanel

Initialize with a predefined environment

Initialize with a base url

Initialize with a product id

Use a custom tracking endpoint

Verbose mode

Use loggers

See also

Customize `fetchInstrumentation`

Customize `documentLoadInstrumentation`

Customize `xmlHttpRequestInstrumentation`

Customize `userInteractionInstrumentation`