@unhandled/otel-lean
v0.2.5
Published
Unhandled span processors, instrumentations, @adonisjs/otel destinations and analytics for apps that run their own OpenTelemetry SDK
Readme
@unhandled/otel-lean
The Unhandled pieces for apps that run their own OpenTelemetry SDK, such as AdonisJS apps on @adonisjs/otel. It depends only on @unhandled/protocol; the OpenTelemetry packages are peers, so it uses the copies your SDK already loads and installs no second SDK.
Install
pnpm add @unhandled/otel-lean @opentelemetry/[email protected]Pin @opentelemetry/instrumentation to the version your SDK uses (0.213.0 for @adonisjs/otel 1.2.4). Without the pin, npm and pnpm install the newest 0.2xx release beside it.
@adonisjs/otel
// config/otel.ts
import { defineConfig } from '@adonisjs/otel'
import { unhandledDestinations, unhandledSpanProcessors } from '@unhandled/otel-lean/otel_preset'
import { KNEX_POOL_WAIT_INSTRUMENTATION_NAME, KnexPoolWaitInstrumentation } from '@unhandled/otel-lean/knex_pool_wait'
import env from '#start/env'
const destinations = unhandledDestinations({ dsn: env.get('UNHANDLED_DSN'), environment: env.get('APP_ENV') })
export default defineConfig({
destinations,
instrumentations: { [KNEX_POOL_WAIT_INSTRUMENTATION_NAME]: new KnexPoolWaitInstrumentation() },
spanProcessors: unhandledSpanProcessors({ destinations }),
})unhandledDestinations() turns the DSN into an @adonisjs/otel destination. Without a DSN it returns none, and @adonisjs/otel falls back to the OTEL_EXPORTER_OTLP_* variables.
Passing destinations switches export away from the OTEL_* variables: the OpenTelemetry Node SDK builds no exporter from OTEL_EXPORTER_OTLP_* once a destination supplies its own. If your .env has both UNHANDLED_DSN and OTEL_* variables, everything goes to the DSN and the OTEL_* endpoint receives nothing.
[!WARNING] Don't pass
spanProcessors: [new ExecutionContextProcessor()]on its own. WhenspanProcessorsis set, the Node SDK skips the trace exporter it builds from theOTEL_*variables, so an app without a DSN destination stops exporting traces and nothing reports it.unhandledSpanProcessors()returns theExecutionContextProcessorplus that exporter, built fromOTEL_TRACES_EXPORTER,OTEL_EXPORTER_OTLP_PROTOCOLand the endpoint and header variables the way the SDK would build it. It leaves the exporter out when a destination already takes traces orOTEL_SDK_DISABLED=true.
Subpaths
| Import | Exports |
| --- | --- |
| @unhandled/otel-lean/otel_preset | unhandledDestinations, unhandledSpanProcessors and everything below except the error class |
| @unhandled/otel-lean/execution_context | ExecutionContextProcessor, which marks every span web or background |
| @unhandled/otel-lean/knex_pool_wait | KnexPoolWaitInstrumentation, which puts the knex pool wait on the query span as db.client.connection.wait_time |
| @unhandled/otel-lean/clickhouse | ClickHouseInstrumentation for @clickhouse/client |
| @unhandled/otel-lean/errors | UnhandledConfigError |
Both instrumentations stay off until the SDK registers them (registerInstrumentations, which NodeSDK.start() calls), so a config file that builds them under OTEL_SDK_DISABLED=true hooks nothing.
For AI agents
A coding agent can install this package, check that its data arrives and fix the errors it reports through the Unhandled MCP server at https://unhandled.net/mcp. In Claude Code, the Unhandled plugin adds that server plus skills for instrumenting a service, fixing a production error with a failing test first and verifying a deploy:
claude plugin marketplace add treboryx/unhandled
claude plugin install unhandled@unhandledCodex, Cursor, Gemini CLI and other agents connect to the same URL. Coding agents has the setup for each one and an AGENTS.md section to add to your repository.
