OpenTelemetry for Zuplo

@zuplo/otel instruments your Zuplo API with OpenTelemetry — incoming requests, policies, handlers, and outbound fetch — and exports the resulting spans to the Zuplo-managed trace ingest and/or to any OTLP/HTTP destination(s) you configure.

Getting started

Register the plugin from your project's zuplo.runtime.ts. With no configuration, traces are sent to Zuplo and are queryable in the portal — service.name defaults to your project name:

import { RuntimeExtensions } from "@zuplo/runtime";
import { OpenTelemetryPlugin } from "@zuplo/otel";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(new OpenTelemetryPlugin());
}

The Zuplo-managed exporter only works in deployed Zuplo environments. In environments where the managed ingest isn't configured (e.g. local development), using it throws a ConfigurationError — configure your own exporter/spanProcessors, or only add the plugin in deployed environments.

Usage configurations

Zuplo-managed exporter (default)

Omit any destination and spans go to Zuplo. You can still name the service:

new OpenTelemetryPlugin({
  service: { name: "my-api" },
});

This is equivalent to explicitly passing a ZuploSpanExporter:

import { OpenTelemetryPlugin, ZuploSpanExporter } from "@zuplo/otel";

new OpenTelemetryPlugin({
  service: { name: "my-api" },
  exporter: new ZuploSpanExporter(),
});

Your own OTLP collector

Point a single OTLP/HTTP exporter at your collector. Provide headers for authentication. (Using exporter opts out of the Zuplo default.)

import { environment } from "@zuplo/runtime";

new OpenTelemetryPlugin({
  service: { name: "my-api", version: "1.0.0" },
  exporter: {
    url: environment.OTLP_ENDPOINT,
    headers: { authorization: `Bearer ${environment.OTEL_TOKEN}` },
  },
});

Separate logs and traces endpoints

When your backend exposes distinct endpoints for logs and traces, provide both. The shared headers are sent to each.

new OpenTelemetryPlugin({
  service: { name: "my-api" },
  logUrl: environment.OTLP_LOG_ENDPOINT,
  traceUrl: environment.OTLP_TRACE_ENDPOINT,
  headers: { authorization: `Bearer ${environment.OTEL_TOKEN}` },
});

Multiple destinations (Zuplo + your own)

To send spans to more than one destination, build a span processor per destination and pass them as spanProcessors. Each processor batches and flushes independently, so one slow or failing exporter does not block the others. Spans are produced once per request and fan out to every processor.

import {
  OpenTelemetryPlugin,
  OTLPSpanExporter,
  BatchTraceSpanProcessor,
  ZuploSpanExporter,
} from "@zuplo/otel";
import { environment } from "@zuplo/runtime";

new OpenTelemetryPlugin({
  service: { name: "my-api" },
  spanProcessors: [
    // Your own collector
    new BatchTraceSpanProcessor(
      new OTLPSpanExporter({ url: environment.OTLP_ENDPOINT })
    ),
    // ...and Zuplo
    new BatchTraceSpanProcessor(new ZuploSpanExporter()),
  ],
});

spanProcessors accepts any OpenTelemetry SpanProcessor, so you can also mix in standard processors — for example a console exporter for local debugging:

import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";

new OpenTelemetryPlugin({
  service: { name: "my-api" },
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});

Resource attributes

Every span is automatically tagged with Zuplo's service, account, project, cloud, and build identifiers. Use resourceAttributes to add your own — they are merged on top of the defaults, so a key you set here overrides the default of the same name.

new OpenTelemetryPlugin({
  service: { name: "my-api" },
  resourceAttributes: {
    "deployment.environment.name": "canary",
  },
});

Sampling

Head sampling is configured via sampling.headSampler. Pass a ratio to sample a fraction of traces (defaults to sampling everything):

new OpenTelemetryPlugin({
  service: { name: "my-api" },
  sampling: {
    headSampler: { ratio: 0.1 }, // sample 10% of requests
  },
});

Exports

| Export | Purpose | | ------------------------- | ------------------------------------------------------------------------- | | OpenTelemetryPlugin | The plugin registered via runtime.addPlugin(...). | | ZuploSpanExporter | Sends spans to the Zuplo-managed trace ingest (the default destination). | | TraceConfig | Type of the plugin's configuration object. | | OTLPSpanExporter | OTLP/HTTP span exporter; pair with a span processor. | | OTLPExporterConfig | Configuration (url, optional headers) for an OTLP exporter. | | BatchTraceSpanProcessor | Per-trace batching span processor; wrap an exporter to add a destination. |