1. Docs
2. Send Data to Honeycomb
3. Browser JavaScript
4. Browser Data with Honeycomb Web Instrumentation

Send Browser Data with Honeycomb Web Instrumentation

Table of Contents

Honeycomb provides the Honeycomb Web Instrumentation package to help you instrument your applications and send browser data to Honeycomb as quickly and easily as possible. Under the hood, the Honeycomb Web Instrumentation package uses OpenTelemetry for JavaScript.

Although automatic instrumentation for the web exists, you will get the most value by supplementing automatically-generated instrumentation in your application with custom spans and events. To add custom spans and events, which is known as custom instrumentation, use the full OpenTelemetry API.

If you prefer to learn by example, we provide several examples that configure applications to send OpenTelemetry data to Honeycomb.

Why Use the Honeycomb Web Instrumentation package? 

Honeycomb’s Web Instrumentation package gives you all of the capabilities provided by the generic OpenTelemetry Distribution for JavaScript and also allows you to:

• more easily initialize OpenTelemetry for use with Honeycomb
• more easily add multi-span attributes
• more easily configure sampling
• link directly to your traces in Honeycomb with local visualizations
• keep any custom instrumentation if you switch to the generic OpenTelemetry Distribution later
• add automatic instrumentation for Core Web Vitals and customize attributes on those spans

Before You Begin 

Before you can set up instrumentation for your application, you will need to do a few things.

Get Your Honeycomb API Key 

To send data to Honeycomb, you need to:

1. Sign up for a free Honeycomb account. To sign up, decide whether you would like Honeycomb to store your data in a US-based or EU-based location, then create a Honeycomb account in the US or create a Honeycomb account in the EU. Signup is free!
2. Create a Honeycomb Ingest API Key. To get started, you can create a key that you expect to swap out when you deploy to production. Name it something helpful, perhaps noting that it’s a Getting Started key. Make note of your API key; for security reasons, you will not be able to see the key again, and you will need it later!

Install the Honeycomb Web Instrumentation Package 

We make our Honeycomb Web Instrumentation package available as an NPM package, so you can include it in your web bundle.

Navigate to the root directory of your service’s repo, and then install the package:

npm install @honeycombio/opentelemetry-web '@opentelemetry/auto-instrumentations-web'

yarn add @honeycombio/opentelemetry-web '@opentelemetry/auto-instrumentations-web'

Alternatively, install individual instrumentation packages.

Finally, confirm that the install was successful by opening your package.json file and checking that the Dependencies list now contains @honeycomb/opentelemetry-web.

Configuration Options for Browser Telemetry 

Before adding automatic instrumentation to your application for browser telemetry, choose from the following options to decide how you will send data to Honeycomb. Consider the security aspects of each option.

// index.js or main.js

// other import statements...
import { HoneycombWebSDK } from '@honeycombio/opentelemetry-web';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';

const configDefaults = {
  ignoreNetworkEvents: true,
  // propagateTraceHeaderCorsUrls: [
  // /.+/g, // Regex to match your backend URLs. Update to the domains you wish to include.
  // ]
}

const sdk = new HoneycombWebSDK({
  // endpoint: "https://api.eu1.honeycomb.io/v1/traces", // Send to EU instance of Honeycomb. Defaults to sending to US instance.
  debug: true, // Set to false for production environment.
  apiKey: '[YOUR API KEY HERE]', // Replace with your Honeycomb Ingest API Key.
  serviceName: '[YOUR APPLICATION NAME HERE]', // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  instrumentations: [getWebAutoInstrumentations({
    // Loads custom configuration for xml-http-request instrumentation.
    '@opentelemetry/instrumentation-xml-http-request': configDefaults,
    '@opentelemetry/instrumentation-fetch': configDefaults,
    '@opentelemetry/instrumentation-document-load': configDefaults,
  })],
});
sdk.start();

// application instantiation code

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
        cors:
          allowed_origins:
            - "http://*.<yourdomain>.com"
            - "https://*.<yourdomain>.com"

processors:
  batch:

exporters:
  otlp:
    endpoint: "api.honeycomb.io:443" # US instance
    #endpoint: "api.eu1.honeycomb.io:443" # EU instance
    headers:
      "x-honeycomb-team": "YOUR_API_KEY"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

// index.js or main.js

