@opentelemetry/exporter-trace-otlp-proto

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

The @opentelemetry/exporter-trace-otlp-proto npm package is designed for exporting telemetry data, specifically traces, in the OTLP (OpenTelemetry Protocol) format using Protocol Buffers (protobuf). It is part of the OpenTelemetry JavaScript project, which provides tools for observability and monitoring through tracing, metrics, and logs.

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

Exporting Traces

This feature allows the user to export trace data to a backend that supports OTLP over gRPC. The code sample initializes an OTLPTraceExporter with a specified endpoint and insecure credentials, then adds it to a tracer provider.

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const exporter = new OTLPTraceExporter({
  url: 'http://localhost:4317',
  credentials: grpc.credentials.createInsecure()
});
tracerProvider.addSpanProcessor(new BatchSpanProcessor(exporter));

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

@opentelemetry/exporter-trace-otlp-http

Similar to @opentelemetry/exporter-trace-otlp-proto, this package is used for exporting trace data. However, it uses HTTP/JSON instead of gRPC/protobuf for communication with the backend. This difference makes it suitable for environments where gRPC is not supported or preferred.

@opentelemetry/exporter-jaeger

This package exports trace data to Jaeger, a different backend that is popular for monitoring and troubleshooting microservices-based distributed systems. While it serves a similar purpose in exporting trace data, it is specifically tailored for integration with Jaeger rather than using the OTLP.

@opentelemetry/exporter-zipkin

The Zipkin exporter sends trace data to Zipkin, another tracing backend. Like the Jaeger exporter, it is designed for a specific backend and uses different protocols and formats compared to the OTLP exporters.

README

OpenTelemetry Collector Exporter for node with protobuf

Note: This is an experimental package under active development. New releases may include breaking changes.

This module provides a trace-exporter for OTLP (http/protobuf) using protocol version v0.20.0.

Installation

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

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-proto package

Traces in Node - PROTO over http

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

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

const exporter = new OTLPTraceExporter(collectorOptions);
const provider = new BasicTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(exporter)]
});

provider.register();

Exporter Timeout Configuration

The OTLPTraceExporter has a timeout configuration option which is the maximum time, in milliseconds, the OTLP exporter will wait for each batch export. The default value is 10000ms.

To override the default timeout duration, use the following options:

• Set with environment variables:

  Environment variable	Description
  OTEL_EXPORTER_OTLP_TRACES_TIMEOUT	The maximum waiting time, in milliseconds, allowed to send each OTLP trace batch. Default is 10000.
  OTEL_EXPORTER_OTLP_TIMEOUT	The maximum waiting time, in milliseconds, allowed to send each OTLP trace and metric batch. Default is 10000.

  OTEL_EXPORTER_OTLP_TRACES_TIMEOUT takes precedence and overrides OTEL_EXPORTER_OTLP_TIMEOUT.

• Provide timeoutMillis to OTLPTraceExporter with collectorOptions:

  const collectorOptions = {
    timeoutMillis: 15000,
    url: '<opentelemetry-collector-url>', // url is optional and can be omitted - default is http://localhost:4318/v1/traces
    headers: {
      foo: 'bar'
    }, //an optional object containing custom headers to be sent with each request will only work with http
  };
  
  const exporter = new OTLPTraceExporter(collectorOptions);
  

  Providing timeoutMillis with collectorOptions takes precedence and overrides timeout set with environment variables.

OTLP Exporter Retry

OTLP requires that transient errors be handled with a retry strategy.

This retry policy has the following configuration, which there is currently no way to customize.

• DEFAULT_EXPORT_MAX_ATTEMPTS: The maximum number of attempts, including the original request. Defaults to 5.
• DEFAULT_EXPORT_INITIAL_BACKOFF: The initial backoff duration. Defaults to 1 second.
• DEFAULT_EXPORT_MAX_BACKOFF: The maximum backoff duration. Defaults to 5 seconds.
• DEFAULT_EXPORT_BACKOFF_MULTIPLIER: The backoff multiplier. Defaults to 1.5.

This retry policy first checks if the response has a 'Retry-After' header. If there is a 'Retry-After' header, the exporter will wait the amount specified in the 'Retry-After' header before retrying. If there is no 'Retry-After' header, the exporter will use an exponential backoff with jitter retry strategy.

The exporter will retry exporting within the exporter timeout configuration time.

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.