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.
        • 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.
      • options: An optional object literal of options:
        • productId: The product id.
        • trackingEndpoint: An optional tracking endpoint.
    • 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 current session credentials are automatically sent with the OTel trace requests.

Use an API key

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 })]
});