// other import statements...
import { HoneycombWebSDK } from '@honeycombio/opentelemetry-web';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';

const configDefaults = {
  ignoreNetworkEvents: true,
  // propagateTraceHeaderCorsUrls: [
  // /.+/g, // Regex to match your backend URLs. Update to the domains you wish to include.
  // ]
}

const sdk = new HoneycombWebSDK({
  debug: true, // turn off in production
  serviceName: '[YOUR APPLICATION NAME HERE]', // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  endpoint: '[YOUR COLLECTOR URL]',
  instrumentations: [getWebAutoInstrumentations({
    // Loads custom configuration for xml-http-request instrumentation.
    '@opentelemetry/instrumentation-xml-http-request': configDefaults,
    '@opentelemetry/instrumentation-fetch': configDefaults,
    '@opentelemetry/instrumentation-document-load': configDefaults,
  })],
});
sdk.start();

// application instantiation code

// index.js or main.js

// other import statements...
import { HoneycombWebSDK } from '@honeycombio/opentelemetry-web';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';

const configDefaults = {
  ignoreNetworkEvents: true,
  // propagateTraceHeaderCorsUrls: [
  // /.+/g, // Regex to match your backend URLs. Update to the domains you wish to include.
  // ]
}

const sdk = new HoneycombWebSDK({
  debug: true, // Set to false for production environment.
  serviceName: '[YOUR APPLICATION NAME HERE]', // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  endpoint: '[YOUR PROXY ENDPOINT HERE]',
  instrumentations: [getWebAutoInstrumentations({
    // Loads custom configuration for xml-http-request instrumentation.
    '@opentelemetry/instrumentation-xml-http-request': configDefaults,
    '@opentelemetry/instrumentation-fetch': configDefaults,
    '@opentelemetry/instrumentation-document-load': configDefaults,
  })],
});
sdk.start();

// application instantiation code

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-honeycomb-team': process.env.HONEYCOMB_API_KEY,
  },
  body: JSON.stringify(otlpJsonExportedFromFrontend),
};

// frontend.js
const sdk = new HoneycombWebSDK({
  endpoint: "http://localhost:3000/v1/traces",
  serviceName: "your-service-name",
  instrumentations: [getWebAutoInstrumentations()],
})

// backend.js
import { config } from 'dotenv';
import express from 'express';
import fetch from 'node-fetch';
import cors from 'cors';

const app = express();
const port = 3000;

app.use(
  cors({
    origin: ['http://localhost:5000', 'http://127.0.0.1:5000'],
    methods: ['POST'],
    credentials: true,
  }),
);
// Allow parsing of json
app.use(express.json());

// our api relay route
app.post('/v1/traces', async (req, res) => {
  try {
    const otlpJsonExportedFromFrontend = await req.body;

    const options = {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-honeycomb-team': process.env.HONEYCOMB_API_KEY,
      },
      body: JSON.stringify(otlpJsonExportedFromFrontend),
    };

    // sending on to Honeycomb
    const response = await fetch('https://api.honeycomb.io/v1/traces', options) // US instance
    //const response = await fetch('https://api.eu1.honeycomb.io/v1/traces', options) // EU instance
      .then((response) => console.log(response))
      .catch((err) => console.error(err));

    return res.json({
      success: true,
      response,
    });
  } catch (err) {
    return res.status(500).json({
      success: false,
      message: err.message,
    });
  }
});

app.listen(port, () => console.log(`Server listening on port ${port}!`));

Advanced Configuration 

This is the complete list of configuration options for the Honeycomb Web Instrumentation package.

WebVitalsInstrumentationConfig 

GlobalErrorsInstrumentationConfig 

Network Events and Telemetry Volume 

In the Honeycomb Web Instrumentation, we pass in the ignoreNetworkEvents: true configuration to all automatic instrumentation packages. This configuration option reduces the number of events emitted from OpenTelemetry by about 90%. This configuration also means you do not collect network timing for all network requests, such as domainLookup, requestStart, requestEnd, and so on.

