@opentelemetry/exporter-trace-otlp-grpc
TypeScript icon, indicating that this package has built-in type declarations

0.49.1 • Public • Published

OpenTelemetry Collector Exporter for node with grpc

NPM Published Version Apache License

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 http://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'http://<collector-hostname>:<port>',
};

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 http://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'http://<collector-hostname>:<port>',
  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 http://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'http://<collector-hostname>:<port>',
  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: '<collector-hostname>:<port>',
      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 http://localhost:4317
  // Unix domain sockets are also supported: 'unix:///path/to/socket.sock'
  url: 'http://<collector-hostname>:<port>',
  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

Environment variable Description
OTEL_EXPORTER_OTLP_TRACES_COMPRESSION The compression type to use on OTLP trace requests. Options include gzip. By default no compression will be used.
OTEL_EXPORTER_OTLP_COMPRESSION The compression type to use on OTLP trace, metric, and log requests. Options include gzip. By default no compression will be used.
OTEL_EXPORTER_OTLP_TRACES_INSECURE Whether to enable client transport security for the exporter's gRPC connection for trace requests. This option only applies to OTLP/gRPC when an endpoint is provided without the http or https scheme. Options include true or false. By default insecure is false which creates a secure connection.
OTEL_EXPORTER_OTLP_INSECURE Whether to enable client transport security for the exporter's gRPC connection for trace, metric and log requests. This option only applies to OTLP/gRPC when an endpoint is provided without the http or https scheme. Options include true or false. By default insecure is false which creates a secure connection.
OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE The path to the file containing trusted root certificate to use when verifying an OTLP trace server's TLS credentials. By default the host platform's trusted root certificate is used.
OTEL_EXPORTER_OTLP_CERTIFICATE The path to the file containing trusted root certificate to use when verifying an OTLP trace, metric, or log server's TLS credentials. By default the host platform's trusted root certificate is used.
OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY The path to the file containing private client key to use when verifying an OTLP trace client's TLS credentials. Must provide a client certificate/chain when providing a private client key. By default no client key file is used.
OTEL_EXPORTER_OTLP_CLIENT_KEY The path to the file containing private client key to use when verifying an OTLP trace, metric or log client's TLS credentials. Must provide a client certificate/chain when providing a private client key. By default no client key file is used.
OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE The path to the file containing trusted client certificate/chain for clients private key to use when verifying an OTLP trace server's TLS credentials. Must provide a private client key when providing a certificate/chain. By default no chain file is used.
OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE The path to the file containing trusted client certificate/chain for clients private key to use when verifying an OTLP trace, metric and log server's TLS credentials. Must provide a private client key when providing a certificate/chain. By default no chain file is used.
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.

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

License

Apache 2.0 - See LICENSE for more information.

Package Sidebar

Install

npm i @opentelemetry/exporter-trace-otlp-grpc

Weekly Downloads

1,313,627

Version

0.49.1

License

Apache-2.0

Unpacked Size

35.5 kB

Total Files

12

Last publish

Collaborators

  • pichlermarc
  • bogdandrutu
  • dyladan