OpenTelemetry HTTP and HTTPS 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 http and https.

Installation

npm install --save @opentelemetry/instrumentation-http
Copy

Supported Versions

• Nodejs >=14

Usage

OpenTelemetry HTTP Instrumentation allows the user to automatically collect telemetry and export it to their backend of choice, to give observability to distributed systems.

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

const { trace } = require('@opentelemetry/api');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ConsoleSpanExporter, TracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace');
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 HttpInstrumentation()],
});
Copy

See examples/http for a short example.

Http instrumentation Options

Http instrumentation has a few configuration options available to choose from. You can set the following:

Query parameter redaction

Query parameters that commonly carry credentials are redacted before URLs are recorded as span attributes. On client spans the redacted URL is recorded as url.full; on server spans the redacted query string is recorded as url.query. Matching values are replaced with the literal string REDACTED.

By default both sides redact the following parameters:

sig, Signature, AWSAccessKeyId, X-Goog-Signature,
X-Amz-Signature, X-Amz-Credential, X-Amz-Security-Token
Copy

redactedQueryParams controls the client side and redactedQueryParamsServer controls the server side, independently. For each option:

• Omit it to use the built-in list above.
• Supply an array to replace the built-in list entirely. The arrays are not merged, so include any built-in parameters you still want redacted.
• Supply an empty array to disable redaction on that side.

The two options do not fall back to each other: when redactedQueryParamsServer is omitted, server spans use the built-in list, not the value of redactedQueryParams. Setting redactedQueryParams alone therefore leaves custom parameters unredacted on server spans. To redact the same custom parameters on both sides, set both options to the same array.

Parameter names are matched exactly and are case-sensitive, which is why the built-in list contains both sig and Signature.

// The built-in list plus an application-specific parameter, applied to both sides.
const redacted = [
  'sig',
  'Signature',
  'AWSAccessKeyId',
  'X-Goog-Signature',
  'X-Amz-Signature',
  'X-Amz-Credential',
  'X-Amz-Security-Token',
  'api_key',
];

new HttpInstrumentation({
  redactedQueryParams: redacted,
  redactedQueryParamsServer: redacted,
});
Copy

Hook function signatures

Semantic Conventions

Span attributes:

Metrics:

• http.server.request.duration
• http.client.request.duration

Versions of @opentelemetry/instrumentation-http to 0.221.0 used semantic conventions v1.7.0 by default. Versions 0.54.0 - 0.220.0 supported the OTEL_SEMCONV_STABILITY_OPT_IN environment variable for migrating from old to stable semantic conventions.

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.