@dash0hq/opentelemetry

Dash0 Node.js OpenTelemetry Distribution

This is the Dash0 OpenTelemetry distribution for Node.js. It is primarily intended to be used by the Dash0 Kubernetes operator to instrument Node.js workloads with OpenTelemetry.

Configuration

DASH0_AUTOMATIC_SERVICE_NAME

If no service name has been set, a service name and a service version are automatically derived by reading the main package.json file (if it is present):

• The service.name resource attribute will be set to the value of the name attribute found in the package.json file.
• The service.version resource attribute will be set to the value of the version attribute found in the package.json file.

This behavior can be disabled either

• by setting an explicit service name using the OTEL_SERVICE_NAME environment variable,
• by setting an explicit service name using the OTEL_RESOURCE_ATTRIBUTES environment variable (using the service.name attribute key), or
• by setting the environment variable DASH0_AUTOMATIC_SERVICE_NAME=false.

DASH0_BOOTSTRAP_SPAN

If set to a non-empty string, the distribution will create a span immediately at startup with the span name set to the value of DASH0_BOOTSTRAP_SPAN.

DASH0_DEBUG

Additional debug logs can be enabled by setting DASH0_DEBUG=true.

DASH0_DEBUG_PRINT_SPANS

If DASH0_DEBUG_PRINT_SPANS=true is set, all spans are printed to stdout via the ConsoleSpanExporter. If DASH0_DEBUG_PRINT_SPANS is set to any other non-empty string, the value is interpreted as a file system path. Spans will be appended to that file. The file will be created if it does not exist. If the file cannot be opened for writing, a message will be printed to stderr and no spans will be printed to file. The spans are printed in the same format that the ConsoleSpanExporter uses. This facility is meant for troubleshooting and should not be activated in production.

DASH0_DISABLE

Disables the Dash0 Node.js distribution entirely.

DASH0_ENABLE_FS_INSTRUMENTATION

By default, the instrumentation plug-in @opentelemetry/instrumentation-fs is disabled. Set DASH0_ENABLE_FS_INSTRUMENTATION=true to enable spans for file system access.

DASH0_FLUSH_ON_SIGTERM_SIGINT

If DASH0_FLUSH_ON_SIGTERM_SIGINT=true is set, the Dash0 Node.js distribution will install a handler for SIGTERM and SIGINT that will shutdown the OpenTelemetry SDK gracefully when one of these signals is received. The SDK shutdown is timeboxed to 500 milliseconds. The signal handler will call process.exit(0) after the SDK's shutdown has completed, or after the 500 millisecond timeout, whichever happens sooner. This option can be helpful if you care about telemetry that is being produced shortly before the process terminates. This option must not be used if the application under monitoring has its own handler for SIGTERM or SIGINT, because Dash0's handler (and in particular the necessary process.exit(0) call) might interfere with the application's own signal handler.

DASH0_FLUSH_ON_EMPTY_EVENT_LOOP

By default, the Dash0 Node.js distribution will install a hook that will shutdown the OpenTelemetry SDK gracefully when the Node.js runtime is about to exit because the event loop is empty. This can be disabled by setting DASH0_FLUSH_ON_EMPTY_EVENT_LOOP=false. The SDK shutdown is timeboxed to 500 milliseconds. This hook can be helpful if you care about telemetry that is being produced shortly before the process exits. Disabling it can be useful if you care about the process terminating as quickly as possible when the event loop is empty. In contrast to the handlers for SIGTERM/SIGINT (see above), this hook will not call process.exit (since the Node.js runtime will exit on its own anyway).

DASH0_OTEL_COLLECTOR_BASE_URL

The base URL of the OpenTelemetry collector that the distribution will send data to. It defaults to http://dash0-operator-opentelemetry-collector.dash0-operator-system.svc.cluster.local:4318.

Enabling only specific instrumentations

By default, all supported instrumentations are enabled (with the exception of @opentelemetry/instrumentation-fs), but you can use the environment variable OTEL_NODE_ENABLED_INSTRUMENTATIONS to enable only certain instrumentations by providing a comma-separated list of the instrumentation package names without the @opentelemetry/instrumentation- prefix.

For example, to enable only @opentelemetry/instrumentation-http and @opentelemetry/instrumentation-nestjs-core instrumentations, set OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,nestjs-core".

See https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md#usage-auto-instrumentation for more information.