Auto-Instrumentation

Autotel supports all official @opentelemetry/instrumentation-* packages. Use the autoInstrumentations array in init() to enable them by name.

Quick Start

instrumentation.ts

import 'autotel/register'; // Must be first for ESM

import { init } from 'autotel';

init({
  service: 'my-app',
  autoInstrumentations: ['express', 'http', 'pino'],
  endpoint: process.env.OTLP_ENDPOINT,
});

tsx --import ./instrumentation.ts src/index.ts

Available Instrumentations

Pass short names to autoInstrumentations:

Short Name	Instruments
'http'	Node.js HTTP/HTTPS
'express'	Express
'fastify'	Fastify
'nestjs-core'	NestJS core
'pino'	Pino logger
'bunyan'	Bunyan logger
'winston'	Winston logger
'pg'	PostgreSQL
'mysql' / 'mysql2'	MySQL
'redis'	Redis
'mongodb'	MongoDB
'graphql'	GraphQL
'grpc'	gRPC
'koa'	Koa
'hapi'	Hapi
'kafka'	KafkaJS

Using Official Packages Directly

For more control, pass instrumentations directly:

import 'autotel/register';
import { init } from 'autotel';
import { PgInstrumentation } from '@opentelemetry/instrumentation-pg';
import { RedisInstrumentation } from '@opentelemetry/instrumentation-redis';

init({
  service: 'my-app',
  instrumentations: [new PgInstrumentation(), new RedisInstrumentation()],
});

Or use getNodeAutoInstrumentations() for everything:

import 'autotel/register';
import { init } from 'autotel';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

init({
  service: 'my-app',
  instrumentations: getNodeAutoInstrumentations({
    '@opentelemetry/instrumentation-pino': { enabled: true },
    '@opentelemetry/instrumentation-http': { enabled: true },
  }),
});

YAML Configuration

autotel.yaml

autoInstrumentations:
  - express
  - http
  - pino

When to Use What

Scenario	Approach
Quick setup, common frameworks	autoInstrumentations: ['express', 'http']
Specific packages only	instrumentations: [new PgInstrumentation()]
Everything (heavy)	instrumentations: getNodeAutoInstrumentations()
YAML-driven config	autoInstrumentations: [express, http] in autotel.yaml

ESM Requirements

For ESM apps (Node 18.19+), you must:

1. Import autotel/register first
2. Pass instrumentations directly to init()
3. Run with --import flag: tsx --import ./instrumentation.ts src/index.ts

autotel-plugins vs Official Packages

Package	When to Use
@opentelemetry/instrumentation-*	Official package exists and works
autotel-plugins	No official package (BigQuery, Kafka batch) or broken
autotel-drizzle	Drizzle ORM (no official package)
autotel-mongoose	Mongoose (stable semconv, PII redaction)

Examples

• example-basic: ESM and CJS instrumentation setup patterns.
• example-pg: PostgreSQL with official @opentelemetry/instrumentation-pg.