Open Telemetry
Overview
OpenTelemetry is an open-source, vendor-agnostic observability framework for generating, collecting, and exporting telemetry data (metrics, logs, and traces) for analysis to understand your application’s performance and behavior. OpenTelemetry data can be exported to a variety of observability backends such as DataDog, Jaeger or New Relic.
The Storefront Boilerplate includes a built-in OpenTelemetry integration. This integration depends on the @scayle/nuxt-opentelemetry module. This module configures the OpenTelemetry SDK to capture and export traces, installs platform instrumentations and adds instrumentation for the Nitro web server. It does not currently support capturing logs and metrics.
SDK Initialization
To capture traces the OpenTelemetry SDK must be initialized before any application code. @scayle/nuxt-opentelemetry does this by rewriting the entry point during the build process. It replaces the existing entry point with a new one which imports the SDK initialization code and then the original entry point. This initialization code is specific for each platform. For that reason, only node-server , vercel and vercel-edge presets are supported at this time. If you are using a different platform, the OpenTelemetry initialization will be skipped.
Nitro Instrumentation
@scayle/nuxt-opentelemetry also adds instrumentation to Nitro requests. For each incoming request, a span will be created which includes the HTTP Method and route name along with additional metadata from the request.
Storefront Core Instrumentation
@scayle/storefront-nuxt is natively instrumented with OpenTelemetry. There is a span created for each RPC request which includes the following data.
| Key | Description |
|---|---|
rpc.method | The name of the RPC method which was called. e.g. getUser |
rpc.service | The name of the service. |
rpc.payload | The sanitized payload of the RPC request. |
server.address | The hostname of the server. |
server.port | The port of the server. |
Module Configuration
@scayle/nuxt-opentelemetry can be configured through module options or runtime environment variables. The options with a NUXT_OPENTELEMETRY_ variable can be set at runtime, the others can only be set at build-time through the module configuration.
enabledorNUXT_OPENTELEMETRY_ENABLED- This option enables or disables the module. Ifenabledis set to false at build-time, the module will not install any plugins or modify the entrypoint. If it is set to false at runtime, the plugin will be installed, but spans will not be created for Nitro requests.pathBlocklistorNUXT_OPENTELEMETRY_PATH_BLOCKLIST- This option allows ignoring requests for paths that match the pattern. It can be a regular expression string or plain string. For example, the Storefront Boilerplate uses this option{ pathBlocklist: '^(/.*)?/api/up' }to skip creating spans for/api/uprequests.pathReplaceorNUXT_OPENTELEMETRY_PATH_REPLACE- The Nitro span names are derived from the route path. This option can be used to rewrite the path that is used in the name. It should be an array with two elements. The first element is the pattern to match, as a regular expression string or plain string. The second element is the text to replace the match with.
Including and Excluding modules
The below options are passed to import-in-the-middle to control its interception behavior. You can read more about the behavior of these options in its documentation. Both of these options must be configured at build-time in the module configuration.
includeAn array of module identifiers to include for hookingexcludeAn array of module identifiers to exclude from hooking
OpenTelemetry Options
The OpenTelemetry SDK and Exporter also support configuration through environment variables. You can see a full list of the supported configuration options here. The most important one is OTEL_SERVICE_NAME which allows setting the service name.
OTEL_NODE_ENABLED_INSTRUMENTATIONS can also be set to control which automatic instrumentations are used.
