@heyhru/server-plugin-otel

OpenTelemetry SDK initializer for Node.js services. Configures OTLP gRPC trace export with auto-instrumentation for Fastify, pg, mysql2, and ioredis.

Install

pnpm add @heyhru/server-plugin-otel

Usage

import { initOtel } from "@heyhru/server-plugin-otel";

// Must be called before any other imports (use bootstrap pattern)
initOtel({
  serviceName: "my-service",
  endpoint: "http://localhost:4317",
});

Important: initOtel must run before the application imports pg, mysql2, or ioredis so that the instrumentation hooks can patch them. Use a bootstrap.ts entry point with dynamic import:

// bootstrap.ts
import "./otel.js";
await import("./index.js");

API

initOtel(options)

Initialize the OpenTelemetry SDK and start trace collection.

Options:

| Option | Type | Required | Description | | ------------- | -------- | -------- | ------------------------------ | | serviceName | string | Yes | Service name for traces | | endpoint | string | No | OTLP gRPC endpoint (default: http://localhost:4317) |

Instrumentations

| Library | Package | | --------- | --------------------------------------------- | | HTTP | @opentelemetry/instrumentation-http | | Fastify | @fastify/otel | | pg | @opentelemetry/instrumentation-pg | | mysql2 | @opentelemetry/instrumentation-mysql2 | | ioredis | @opentelemetry/instrumentation-ioredis |

Health (/health), metrics (/metrics), and OPTIONS requests are excluded from traces.