OpenTelemetry gRPC Instrumentation for Node.js

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

This module provides automatic instrumentation for @grpc/grpc-js. Currently, version 1.x of @grpc/grpc-js is supported.

Installation

npm install --save @opentelemetry/instrumentation-grpc

Supported Versions

• @grpc/grpc-js versions ^1.0.0

Usage

OpenTelemetry gRPC Instrumentation allows the user to automatically collect trace data and export them to the backend of choice, to give observability to distributed systems when working with (grpc-js).

To load a specific instrumentation (gRPC in this case), specify it in the Node Tracer's configuration.

const { trace } = require('@opentelemetry/api');
const { ConsoleSpanExporter, TracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace');
const { GrpcInstrumentation } = require('@opentelemetry/instrumentation-grpc');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const tracerProvider = new TracerProvider({
  spanProcessors: [
    new SimpleSpanProcessor({ exporter: new ConsoleSpanExporter() })
  ]
});
trace.setGlobalTracerProvider(tracerProvider);
// See https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/sdk-trace/
// for a more complete example setting up a *context manager* and *propagators*.

registerInstrumentations({
  instrumentations: [new GrpcInstrumentation()]
});

See examples/grpc-js for examples.

gRPC Instrumentation Options

gRPC instrumentation accepts the following configuration:

| Options | Type | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ignoreGrpcMethods | IgnoreMatcher[] | gRPC instrumentation will not trace any methods that match anything in this list. You may pass a string (case-insensitive match), a RegExp object, or a filter function. | | metadataToSpanAttributes | object | List of case insensitive metadata to convert to span attributes. Client and server (outgoing requests, incoming responses) metadata attributes will be converted to span attributes in the form of rpc.{request\response}.metadata.metadata_key, e.g. rpc.response.metadata.date |

Semantic Conventions

The instrumentation-grpc versions v0.220.0 and later emit the stable v1.23.0+ semantic conventions.

Attributes collected

| v1.23.0 semconv | Short Description | | ---------------- | ---------------------------------------------------------- | | server.address | Server domain name if available without reverse DNS lookup | | server.port | Server port number |

| Attribute | Short Description | | ------------- | -------------------------------------------------------------------------------------------------- | | rpc.method | The name of the (logical) method being called, must be equal to the $method part in the span name. | | rpc.service | The full (logical) name of the service being called, including its package name, if applicable. | | rpc.system | A string identifying the remoting system. |

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.