@opentelemetry/exporter-trace-otlp-http

What is @opentelemetry/exporter-trace-otlp-http?

The @opentelemetry/exporter-trace-otlp-http npm package is designed to export telemetry data (specifically traces) from applications to a backend that supports the OpenTelemetry Protocol (OTLP) over HTTP. This is part of the broader OpenTelemetry project, which aims to provide observability through tools for collecting and exporting telemetry data such as traces, metrics, and logs.

What are @opentelemetry/exporter-trace-otlp-http's main functionalities?

Exporting Traces

This feature allows the user to export trace data to an OTLP-compatible backend. The code sample demonstrates how to initialize the OTLPTraceExporter with a specific endpoint URL.

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const exporter = new OTLPTraceExporter({
  url: 'http://your-otlp-endpoint:4318/v1/traces'
});

Other packages similar to @opentelemetry/exporter-trace-otlp-http

@opentelemetry/exporter-trace-otlp-grpc

This package is similar to @opentelemetry/exporter-trace-otlp-http but uses gRPC as the transport protocol instead of HTTP. It is suitable for environments where gRPC is preferred over HTTP for performance reasons or due to existing infrastructure.

@opentelemetry/exporter-jaeger

The Jaeger exporter sends trace data to Jaeger, a different backend that is popular for tracing. It differs from @opentelemetry/exporter-trace-otlp-http in that it targets Jaeger's own protocol rather than OTLP.

@opentelemetry/exporter-zipkin

Similar to the Jaeger exporter, the Zipkin exporter sends trace data to a Zipkin backend. This package is for those who use Zipkin as their trace data visualization and storage tool, offering an alternative to OTLP.

README

OpenTelemetry Collector Exporter for web and node

This module provides exporter for web and node to be used with opentelemetry-collector - last tested with version 0.25.0.

Installation

npm install --save @opentelemetry/exporter-trace-otlp-http

Service Name

The OpenTelemetry Collector Exporter does not have a service name configuration. In order to set the service name, use the service.name resource attribute as prescribed in the OpenTelemetry Resource Semantic Conventions. To see documentation and sample code for the metric exporter, see the exporter-metrics-otlp-http package

Traces in Web

The OTLPTraceExporter in Web expects the endpoint to end in /v1/traces.

import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const collectorOptions = {
  url: '<opentelemetry-collector-url>', // url is optional and can be omitted - default is http://localhost:55681/v1/traces
  headers: {}, // an optional object containing custom headers to be sent with each request
  concurrencyLimit: 10, // an optional limit on pending requests
};

const provider = new WebTracerProvider();
const exporter = new OTLPTraceExporter(collectorOptions);
provider.addSpanProcessor(new BatchSpanProcessor(exporter, {
  // The maximum queue size. After the size is reached spans are dropped.
  maxQueueSize: 100,
  // The maximum batch size of every export. It must be smaller or equal to maxQueueSize.
  maxExportBatchSize: 10,
  // The interval between two consecutive exports
  scheduledDelayMillis: 500,
  // How long the export can run before it is cancelled
  exportTimeoutMillis: 30000,
}));

provider.register();

Traces in Node - JSON over http

