OpenTelemetry Collector Exporter for node with grpc

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

This module provides a trace-exporter for OTLP (gRPC) traces using protocol version v0.20.0.

Installation

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

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

Traces in Node - GRPC

The OTLPTraceExporter in Node expects the URL to only be the hostname. It will not work with /v1/traces.

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

const collectorOptions = {
  // url is optional and can be omitted - default is https://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'https://:',
};

const provider = new BasicTracerProvider();
const exporter = new OTLPTraceExporter(collectorOptions);
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

provider.register();
['SIGINT', 'SIGTERM'].forEach(signal => {
  process.on(signal, () => provider.shutdown().catch(console.error));
});

By default, plaintext connection is used. In order to use TLS in Node.js, provide credentials option like so:

const fs = require('fs');
const grpc = require('@grpc/grpc-js');

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

const collectorOptions = {
  // url is optional and can be omitted - default is https://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'https://:',
  credentials: grpc.credentials.createSsl(),
};

const provider = new BasicTracerProvider();
const exporter = new OTLPTraceExporter(collectorOptions);
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

provider.register();
['SIGINT', 'SIGTERM'].forEach(signal => {
  process.on(signal, () => provider.shutdown().catch(console.error));
});

To use mutual authentication, pass to the createSsl() constructor:

  credentials: grpc.credentials.createSsl(
    fs.readFileSync('./ca.crt'),
    fs.readFileSync('./client.key'),
    fs.readFileSync('./client.crt')
  ),

To generate credentials for mutual authentication, you can refer to the script used to generate certificates for tests here

The exporter can be configured to send custom metadata with each request as in the example below:

const grpc = require('@grpc/grpc-js');

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

const metadata = new grpc.Metadata();
// For instance, an API key or access token might go here.
metadata.set('k', 'v');

const collectorOptions = {
  // url is optional and can be omitted - default is https://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'https://:',
  metadata, // // an optional grpc.Metadata object to be sent with each request
};

const provider = new BasicTracerProvider();
const exporter = new OTLPTraceExporter(collectorOptions);
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

provider.register();
['SIGINT', 'SIGTERM'].forEach(signal => {
  process.on(signal, () => provider.shutdown().catch(console.error));
});

Note, that this will only work if TLS is also configured on the server.

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, provide timeoutMillis to OTLPTraceExporter with collectorOptions:

  const collectorOptions = {
    timeoutMillis: 15000,
    // url is optional and can be omitted - default is localhost:4317
    // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
    url: ':',
    metadata, // // an optional grpc.Metadata object to be sent with each request
  };
  
  const exporter = new OTLPTraceExporter(collectorOptions);
  

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

Exporter Compression Configuration

By default no compression will be used. To use compression, set it programmatically in collectorOptions or with environment variables. Supported compression options: gzip and none.

const { CompressionAlgorithm } = require('@opentelemetry/exporter-trace-otlp-grpc');

const collectorOptions = {
  // url is optional and can be omitted - default is https://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'https://:',
  metadata, // // an optional grpc.Metadata object to be sent with each request
  compression: CompressionAlgorithm.GZIP,
};
const exporter = new OTLPTraceExporter(collectorOptions);

> Providing compression with collectorOptions takes precedence and overrides compression set with environment variables.

Environment Variable Configuration

> Settings configured programmatically take precedence over environment variables. Per-signal environment variables take precedence over non-per-signal environment variables.

Running opentelemetry-collector locally to see the traces

1. Go to examples/otlp-exporter-node
2. Follow the instructions there to inspect traces.

Useful links

• For more information on OpenTelemetry, visit:
• For more about OpenTelemetry JavaScript:
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.