# Getting started

Prefer using the @workleap/telemetry umbrella package over this standalone library.

While we recommend using the @workleap/telemetry umbrella package, Workleap's LogRocket instrumentation can also be used as a standalone @worleap/honeycomb package.

To set it up, follow these steps 👇

# Install the packages

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

pnpm add @workleap/honeycomb @opentelemetry/api

# Register instrumentation

Then, update the application bootstrapping code to register Honeycomb instrumentation using the registerHoneycombInstrumentation function:

index.tsx
import { registerHoneycombInstrumentation, HoneycombInstrumentationProvider, createTelemetryContext } from "@workleap/honeycomb/react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

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

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

root.render(
    <StrictMode>
        <HoneycombInstrumentationProvider client={client}>
            <App />
        </HoneycombInstrumentationProvider>
    </StrictMode>
);

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.

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

# Set custom user attributes

Most applications need to set custom attributes about the current user environment on all traces. To help with that, HoneycombInstrumentationClient expose the setGlobalSpanAttributes method:

import { useHoneycombInstrumentationClient } from "@workleap/honeycomb/react";

const client = useHoneycombInstrumentationClient();

client.setGlobalSpanAttributes({
    "app.user_id": "123"
});

Now, every trace recorded after the execution of setGlobalSpanAttributes will include the custom attribute app.user_id:

# Integrate with LogRocket

Starting with version 7.0, attaching LogRocket session replays to Honeycomb traces requires providing a LogRocketInstrumentationClient to the registration function:

import { registerHoneycombInstrumentation, HoneycombInstrumentationProvider, createTelemetryContext } from "@workleap/honeycomb/react";
import { registerLogRocketInstrumentation } from "@workleap/logrocket/react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

const logRocketInstrumentationClient = registerLogRocketInstrumentation("app-id");

const honeycombInstrumentationClient = registerHoneycombInstrumentation("sample", "my-app", [/.+/g,], {
    proxy: "https://sample-proxy",
    telemetryContext: createTelemetryContext(),
    logRocketInstrumentationClient
});

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

root.render(
    <StrictMode>
        <HoneycombInstrumentationProvider client={client}>
            <App />
        </HoneycombInstrumentationProvider>
    </StrictMode>
);

# Custom traces

Applications are expected to use the OpenTelemetry API to send custom traces to Honeycomb:

src/Page.tsx
import { useEffect } from "react";
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("sample");

export function Page() {
    useEffect(() => {
        // OK, this is a pretty bad example.
        const span = tracer.startSpan("sample-span");
        span.end();
    }, []);

    return (
        <div>Hello from a page!</div>
    );
}

# Try it 🚀

Start the application in a development environment using the dev script. Render a page, then navigate to your Honeycomb instance. Go to the "Query" page and type name = HTTP GET into the "Where" input. Run the query, select the "Traces" tab at the bottom of the page and view the detail of a trace. You should view information about the request.

# Troubleshoot issues

If you are experiencing issues with this guide:

Set the verbose predefined option to true.
Open the DevTools console. Look for logs starting with [honeycomb].
You should also see a log entry for every Honeycomb traces.
- honeycombio/opentelemetry-web: Honeycomb link: https://ui.honeycomb.io/...
Refer to the sample on GitHub.