IgnoreNetworkEvents defaults to false. If you wish to collect timing events, you can remove the ignoreNetworkEvents: true call for one or all of the instrumentations that the configDefaults object is passed into, similar to the below example:

  // Turn on for fetch requests only.

  const configDefaults = {
    ignoreNetworkEvents: true, // <- no change
    // propagateTraceHeaderCorsUrls: [
    // /.+/g, // Regex to match your backend URLs. Update to the domains you wish to include.
    // ]
  }

  instrumentations: [getWebAutoInstrumentations({
    // Loads custom configuration for xml-http-request instrumentation.
    '@opentelemetry/instrumentation-xml-http-request': configDefaults,
    // '@opentelemetry/instrumentation-fetch': configDefaults,
    '@opentelemetry/instrumentation-document-load': configDefaults,
  })],

  /**************************************/
  // Turn on for all requests.

  const configDefaults = {
    ignoreNetworkEvents: false, // <- Changed from true
    // propagateTraceHeaderCorsUrls: [
    // /.+/g, // Regex to match your backend URLs. Update to the domains you wish to include.
    // ]
  }

  instrumentations: [getWebAutoInstrumentations({
    // Loads custom configuration for xml-http-request instrumentation.
    '@opentelemetry/instrumentation-xml-http-request': configDefaults,
    '@opentelemetry/instrumentation-fetch': configDefaults,
    '@opentelemetry/instrumentation-document-load': configDefaults,
  })],

Add Application-Specific Resource Attributes 

To optimize your data collection, we recommend that you add custom attributes that are specific to your application to every span. You can specify extra attributes through the resourceAttributes configuration option. This data will be available on every span your instrumentation emits, which makes it easier to correlate your data to important business information.

// index.js or main.js

// other import statements...
import { HoneycombWebSDK } from '@honeycombio/opentelemetry-web';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';

const configDefaults = {
  ignoreNetworkEvents: true,
  // propagateTraceHeaderCorsUrls: [
  // /.+/g, // Regex to match your backend URLs. Update to the domains you wish to include.
  // ]
}

const sdk = new HoneycombWebSDK({
  // endpoint: "https://api.eu1.honeycomb.io/v1/traces", // Send to EU instance of Honeycomb. Defaults to sending to US instance.
  debug: true, // Set to false for production environment.
  apiKey: '[YOUR API KEY HERE]', // Replace with your Honeycomb Ingest API Key.
  serviceName: '[YOUR APPLICATION NAME HERE]', // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  instrumentations: [getWebAutoInstrumentations({
    // Loads custom configuration for xml-http-request instrumentation.
    '@opentelemetry/instrumentation-xml-http-request': configDefaults,
    '@opentelemetry/instrumentation-fetch': configDefaults,
    '@opentelemetry/instrumentation-document-load': configDefaults,
  })],
  resourceAttributes: { // Data in this object is applied to every trace emitted.
    "user.id": user.id, // Specific to your app.
    "user.role": user.role, // Specific to your app.
  },
});
sdk.start();

// Application instantiation code

Connecting the Frontend and Backend Traces 

You can connect your frontend request traces to your backend traces, which allows you to trace a request all the way from your browser through your distributed system. To connect your frontend traces to your backend traces, you must include the trace context header in the request. You can do this using either automatic instrumentation or manual instrumentation.

Automatically Propagate the Trace Context Header 

Use request automatic instrumentation to automatically send spans for every HTTP request. @opentelemetry/instrumentation-xml-http-request automatically instruments XHR requests and @opentelemetry/instrumentation-fetch automatically instruments fetch requests. If your browser application uses a request library to make requests, such as axios or superagent, these requests are also automatically instrumented by enabling the xml-http-request or fetch instrumentation, depending on what the library uses to make requests.

When using the Honeycomb Instrumentation snippet (as documented on this page), uncomment the propagateTraceHeaderCorsUrls array and add regex to include all target domains. This method allows you to propagate to your backend services without leaking trace IDs to third-party services.

const configDefaults = {
  ignoreNetworkEvents: true,
  propagateTraceHeaderCorsUrls: [
    /.+/g, // Regex to match your backend URLs. Update to the domains you wish to include.
  ]
}

Manually Propagate the Trace Context Header 

It is also possible to manually propagate the trace context header if automatic instrumentation is not an option:

// General request handler, instrumented with OTel
// Forwards traceparent header to connect spans created in the browser
// with spans created on the backend
const request = async (url, method = 'GET', headers, body) => {
  return trace
    .getTracer('request-tracer')
    .startActiveSpan(`Request: ${method} ${url}`, async (span) => {

      // construct W3C traceparent header
      const traceparent = `00-${span.spanContext().traceId}-${span.spanContext().spanId}-01`;

      try {
        const response = await fetch(url, {
          method,
          headers: {
            ...headers,
            // set traceparent header
            traceparent: traceparent,
          },
          body,
        });
        span.setAttributes({
          'http.method': method,
          'http.url': url,
          'response.status_code': response.status,
        });
        if (response.ok && response.status >= 200 && response.status < 400) {
          span.setStatus({ code: SpanStatusCode.OK });
          return response.text();
        } else {
          throw new Error(`Request Error ${response.status} ${response.statusText}`);
        }
      } catch (error) {
        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
        throw new Error(error);
      } finally {
        span.end();
      }
    });
};

Other Automatic Instrumentation 

There are several automatic instrumentation libraries available for the browser. They tend to produce a lot of span events so we recommend adding them with some caution.

npm install --save \
    @opentelemetry/instrumentation-user-interaction \
    @opentelemetry/instrumentation-long-task

yarn add \
    @opentelemetry/instrumentation-user-interaction \
    @opentelemetry/instrumentation-long-task

User Interaction 

@opentelemetry/instrumentation-user-interaction produces spans for user interactions with a browser web application. Import the package and add the output to the instrumentations array in the configuration:

import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';

const sdk = new HoneycombWebSDK({
  apiKey: '[YOUR API KEY HERE]', // Replace with your Honeycomb Ingest API Key.
  serviceName: '[YOUR APPLICATION NAME HERE]' // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  instrumentations: [getWebAutoInstrumentations({
      // Loads custom configuration for xml-http-request instrumentation.
      '@opentelemetry/instrumentation-xml-http-request': configDefaults,
      '@opentelemetry/instrumentation-fetch': configDefaults,
      '@opentelemetry/instrumentation-document-load': configDefaults,
    }),

    new UserInteractionInstrumentation(),
  ],
});

sdk.start();

By default, only click events are automatically instrumented. To automatically instrument other events, specify the events that should be captured for telemetry. Most browser events are supported.

import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';

const sdk = new HoneycombWebSDK({
  apiKey: '[YOUR API KEY HERE]', // Replace with your Honeycomb Ingest API Key.
  serviceName: '[YOUR APPLICATION NAME HERE]' // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  instrumentations: [getWebAutoInstrumentations({
      // Loads custom configuration for xml-http-request instrumentation.
      '@opentelemetry/instrumentation-xml-http-request': configDefaults,
      '@opentelemetry/instrumentation-fetch': configDefaults,
      '@opentelemetry/instrumentation-document-load': configDefaults,
    }),

    new UserInteractionInstrumentation({
      eventNames: ['submit', 'click', 'keypress'],
    }),
  ],
});

sdk.start();

To attach extra attributes to user interaction spans, provide a callback function:

import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';

const sdk = new HoneycombWebSDK({
  apiKey: '[YOUR API KEY HERE]', // Replace with your Honeycomb Ingest API Key.
  serviceName: '[YOUR APPLICATION NAME HERE]' // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  instrumentations: [getWebAutoInstrumentations({
      // Loads custom configuration for xml-http-request instrumentation.
      '@opentelemetry/instrumentation-xml-http-request': configDefaults,
      '@opentelemetry/instrumentation-fetch': configDefaults,
      '@opentelemetry/instrumentation-document-load': configDefaults,
    }),

    new UserInteractionInstrumentation({
      eventNames: ['submit', 'click', 'keypress'],
      shouldPreventSpanCreation: (event, element, span) => {
        span.setAttribute('target.id', element.id)
        // etc..
      }
    }),
  ],
});

sdk.start();

Long Tasks 

@opentelemetry/instrumentation-long-task provides automatic instrumentation for Long Task API.

import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';

const sdk = new HoneycombWebSDK({
  apiKey: '[YOUR API KEY HERE]', // Replace with your Honeycomb Ingest API Key.
  serviceName: '[YOUR APPLICATION NAME HERE]' // Replace with your application name. Honeycomb uses this string to find your dataset when we receive your data. When no matching dataset exists, we create a new one with this name if your API Key has the appropriate permissions.
  instrumentations: [getWebAutoInstrumentations({
      // Loads custom configuration for xml-http-request instrumentation.
      '@opentelemetry/instrumentation-xml-http-request': configDefaults,
      '@opentelemetry/instrumentation-fetch': configDefaults,
      '@opentelemetry/instrumentation-document-load': configDefaults,
    }),

    new LongTaskInstrumentation({
      observerCallback: (span, longtaskEvent) => {
        span.setAttribute('location.pathname', window.location.pathname)
      }
    }),
  ],
});

