OpenTelemetry JS

The @opentelemetry/otlp-exporter-base package provides the foundational components required to build OTLP (OpenTelemetry Protocol) Exporters for both Web and Node.js environments.

If you specifically require gRPC support, you should use the dedicated gRPC base package instead: @opentelemetry/otlp-grpc-exporter-base.

This example demonstrates how to use OpenTelemetry HTTPS instrumentation to automatically collect trace data and export it to a backend like Zipkin or Jaeger. It covers key tracing concepts including:

• Root Span: The initial span created on the client.
• Child Span: Spans created within the client's execution flow.
• Remote Parent Spans: Spans on the server that are linked to the client's context.
• SpanContext Propagation: The mechanism that carries trace information from the client to the server.
• Span Events and Attributes: Adding metadata and lifecycle events to spans.

The examples/ directory provides real-world applications demonstrating how to use OpenTelemetry JavaScript. These examples range from beginner-level introductory instrumentation to intermediate-level specialized instrumentation (HTTP, gRPC, OTLP).

Maintained Examples are updated with every release to ensure they follow the latest best practices and features. Use these as a reference for implementing tracing, metrics, and specific instrumentations in your own projects.

The @opentelemetry/context-async-hooks package provides ContextManager implementations specifically for Node.js environments using the async_hooks module. This allows OpenTelemetry to propagate context (like trace IDs) across asynchronous operations.

Important Environment Note:

• For Browser environments, do not use this package. Instead, use opentelemetry-context-zone or opentelemetry-context-zone-peer-dep.

Propagation is the process of sending span context fields—such as traceId, spanId, traceFlags, and baggage—to downstream services. This ensures that spans created by downstream services can be properly associated with the current span, maintaining a continuous trace across distributed systems.

Propagation is typically achieved using HTTP headers or RPC metadata. Common well-known formats supported by OpenTelemetry include:

• W3C Trace Context: Supported via W3CTraceContextPropagator.
• B3: Supported via B3Propagator.
• Jaeger: Supported via JaegerPropagator.

An OpenTelemetry Resource is an immutable representation of the entity producing telemetry. It contains attributes that describe the source of the data, such as a process running in a Kubernetes container, including details like Pod name, namespace, or Deployment name.

Standard attributes for resources are defined in the @opentelemetry/semantic-conventions package.

The OpenTelemetry API uses a variable on the global object to store the global API. This allows it to handle scenarios where multiple versions of the API might exist in a single node_modules tree due to dependency resolution.

When an API method is called, it checks for a compatible version on the global object. If the version used by a dependency is incompatible with the version used by the end user, the package will receive a no-op implementation instead of failing.

OpenTelemetry is vendor-agnostic. You can upload data to any backend by using various exporter implementations. While OpenTelemetry supports many backends out-of-the-box, you can also implement your own exporters for proprietary or unsupported backends.

To find a list of available exporters, visit the OpenTelemetry registry.