const { BasicTracerProvider, BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { OTLPTraceExporter } =  require('@opentelemetry/exporter-trace-otlp-http');

const collectorOptions = {
  url: '<opentelemetry-collector-url>', // url is optional and can be omitted - default is http://localhost:55681/v1/traces
  headers: {
    foo: 'bar'
  }, // an optional object containing custom headers to be sent with each request will only work with http
  concurrencyLimit: 10, // an optional limit on pending requests
};

const provider = new BasicTracerProvider();
const exporter = new OTLPTraceExporter(collectorOptions);
provider.addSpanProcessor(new BatchSpanProcessor(exporter, {
  // The maximum queue size. After the size is reached spans are dropped.
  maxQueueSize: 1000,
  // The interval between two consecutive exports
  scheduledDelayMillis: 30000,
}));

provider.register();

GRPC

For GRPC please check npm-url-grpc

PROTOBUF

For PROTOBUF please check npm-url-proto

Configuration options as environment variables

Instead of providing options to OTLPMetricExporter and OTLPTraceExporter explicitly, environment variables may be provided instead.

OTEL_EXPORTER_OTLP_ENDPOINT=https://localhost:4317
# this will automatically append the version and signal path
# e.g. https://localhost:4317/v1/traces for `OTLPTraceExporter` and https://localhost:4317/v1/metrics for `OTLPMetricExporter`

If the trace and metric exporter endpoints have different providers, the env var for per-signal endpoints are available to use

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://trace-service:4317/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://metric-service:4317/v1/metrics
# version and signal needs to be explicit

The per-signal endpoints take precedence and overrides OTEL_EXPORTER_OTLP_ENDPOINT

For more details, see OpenTelemetry Specification on Protocol Exporter.

Running opentelemetry-collector locally to see the traces

1. Go to examples/otlp-exporter-node
2. run npm run docker:start
3. Open page at http://localhost:9411/zipkin/ to observe the traces

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

1.0.1 / Experimental 0.27.0

:boom: Breaking Change

• Other
  • #2566 feat!(metrics): remove batch observer (@dyladan)
  • #2485 feat!: Split metric and trace exporters into new experimental packages (@willarmiros)
  • #2540 fix(sdk-metrics-base): remove metric kind BATCH_OBSERVER (@legendecas)
  • #2496 feat(api-metrics): rename metric instruments to match feature-freeze API specification (@legendecas)
• opentelemetry-core
  • #2529 feat(api-metrics): add schemaUrl to meter creations (@legendecas)

:rocket: (Enhancement)

• Other
  • #2523 feat: Rename Labels to Attributes (@pirgeo)
  • #2559 feat(api-metrics): remove bind/unbind and bound instruments (@legendecas)
  • #2563 feat(sdk-metrics-base): remove per-meter config on MeterProvider.getMeter (@legendecas)
• opentelemetry-core
  • #2465 fix: prefer globalThis instead of window to support webworkers (@legendecas)
• opentelemetry-semantic-conventions
  • #2532 feat(@opentelemetry/semantic-conventions): change enum to object literals (@echoontheway)
  • #2528 feat: upgrade semantic-conventions to latest v1.7.0 spec (@weyert)
• opentelemetry-core, opentelemetry-sdk-trace-base
  • #2484 feat: new merge function (@obecny)

:bug: (Bug Fix)

• Other
  • #2610 fix: preventing double enable for instrumentation that has been already enabled (@obecny)
  • #2581 feat: lazy initialization of the gzip stream (@fungiboletus)
  • #2584 fix: fixing compatibility versions for detectors (@obecny)
  • #2558 fix(@opentelemetry/exporter-prometheus): unref prometheus server to prevent process running indefinitely (@mothershipper)
  • #2495 fix(sdk-metrics-base): metrics name should be in the max length of 63 (@legendecas)
  • #2497 feat(@opentelemetry-instrumentation-fetch): support reading response body from the hook applyCustomAttributesOnSpan (@echoontheway)
• opentelemetry-core
  • #2560 fix(core): support regex global flag in urlMatches (@moander)
• opentelemetry-exporter-zipkin
  • #2519 fix(exporter-zipkin): correct status tags names (@t2t2)

:books: (Refine Doc)

• Other
  • #2561 Use new canonical path to Getting Started (@chalin)
  • #2576 docs(instrumentation): update links in the Readme (@OlivierAlbertini)
  • #2600 docs: fix URLs in README post-experimental move (@arbourd)
  • #2579 doc: Move upgrade propagator notes to correct section (@NathanielRN)
  • #2568 chore(doc): update matrix with contrib version for 1.0 core (@vmarchaud)
  • #2555 docs: expose existing comments (@moander)
  • #2493 chore: remove getting started and link to documentation. (@svrnm)
• opentelemetry-core
  • #2604 Docs: Document the HrTime format (@JamesJHPark)

:house: (Internal)

• Other
  • #2404 chore: Fix lint warnings in instrumentation package (@alisabzevari)
  • #2533 chore: regularly close stale issues (@Rauno56)
  • #2570 chore: adding selenium tests with browserstack (@obecny)
  • #2522 chore: cleanup setting config in instrumentations (@Flarna)
  • #2541 chore: slim font size for section title in PR template (@legendecas)
  • #2509 chore: expand pull request template with action items (@pragmaticivan)
  • #2488 chore: inline sources in source maps (@dyladan)
  • #2514 chore: update stable dependencies to 1.0 (@dyladan)
• opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-node, opentelemetry-sdk-trace-web
  • #2607 chore: update npm badge image links (@legendecas)
• opentelemetry-context-async-hooks, opentelemetry-context-zone-peer-dep, opentelemetry-core, opentelemetry-exporter-jaeger, opentelemetry-exporter-zipkin, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger, opentelemetry-resources, opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-node, opentelemetry-sdk-trace-web, opentelemetry-shim-opentracing
  • #2531 chore(deps): pin minor API version (@Flarna)
• opentelemetry-core
  • #2520 chore(deps): remove unused semver (@mhennoch)

Committers: 23

• (Eliseo) Nathaniel Ruiz Nowell (@NathanielRN)
• Ali Sabzevari (@alisabzevari)
• Antoine Pultier (@fungiboletus)
• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Dylan Arbour (@arbourd)
• Georg Pirklbauer (@pirgeo)
• Gerhard Stöbich (@Flarna)
• Ivan Santos (@pragmaticivan)
• Jack (@mothershipper)
• James (@JamesJHPark)
• MartenH (@mhennoch)
• Olivier Albertini (@OlivierAlbertini)
• Patrice Chalin (@chalin)
• Rauno Viskus (@Rauno56)
• Severin Neumann (@svrnm)
• Valentin Marchaud (@vmarchaud)
• Weyert de Boer (@weyert)
• William Armiros (@willarmiros)
• @echoontheway
• legendecas (@legendecas)
• moander (@moander)
• t2t2 (@t2t2)