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

    0.29.2 • Public • Published

    OpenTelemetry Collector Exporter for node with grpc

    NPM Published Version Apache License

    This module provides exporter for web and node to be used with opentelemetry-collector. Compatible with opentelemetry-collector versions >=0.16 <=0.50.

    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
      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
      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
      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
        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
      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.

    Install

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

    DownloadsWeekly Downloads

    53,589

    Version

    0.29.2

    License

    Apache-2.0

    Unpacked Size

    34.9 kB

    Total Files

    12

    Last publish

    Collaborators

    • bogdandrutu
    • dyladan