Koa

Send distributed traces to Levitate from a Koa app using OpenTelemetry

Introduction

Koa is a web framework for Node.js. This comprehensive guide will help you instrument your Koa application with OpenTelemetry, seamlessly sending the traces to Levitate.

You can also check out the example application on GitHub↗.

Pre-requisites

1. You have a Koa application
2. You have signed up for Levitate, created a cluster, and obtained the following OTLP credentials from the Integrations page:
   • endpoint
   • auth_header

Install OpenTelemetry packages

To perform the instrumentation, install the following OpenTelemetry packages.

npm install --save @opentelemetry/api \
  @opentelemetry/instrumentation \
  @opentelemetry/tracing \
  @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/resources \
  @opentelemetry/semantic-conventions \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/sdk-node

To know more about them, you can check: https://opentelemetry.io/docs/languages/js/libraries/

Setup auto-instrumentation using OpenTelemetry

Add the necessary environment variables that can be obtained from the Integrations page.

OTET_EXPORTER_OTLP_ENDPOINT=<ENDPOINT>/v1/traces
OTLP_AUTHORIZATION_HEADER="Basic <BASIC_AUTH_HEADER>"

Next, create a file named instrumentation.ts and add the following code:

import * as api from "@opentelemetry/api";
import {
  NodeTracerProvider,
  TracerConfig,
} from "@opentelemetry/sdk-trace-node";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import {
  SEMRESATTRS_SERVICE_NAME,
  SEMRESATTRS_DEPLOYMENT_ENVIRONMENT,
} from "@opentelemetry/semantic-conventions";
import { Resource } from "@opentelemetry/resources";

// For troubleshooting, set the log level to DiagLogLevel.DEBUG
// import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
// diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);

export const setupTracing = (serviceName: string) => {
  const providerConfig: TracerConfig = {
    resource: new Resource({
      [SEMRESATTRS_SERVICE_NAME]: serviceName,
      [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV,
    }),
  };

  // Initialize and register the tracer provider
  const provider = new NodeTracerProvider(providerConfig);
  const otlp = new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
    headers: {
      Authorization: process.env.OTEL_AUTHORIZATION_HEADER,
    },
  });

  provider.addSpanProcessor(new BatchSpanProcessor(otlp));

  // Automatically instrument HTTP and Koa
  registerInstrumentations({
    instrumentations: [
      getNodeAutoInstrumentations({
        "@opentelemetry/instrumentation-fs": {
          enabled: false,
        },
      }),
    ],
    tracerProvider: provider,
  });

  provider.register();

  return api.trace.getTracer(serviceName);
};

This above code performs the following steps:

1. Set up Trace Provider with the application's name as Service Name.
2. Set up OTLP Exporter with Levitate OTLP endpoint.
3. Set up auto instrumentation for all the supported libraries.

Next, this script must be imported at the application's entry point, even before importing koa package. For instance, if you have server.ts as your entry file, then import it at the top of the file as follows:

import { setupTracing } from "./instrumentation";
// Do this before requiring koa package
setupTracing("koa-api-server");;
import Koa from "koa";
// other imports...

tip

You can also use instrumentation.js if you are not using Typescript.

Visualize the traces in Levitate

Once the application runs with the above code, it will start pushing traces to Levitate. You can see the result in action by looking at the APM dashboard in Levitate.

Troubleshooting

Please get in touch with us on Discord or Email if you have any questions.