nitro-opentelemetry

ℹ️ Opentelemetry integration is going to be built-in in a future version of nitro. This module does not reflect the future API of the official integration of nitro OTEL.

Opentelemetry integration for nitro. Without patching nitro.

This nitro module automatically create spans for request and error happening in your nitro server.

Usage

Install package:

# ✨ Auto-detect
npx nypm install nitro-opentelemetry

# npm
npm install nitro-opentelemetry

# yarn
yarn add nitro-opentelemetry

# pnpm
pnpm add nitro-opentelemetry

# bun
bun install nitro-opentelemetry

# deno
deno install npm:nitro-opentelemetry

Add the module:

//https://nitro.unjs.io/config
export default defineNitroConfig({
  modules: [
    'nitro-opentelemetry'
  ]
});

This module is also compatible with Nuxt

export default defineNuxtConfig({
  modules: [
    'nitro-opentelemetry'
  ]
})

Build-time

Config

You can configure the module with the otel property in your nitro.config.ts

• preset:
  • Option to configure the preset that will be used with OTEL

Presets

nitro-opentelemetry provides a list of presets. Theses presets are files that initialize the SDK for OTEL (for example the NodeSDK). You can provide your own by setting:

{
  name: 'custom',
  filePath: 'path_to_your_file'
}

on the preset option in the otel config.

Runtime

Span

A span is created for each event.

It is attached to the event object with the span property. The context associated to the span is also available within H3Event

interface H3Event {
    otel: {
      span: Span
      ctx: Context
    }
}

You can manipulate this span until it ends. The span will be ended in afterResponse (nitro hook) with the endTime set in beforeReponse (nitro hook). In case of an error, if there is an event associated to the error, the span will record the exception and end. If not, nitro-opentelemetry will create a span from the ROOT_CONTEXT and end it.

Hooks

Here are the available hooks.

interface NitroRuntimeHooks {
    'otel:span:name': (context: { event: H3Event, name: undefined|string }) => void
    'otel:span:end': (context: { event: H3Event, span: Span }) => void
}

• otel:span:name

  • Called when a span is created.

• otel:span:end

  • Called before ending a Span. This can happen in the afterResponse hook or in the error hook.

• otel:recordException:before

  • Called before recording and exception within the error hook of nitro. Can be used to not record an exception if you don't want to use a SpanProcessor.

Utils

defineTracedEventHandler

• Wrap your event handler with the span assigned to your event. This avoid loosing the context for opentelemetry. The main renderer and error renderer doesn't need to be wrapped with defineTracedEventHandler

Development

• Clone this repository
• Install latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Published under the MIT license. Made by @huang-julien and community 💛

🤖 auto updated with automd