sdk.start();

Add Custom Instrumentation 

Automatic instrumentation is the easiest way to get started with instrumenting your code, but to get the most insight into your system, you should add custom, or manual, instrumentation where appropriate. To do this, use the OpenTelemetry API to access the currently executing span and add attributes to it, and/or to create new spans.

To learn more about custom, or manual, instrumentation, visit the comprehensive set of topics covered by Manual Instrumentation for JavaScript in OpenTelemetry’s documentation.

Acquire Dependencies 

Adding custom instrumentation requires the the OpenTelemetry API package. If not installed yet, use this command for installation:

npm install --save @opentelemetry/api

yarn add @opentelemetry/api

To customize your instrumentation, you need to add instrumentation for actions. Refer to the sample code below that instruments the window load event and a button:

import { trace, context, } from '@opentelemetry/api';

const tracer = trace.getTracer();

const rootSpan = tracer.startActiveSpan('document_load', span => {
  //start span when navigating to page
  span.setAttribute('pageUrlwindow', window.location.href);
  window.onload = (event) => {
    // ... do loading things
    // ... attach timing information
    span.end(); //once page is loaded, end the span
  };

  button.clicked = (event) => {
    tracer.startActiveSpan('button_clicked', btnSpan => {
      // Add your attributes to describe the button clicked here
      btnSpan.setAttribute('some.attribute', 'some.value');

      btnSpan.end();
    });
  }
});

Add Attributes to Spans 

Adding attributes to a currently executing span in a trace can be useful. For example, you may have an application or service that handles users, and you want to associate the user with the span when querying your service in Honeycomb. To do this, get the current span from the context and set an attribute with the user ID:

import opentelemetry from '@opentelemetry/api';

function handleUser(user: User) {
  let activeSpan = opentelemetry.trace.getActiveSpan();
  activeSpan.setAttribute("user.id", user.getId());
}

const opentelemetry = require("@opentelemetry/api");

function handleUser(user) {
  let activeSpan = opentelemetry.trace.getActiveSpan();
  activeSpan.setAttribute("user.id", user.getId());
}

This will add a user.id field to the current span so that you can use the field in WHERE, GROUP BY or ORDER clauses in the Honeycomb query builder.

Initialize a Tracer 

To start manually tracing, you must initialize a tracer.

import opentelemetry from '@opentelemetry/api';

const tracer = opentelemetry.trace.getTracer("tracer.name.here");

const opentelemetry = require("@opentelemetry/api");

const tracer = opentelemetry.trace.getTracer("tracer.name.here");

When you create a Tracer, OpenTelemetry requires you to give it a name as a string. This string is the only required parameter.

When traces are sent to Honeycomb, the name of the Tracer is turned into the library.name field, which can be used to show all spans created from a particular tracer.

In general, pick a name that matches the appropriate scope for your traces. If you have one tracer for each service, then use the service name. If you have multiple tracers that live in different “layers” of your application, then use the name that corresponds to that “layer”.

The library.name field is also used with traces created from instrumentation libraries.

You can then use this tracer to create custom spans.

Create New Spans 

Automatic instrumentation can show the shape of requests to your system, but only you know the truly important parts. To get the full picture of what is happening, you must add custom instrumentation and create some custom spans. To do this, grab the tracer from the OpenTelemetry API:

import opentelemetry from '@opentelemetry/api';

const tracer = opentelemetry.trace.getTracer("my-service-tracer");

function runQuery() {
  tracer.startActiveSpan("expensive-query", (span) => {
    // ... do cool stuff
    span.end();
  });
}

const opentelemetry = require("@opentelemetry/api");

const tracer = opentelemetry.trace.getTracer("my-service-tracer");

function runQuery() {
  tracer.startActiveSpan("expensive-query", (span) => {
    // ... do cool stuff
    span.end();
  });
}

Add Multi-Span Attributes 

