# Getting started

Welcome to workleap/telemetry, a collection of telemetry libraries for building web applications at Workleap. On this getting started page, you'll find an overview of the project and a list of supported platforms.

# An integrated experience

Without a unified and cohesive telemetry setup, debugging issues or analyzing product behavior often requires jumping between tools with disconnected data. Session replays in LogRocket, traces in Honeycomb, and user events in Mixpanel each offer valuable insights, but without shared identifiers or cross-platform context, it becomes difficult to correlate events, reconstruct user journeys, or measure the full impact of a technical issue in production.

This integrated experience brings together LogRocket, Honeycomb, and Mixpanel. By linking session data, performance traces, and user interactions through consistent identifiers. It becomes possible to trace a single application event across systems, from backend performance to frontend behavior to product impact. This integration streamlines will hopefully enables faster, and more informed decision-making.

# Supported platforms

Name	Description	Documentation
LogRocket	Records frontend sessions and logs to help debug and resolve issues in production and surface critical issues.	Getting started
Honeycomb	Captures and analyzes distributed traces and metrics to understand and monitor complex systems, application behaviors, and performance.	Getting started
Mixpanel	Tracks user interactions to analyze behavior and measure product impact.	Getting started
Common Room	Connects user activity across platforms to provide insight into community engagement and behavior. (Common Room is not part of the integrated experience, as it is a standalone tool used by marketers for a completely different purpose.)	Getting started

# Setup a project

First, open a terminal at the root of the application and install the telemetry libraries packages:

pnpm add @workleap/logrocket @workleap/honeycomb @workleap/mixpanel @opentelemetry/api logrocket

Then, update the application bootstrapping code to initialize the libraries:

index.tsx
import { registerLogRocketInstrumentation } from "@workleap/logrocket";
import { registerHoneycombInstrumentation } from "@workleap/honeycomb";
import { initializeMixpanel } from "@workleap/mixpanel";
import { registerCommonRoomInstrumentation } from "@workleap/common-room";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

registerLogRocketInstrumentation("my-app-id", {});

registerHoneycombInstrumentation("sample", "my-app", [/.+/g,], {
    proxy: "https://sample-proxy"
});

initializeMixpanel("wlp", "development");

registerCommonRoomInstrumentation("my-site-id");

const root = createRoot(document.getElementById("root")!);

root.render(
    <StrictMode>
        <App />
    </StrictMode>
);

import { useTrackingFunction } from "@workleap/mixpanel/react";

// If the host application is not a React application, use
// "createTrackingFunction" instead of the following hook.
const track = useTrackingFunction();

For more information about a specific library, refer to its getting started guide.

For Honeycomb, avoid using /.+/g, in production, as it could expose customer data to third parties. Instead, ensure you specify values that accurately matches your application's backend URLs.

# Correlation ids

Each library sends the same two correlation id values to its respective platform, using platform-specific naming conventions for the names:

Correlation id	Description	LogRocket	Honeycomb	Mixpanel
Telemetry id	Identifies a single application load. It's primarily used to correlate all telemetry platforms with Honeycomb traces.	`Telemetry Id`	`app.telemetry_id`	`Telemetry Id`
Device id	Identifies the user's device across sessions.	`Device Id`	`app.device_id`	`Device Id`

# Troubleshooting example

The following is an example of a troubleshooting workflow using the new telemetry correlation id:

Honeycomb: Locate the app.telemetry_id attribute in a trace to retrieve its value.
LogRocket: Navigate to the "Session Replay" page. Open the "User Traits" filter, select the Telemetry Id trait, paste the app.telemetry_id value, and press "Enter" to view the matching sessions.
Mixpanel: Navigate to the "Events" page. Add a "filter", select the Telemetry Id propertt, paste the app.telemetry_id value, and press on the "Add" button to view the matching events.

This feature is available only when using the following package versions or higher:

@workleap/logrocket ≥ 1.0.0
@workleap/honeycomb ≥ 6.0.0
@workleap/mixpanel ≥ 2.0.0

If your application is using older versions, refer to the migration guide to update.

# LogRocket session URL

In addition to the correlation ids, if LogRocket instrumentation is initialized, the Honeycomb and Mixpanel libraries will automatically enrich their data with the LogRocket session URL once it's available:

Honeycomb	Mixpanel
`app.logrocket_session_url`	`LogRocket Session URL`

This feature is available only when using the following package versions or higher:

@workleap/logrocket ≥ 1.0.0
@workleap/honeycomb ≥ 6.0.0
@workleap/mixpanel ≥ 2.0.0

If your application is using older versions, refer to the migration guide to update.

# Set up loggers

Providing loggers to the registration and initialization functions is optional, but recommended to simplify troubleshooting.

index.tsx
import { registerLogRocketInstrumentation, LogRocketLogger } from "@workleap/logrocket";
import { BrowserConsoleLogger, LogLevel, type RootLogger } from "@workleap/logging";
import { registerHoneycombInstrumentation } from "@workleap/honeycomb";
import { initializeMixpanel } from "@workleap/mixpanel";
import { registerCommonRoomInstrumentation } from "@workleap/common-room";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

...

// Only add LogRocket logger if your product is set up with LogRocket.
const loggers: RootLogger[] = [isDev ? new BrowserConsoleLogger() : new LogRocketLogger({ logLevel: LogLevel.information })];

registerLogRocketInstrumentation("my-app-id", {
    verbose: isDev,
    loggers
});

registerHoneycombInstrumentation("sample", "my-app", [/.+/g,], {
    proxy: "https://sample-proxy",
    verbose: isDev
    loggers
});

initializeMixpanel("wlp", "development", {
    verbose: isDev
    loggers
});

registerCommonRoomInstrumentation("my-site-id", {
    verbose: isDev
    loggers
});

const root = createRoot(document.getElementById("root")!);

root.render(
    <StrictMode>
        <App />
    </StrictMode>
);

To troubleshoot an issue in production, remove the LogLevel from the LogRocketLogger constructor options and set the verbose option to true:

index.tsx
import { registerLogRocketInstrumentation, LogRocketLogger } from "@workleap/logrocket";
import { BrowserConsoleLogger, type RootLogger } from "@workleap/logging";
import { registerHoneycombInstrumentation } from "@workleap/honeycomb";
import { initializeMixpanel } from "@workleap/mixpanel";
import { registerCommonRoomInstrumentation } from "@workleap/common-room";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

...

const loggers: RootLogger[] = [isDev ? new BrowserConsoleLogger() : new LogRocketLogger()];

registerLogRocketInstrumentation("my-app-id", {
    verbose: true,
    loggers
});

registerHoneycombInstrumentation("sample", "my-app", [/.+/g,], {
    proxy: "https://sample-proxy",
    verbose: true
    loggers
});

initializeMixpanel("wlp", "development", {
    verbose: true
    loggers
});

registerCommonRoomInstrumentation("my-site-id", {
    verbose: true
    loggers
});

const root = createRoot(document.getElementById("root")!);

root.render(
    <StrictMode>
        <App />
    </StrictMode>
);

# Migrate

To benefit from the new unified and cohesive telemetry setup, follow the migration guide.