Open Telemetry

Overview

OpenTelemetry is an open-source, vendor-agnostic observability framework for generating, collecting, and exporting telemetry data (metrics, logs, and traces). This data can then be analyzed 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 SCAYLE Storefront Application includes a built-in OpenTelemetry integration. This integration depends on the @scayle/nuxt-opentelemetry module, which configures the OpenTelemetry SDK to capture and export traces, installs platform instrumentations, and adds instrumentation for the Nitro web server. It currently focuses on traces and does not support capturing logs and metrics.

SDK Initialization

To capture traces effectively, the OpenTelemetry SDK must be initialized before any application code executes. The @scayle/nuxt-opentelemetry module handles this by rewriting the application's entry point during the build process. It replaces the existing entry point with a new one that first imports the SDK initialization code, then the original entry point.

• Platform Specificity: This initialization code is platform-specific. For this reason, only node-server, vercel, and vercel-edge Nitro presets are currently supported. If you are using a different platform, the OpenTelemetry initialization will be skipped.

Nitro Instrumentation

The @scayle/nuxt-opentelemetry module also adds instrumentation to Nitro requests. For each incoming request, a span will be created that includes the HTTP Method, route name, and additional metadata from the request.

Storefront SDKs Instrumentation

The @scayle/storefront-nuxt SDK is natively instrumented with OpenTelemetry. A span is created for each RPC request and includes the following data:

Module Configuration

The @scayle/nuxt-opentelemetry module can be configured through module options in nuxt.config.ts or via runtime environment variables. Options marked with a NUXT_OPENTELEMETRY_ prefix can be set at runtime; others can only be configured at build-time.

• enabled or NUXT_OPENTELEMETRY_ENABLED:
  • This option enables or disables the module.
  • If enabled is 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.
• pathBlocklist or NUXT_OPENTELEMETRY_PATH_BLOCKLIST:
  • This option allows ignoring requests for paths that match the specified pattern. It can be a regular expression string or a plain string.
  • For example, the Storefront Application uses { pathBlocklist: '^(/.*)?/api/up' } to skip creating spans for /api/up requests (e.g., health checks).
• pathReplace or NUXT_OPENTELEMETRY_PATH_REPLACE:
  • Nitro span names are derived from the route path. This option can be used to rewrite the path used in the span name.
  • It should be an array with two elements: the first is the pattern to match (as a regular expression string or plain string), and the second 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. Both of these options must be configured at build-time in the module configuration.

• include: An array of module identifiers to include for hooking.
• exclude: An 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 environment variable 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.