Sometimes you want to add the same attribute to many spans within the same trace. This attribute may include variables calculated during your program, or other useful values for correlation or debugging purposes.

To add this attribute, leverage the OpenTelemetry concept of baggage. Baggage allows you to add a key with a value as an attribute to every subsequent child span within the current application context.

import {
  Context,
  context,
  propagation,
} from '@opentelemetry/api';

tracer.startActiveSpan('main', (span) => {
  span.setAttribute('app.username', name); // add to current span

  // new context based on current, with key/values added to baggage
  const ctx: Context = propagation.setBaggage(
    context.active(),
    propagation.createBaggage({ 'app.username': { value: name } })
  );

  // within the new context, do some work and baggage will be
  // applied as attributes on child spans
  context.with(ctx, () => {
    tracer.startActiveSpan('childSpan', (childSpan) => {
      doTheWork();
      childSpan.end();
    });
  });

  span.end();
});

tracer.startActiveSpan('main', (span) => {
  span.setAttribute('app.username', name); // add to current span

  // new context based on current, with key/values added to baggage
  const ctx = propagation.setBaggage(
    context.active(),
    propagation.createBaggage({ 'app.username': { value: name } })
  );

  // within the new context, do some work and baggage will be
  // applied as attributes on child spans
  context.with(ctx, () => {
    tracer.startActiveSpan('childSpan', (childSpan) => {
      doTheWork();
      childSpan.end();
    });
  });

  span.end();
});

Custom Span Processing 

The OpenTelemetry SDK uses span processors as synchronous hooks for when a span starts and when a span ends. This lets you mutate spans after they have been created by automatic instrumentation or manually. Some examples of the actions you can take on spans in a span processor include:

• Add attributes
• Add span events
• Add span links
• Update the name of a span
• Record an exception on a span
• Get the span context to create child spans
• Stop spans from being sent

Example: Basic Custom Span Processor 

Here is a basic example of a custom span processor:

class TestSpanProcessorOne implements SpanProcessor {
  onStart(span: Span): void {
    span.setAttributes({
      'processor1.name': 'TestSpanProcessorOne',
    });
  }

  onEnd(): void {}

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

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

To use it, add the span processor to your configuration when you initialize the Honeycomb Web SDK:

const sdk = new HoneycombWebSDK({
  debug: true,
  apiKey: 'api-key-goes-here',
  serviceName: 'hny-web-distro',
  // ... other config
  spanProcessors: [new TestSpanProcessorOne()],
});

sdk.start();

Example: Adding User Information After SDK Initialization 

Here is an example span processor that adds custom information for users:

import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
import { Span } from '@opentelemetry/api';

export class UserInfoSpanProcessor implements SpanProcessor {
  userInfo: { userId: string; customerId: string; role: string } | undefined;
  constructor() {
    const getUserInfo = (): Promise<{
      userId: string;
      customerId: string;
      role: string;
    }> => {
      return new Promise((resolve) => {
        setTimeout(() => {
          resolve({
            userId: '1234',
            customerId: '5678',
            role: 'admin',
          });
        }, 2000);
      });
    };

    getUserInfo().then(
      (userInfo: { userId: string; customerId: string; role: string }) => {
        this.userInfo = userInfo;
      },
    );
  }

  onStart(span: Span) {
    if (this.userInfo) {
      span.setAttributes({
        'app.user.id': this.userInfo.userId,
        'app.user.customer_id': this.userInfo.customerId,
        'app.user.role': this.userInfo.role,
      });
    }
  }

  onEnd() {}

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

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

To use it, add the span processor to your configuration when you initialize the Honeycomb Web SDK:

const sdk = new HoneycombWebSDK({
  debug: true,
  apiKey: 'api-key-goes-here',
  serviceName: 'hny-web-distro',
  // ... other configuration
  spanProcessors: [new UserInfoSpanProcessor()],
});

sdk.start();

Example: Dynamic page routes with React Router 

Here is an example span processor that adds attributes to spans based on the state of the React Router. It sets the page.route attribute to the generic dynamic route, and records the span as an error if there are errors in the router state.

import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
import { Span } from '@opentelemetry/api';

/**
 * SpanProcessor that adds attributes to spans based on the state of the React Router
 * Sets the page.route attribute to the generic dynamic route
 * Records the span as an error if there are errors in the router state (e.g. 404)
 */
export class ReactRouterSpanProcessor implements SpanProcessor {
  router;
  route;
  constructor({ router }: { router }) {
    this.router = router;
    this.route =
      router.state.matches[router.state.matches.length - 1]?.route.path;

    this.router.subscribe((state: any) => {
      this.route = state.matches[state.matches.length - 1]?.route.path;
    });
  }

