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 install nitro-opentelemetry

# bun
bun install 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

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.

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

local 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