Get Started with Honeycomb for Real User Monitoring (RUM) | Honeycomb

Get Started with Honeycomb for Real User Monitoring (RUM)

Warning
The Honeycomb OpenTelemetry Web SDK is in beta and currently generates more events than you may anticipate. If you implement this in beta, we would love to work with you to refine this feature.

Honeycomb offers real user monitoring (RUM), so you can get complete visibility into your customer experience. Our OpenTelemetry Web SDK, a wrapper for the official OpenTelemetry Javascript SDK, allows you to get a rich set of data for your web service, so you can understand what users are experiencing when using your service and identify areas you can optimize.

In this guide, we walk you through installing and configuring the default Honeycomb RUM instrumentation, which will help you collect data on a variety of performance concerns for web services, as well as give you the necessary foundation for extending traces to any backend services that have OpenTelemetry instrumentation.

We will cover how to:

  • Set up instrumentation on your web site or web app
  • Send data to Honeycomb
  • Start exploring your data in Honeycomb

After following this guide, you will:

  • Have a rich set of default instrumentation available to help you debug your web service
  • Know how to access your data in Honeycomb and find items of interest to investigate
  • Be able to start improving your (and your team’s) Observability practices

Before You Begin 

Before you run the code, you’ll need to do a few things.

Get Your Honeycomb API Key 

To send data to Honeycomb, you’ll need to 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!

Tip
For setup, make sure you check the “Can create datasets” checkbox so that your data will show up in Honeycomb. Later, when you replace this key with a permanent one, you can uncheck that box.

If you want to use an API key you previously stored in a secure location, you can also look up details for Honeycomb API Keys any time in your Environment Settings, and use them to retrieve keys from your storage location.

Install the Honeycomb OpenTelemetry for Web SDK 

We make our OpenTelemetry for Web SDK available as an NPM package, so you can easily include it in your web bundle.

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

Tip
If your repo does not contain a yarn.lock file, install with NPM.
npm install @honeycombio/opentelemetry-web @opentelemetry/auto-instrumentations-web
yarn add @honeycombio/opentelemetry-web @opentelemetry/auto-instrumentations-web

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

Send Data to Honeycomb 

Once you have your Honeycomb Ingest API key and have installed Honeycomb’s OpenTelmetry Web SDK, it’s time to send telemetry data to Honeycomb!

Instantiate Your Instrumentation 

To get a comprehensive set of data about your application, you need to instantiate your instrumentation as early as possible in your application’s lifecycle.

You can set up your web instrumentation using a popular JavaScript framework, using inline JavaScript, or using a JavaScript helper file. To get started the most quickly, add your package configuration inline in the root instantiation file of your application:

Warning
Be sure to replace [YOUR API KEY HERE] and [YOUR APPLICATION NAME HERE] with the value of your Honeycomb API Ingest Key and the name of your service, respectively. We use the serviceName variable to name your dataset in Honeycomb, so replace it with a name that you will find useful.
// index.js or main.js

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

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();

// application instantiation code

Tips for Common JavaScript Frameworks 

In this section, we show you how to set up your web instrumentation in popular JS frameworks. Depending on the framework your application uses, instantiation may be handled differently. If you run into trouble, please ask for help in our Pollinators Community.

If you are using React (such as with create-react-app or via Next.js), you will need to wrap the Honeycomb code snippet in a component to instantiate it.

  1. Create a file called observability.jsx|tsx in your components directory, and insert the code:

    // observability.jsx|tsx
    "use client"; // browser only: https://react.dev/reference/react/use-client
    
    import { getWebAutoInstrumentations } from "@opentelemetry/auto-instrumentations-web";
    import { HoneycombWebSDK } from "@honeycombio/opentelemetry-web";
    
    export default function Observability(){
      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();
    
      return null;
    }
    
  2. In your Layout.jsx|tsx file, import the component, and add it to your layout code:

    // components/layout.tsx|jsx
    import Observability from "@/components/observability";
    // ...
      return (
        <html lang="en">
          <body>{children}</body>
          <Observability />
        </html>
      );
    

Recommended file location: src/main.ts

Place code early, ideally just above the Vue instantiation, to ensure that your instrumentation is as accurate as possible. Find the line that imports main.css, and add the code directly afterwards:

import '.assets/main.css'

// HONEYCOMB SNIPPET HERE

// import { createApp } from 'vue'
Warning
Make sure that your package.js lists version 0.37.0 or greater for @opentelemetry/auto-instrumentations-web. Versions prior to this had a conflict with Angular that prevented automatic instrumentation data from working.

The best place to put your code to instantiate early is the src/main.ts file, which is the entry point of your application.

If you are using ember-auto-import, then you can import the Honeycomb instrumentation packages directly. The best way to use Honeycomb in an Ember application is through an Application Initializer, which ensures that Honeycomb starts up as soon as possible.

  1. Use the Ember CLI to generate a new initializer named observability:

    ember generate instance-initializer observability
    

    You should see a new JS file named observability.js in the app/instance-initializers/ directory.

  2. Add Honeycomb configuration code to the observability.js file:

    import { HoneycombWebSDK } from '@honeycombio/opentelemetry-web';
    import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';
    
    export function initialize(owner) {
      const sdk = new HoneycombWebSDK({
        debug: true,
        apiKey: '[YOUR API KEY HERE]',
        serviceName: '[YOUR APPLICATION NAME HERE]',
        instrumentations: [getWebAutoInstrumentations()], // add auto-instrumentation
      });
    
      sdk.start();
    }
    
    export default {
      initialize,
    };
    

Confirm Data is Sent 

Start up your application and look in the browser console to see debug information. Once you see traces being sent in the console, you’re ready to start using Honeycomb to explore your data.

If you encounter an error, visit Troubleshooting to explore solutions to common issues.

Refine Your Implementation 

Once your data is being sent to Honeycomb, you will probably want to refine and optimize your implementation.

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.

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

const sdk = new HoneycombWebSDK({
  debug: true,
  endpoint: "https://api.honeycomb.io/v1/traces", // US instance
  // endpoint: "https://api.eu1.honeycomb.io/v1/traces", // EU instance
  apiKey: '[YOUR API KEY HERE]',
  serviceName: '[YOUR APPLICATION NAME HERE]',
  instrumentations: [getWebAutoInstrumentations()],
  resourceAttributes: {
    "user.id": user.id, // specific to your app
    "user.role": user.role, // specific to your app
  },
});

sdk.start();

Connect Browser Traces with Backend Traces 

To trace a request all the way from your browser through your distributed system, connect your frontend request traces to your backend traces.

If your application’s backend and frontend are served from the same domain, you can connect traces automatically by using either instrumentation-fetch or instrumentation-xml-http-request automatic instrumentation. If your browser application calls a separate API endpoint, then you must specify the requests to which you want the trace context header added in order to connect the traces:

registerInstrumentations({
 instrumentations: [
   getWebAutoInstrumentations({
     // load custom configuration for xml-http-request instrumentation
     '@opentelemetry/instrumentation-xml-http-request': {
       propagateTraceHeaderCorsUrls: [
           /.+/g, //Regex to match your backend urls. This should be updated.
         ],
     },
     '@opentelemetry/instrumentation-fetch': {
       propagateTraceHeaderCorsUrls: [
           /.+/g, //Regex to match your backend urls. This should be updated.
         ],
     },
   }),
 ],
});

Send Data to an OpenTelemetry Collector 

In production, we recommend that you run an OpenTelemetry Collector and send traces to it from your browser application, which will allow you to control your Honeycomb API key and any data transformation. Your OpenTelemetry Collector can then send the traces on to Honeycomb using your API key that you store in the Collector’s configuration.

This example configuration of the Honeycomb Web SDK sends traces to your Collector:

{
  endpoint: "http(s)://<your-collector-url>",
  serviceName: "your-spiffy-browser-application",
  skipOptionsValidation: true // because we are not including apiKey
}

Troubleshooting 

If you need to troubleshoot your Honeycomb RUM instrumentation, explore these solutions to common issues.

Tip
To ask questions and learn more, visit our Support Knowledge Base or join our Pollinators Community.

Dataset Not Appearing in Honeycomb 

We use the apiKey variable to send your data to Honeycomb. Be 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:

Screenshot of Honeycomb UI on the API Keys page, showing the heading Ingest Keys and the button named 'Create Ingest Key'

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.