  onStart(span: Span) {
    const { errors } = this.router.state;

    // If there are errors, set the span status to error and record the error message
    if (errors !== null) {
      span.setStatus({
        code: 2,
        message: errors[0].data,
      });
    }

    // Set the page.route as the generic dynamic route, making things easier to query
    // e.g. /name/:name/pet/:pet instead of name/123/pet/456
    // url.path attribute will have the more specific computed route
    span.setAttributes({ 'page.route': this.route });
  }

  onEnd() {}

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

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

To use it, add the span processor to your configuration when you initialize the Honeycomb Web SDK:

const sdk = new HoneycombWebSDK({
  debug: true,
  apiKey: 'api-key-goes-here',
  serviceName: 'hny-web-distro',
  // ... other configuration
  spanProcessors: [new ReactRouterSpanProcessor({ router: router })],
});

sdk.start();

Sampling 

Deterministic head sampling can be used with the Honeycomb Web Instrumentation package, with or without manual instrumentation.

The package will read these variables and expect an integer that represents the sample rate you would like to apply. For example, a value of 5 means that one out of every five traces will be sent to Honeycomb.

To add sampling to the package, add sampleRate to the HoneycombWebSDK:

const sdk = new HoneycombWebSDK({
  apiKey: "your-api-key",
  serviceName: "your-service-name",
  instrumentations: [getWebAutoInstrumentations()],
  sampleRate: 5,
})

The value of your sample rate must be a positive integer.

If you have multiple services that communicate with each other, it is important that they have the same sampling configuration. Otherwise, each service might make a different sampling decision, resulting in incomplete or broken traces. You can sample using a standalone proxy as an alternative, like Honeycomb Refinery, or when you have more robust sampling needs.

Distributed Trace Propagation 

When a service calls another service, you want to ensure that the relevant trace information is propagated from one service to the other. This allows Honeycomb to connect the two services in a trace.

Distributed tracing enables you to trace and visualize interactions between multiple instrumented services. For example, your users may interact with a front-end API service, which talks to two internal APIs to fulfill their request. In order to have traces connect spans for all these services, it is necessary to propagate trace context between these services, usually by using an HTTP header.

Both the sending and receiving service must use the same propagation format, and both services must be configured to send data to the same Honeycomb environment.

Note: Any Baggage attributes that you set in your application will be attached to outgoing network requests as a header. If your service communicates to a third party API, do NOT put sensitive information in the Baggage attributes.

Trace context propagation is done by sending and parsing headers that conform to the W3C Trace Context specification.

By default, the Honeycomb’s Web Instrumentation package uses the W3C trace context format.

If you opt to use a different trace context specification than W3C, ensure that both the sending and receiving service are using the same propagation format, and that both services are configured to send data to the same Honeycomb environment.

Visualizing Traces Locally 

Honeycomb’s Web Instrumentation package can create a link to a trace visualization in the Honeycomb UI for local traces. Local visualizations enables a faster feedback cycle when adding, modifying, or verifying instrumentation.

To enable local visualizations:

1. Set the local visualizations option to true in the HoneycombWebSDK:

   const sdk = new HoneycombWebSDK({
     apiKey: "your-api-key",
     serviceName: "your-service-name",
     instrumentations: [getWebAutoInstrumentations()],
     localVisualizations: true,
   })
   

   The output displays the name of the root span and a link to Honeycomb that shows its trace. For example:

   Trace for root-span-name
   Honeycomb link: <link to Honeycomb trace>
   

2. Select the link to view the trace in detail within the Honeycomb UI.

Debug Mode 

To enable debugging when running the Honeycomb Web Instrumentation package, set debug to true the HoneycombWebSDK:

const sdk = new HoneycombWebSDK({
  apiKey: "your-api-key",
  serviceName: "your-service-name",
  instrumentations: [getWebAutoInstrumentations()],
  localVisualizations: true,
  debug: true
})

When the debug setting is enabled, the Honeycomb Web Instrumentation package configures a DiagConsoleLogger that logs telemetry to the console with the log level of Debug.

The debug setting in the Honeycomb Web Instrumentation package will also output to the console the main options configuration, including but not limited to API Key and endpoint.

Keep in mind that printing to the console is not recommended for production and should only be used for debugging purposes.

OTLP Protobuf Definitions 

Honeycomb supports receiving telemetry data via OpenTelemetry’s native protocol, OTLP, over gRPC, HTTP/protobuf, and HTTP/JSON. The minimum supported versions of OTLP protobuf definitions are 1.0 for traces, metrics, and logs.

If the protobuf version in use by the SDK does not match a supported version by Honeycomb, a different version of the SDK may need to be used. If the SDK’s protobuf version is older than the minimum supported version, and telemetry is not appearing as expected in Honeycomb, upgrade the SDK to a version with the supported protobuf definitions. If using an added dependency on a proto library, ensure the version of protobuf definitions matches the supported version of the SDK.

Receiving 464 Errors 

You may receive a 464 error response from the Honeycomb API when sending telemetry using gRPC and HTTP1. The gRPC format depends on using HTTP2 and any request over HTTP1 will be rejected by the Honeycomb servers.

Troubleshooting 

To explore common issues when sending data, visit Common Issues with Sending Data in Honeycomb.

Dataset Not Appearing in Honeycomb 

The apiKey variable is used to send your data to Honeycomb. Make sure you have replaced the placeholder value for it with your Honeycomb Ingest API Key and that your API key permissions include “Can create datasets”.

If Honeycomb is successfully instantiating but your API key is not included, you should see output similar to the following in your browser console:

@opentelemetry/api: Registered a global for diag v1.7.0
@honeycombio/opentelemetry-web: Honeycomb Web SDK Debug Mode Enabled
@honeycombio/opentelemetry-web: API Key configured for traces: '<YOUR_API_KEY>'
@honeycombio/opentelemetry-web: Service Name configured for traces: '<YOUR_SERVICE_NAME>'
@honeycombio/opentelemetry-web: Endpoint configured for traces: 'https://api.honeycomb.io/v1/traces'
@honeycombio/opentelemetry-web: Sample Rate configured for traces: '1'

Dataset in Honeycomb Has Unexpected Name 

We use the serviceName variable to name your dataset in Honeycomb. Be sure you have replaced the placeholder value for it with a name that you will find useful.

Next.js Application “Navigator Is Undefined” Error 

If a “navigator is undefined” error appears when you attempt to start your local server while following Next.js instructions, the instrumentation is being run in a server-side rendering path.

To fix this, try adding the 'use client'; directive at the top of the file where you instantiate Honeycomb’s web instrumentation. Adding the 'use client'; directive tells React to only execute the file in a client environment.

If you are still seeing an error after adding the 'use client'; directive, try wrapping the function in a try/catch block. By wrapping the function, you can catch the error and avoid instantiation in server-side environments, ensuring that your application starts up even if the code is executed in a server-side environment.

try {
 const sdk = new HoneycombWebSDK({ 
    debug: true, 
    apiKey: '[YOUR API KEY HERE]' // Replace with your Honeycomb Ingest API Key  
    serviceName: '[YOUR APPLICATION NAME HERE]', // Replace with your application name. Honeycomb will name your dataset using this variable. 
    instrumentations: [getWebAutoInstrumentations()], // Adds automatic instrumentation  
    }); 
    
    sdk.start(); 
 } catch (e) {}

Available Attributes 

Every default attribute available in the Honeycomb Web Instrumentation package.

Browser Resource Attributes 

Entry Page Resource Attributes 

Honeycomb Metadata Resource Attributes 

Browser span attributes 

Largest Contentful Paint (LCP) Attributes 

Cumulative Layout Shift (CLS) Attributes 

Interaction to Next Paint (INP) Attributes 

Interaction to Next Paint (INP) With Long Animation Frame Timing Attributes 

Interaction to Next Paint (INP) With Performance Script Timing Attributes 

First Contentful Paint (FCP) 

Time To First Byte (TTFB) Attributes 

Did you find what you were looking for?

Yes No

---

If you have questions, join our Pollinators Community Slack!
Pro/Enterprise users can visit Honeycomb Support or email support@honeycomb.io.

Submit