OpenTelemetry Instrumentation#

Misskey's backend uses OpenTelemetry (OTel) for distributed tracing. All instrumentation code lives under packages/backend/src/core/telemetry/. The entry point for initialization is telemetry-registry.ts, which bootstraps adapters before NestJS's DI container is built 1. TelemetryService is a thin NestJS-injectable wrapper over this module-level state 2.

Build Externalization of @opentelemetry/*#

All @opentelemetry/* packages are excluded from the rolldown bundle via a regex rule in the external list 3:

/^@opentelemetry\/.*/

Similarly, pg is also externalized so that require-hook-based instrumentation (Sentry or OTel) can patch it at runtime 4. Without externalizing pg, the bundler would inline it and the hooks applied before require('pg') would find no module to intercept.

In watch (dev) mode all non-local modules are externalized wholesale, bypassing the explicit list 5.

Packages in package.json: 6

diagnostics_channel Instead of Require-Hook Instrumentation#

For HTTP client and Redis, Misskey deliberately avoids the classic require-hook approach (patching require('http') / require('ioredis') on load). Instead, both instrumentations subscribe to native Node.js diagnostics_channel events published by the libraries themselves:

• HTTP client — http-client-instrumentation.ts subscribes to http.client.request.created, http.client.response.finish, and http.client.request.error channels using node:diagnostics_channel 7. The code comment explicitly states this approach captures modules loaded before telemetry initialization — which require-hooks cannot do 8.

• Redis (ioredis) — redis-instrumentation.ts uses node:diagnostics_channel's tracingChannel API to subscribe to ioredis:command and ioredis:connect channels published by ioredis ≥5.11 9 10. This also works after bundling because ioredis itself emits the events — no module patching required.

Both instrumentations are fully testable in isolation by injecting mock subscribe / tracingChannel dependencies 11 12.

PostgreSQL: Dynamic Load & Opt-In#

PostgreSQL instrumentation uses @opentelemetry/instrumentation-pg, which relies on the traditional require-hook pattern. The hook must be installed before the pg module is first imported 13.

installDatabaseInstrumentation in database-instrumentation.ts handles this with two safeguards:

1. Opt-in guard — if options.capturePgSpans is false, the function returns immediately without loading the package at all 14.
2. Dynamic import — @opentelemetry/instrumentation-pg is only loaded via await import(...) when pg spans are enabled, so the module and its hooks are never materialized in the common path 15.

Privacy defaults for pg spans 16:

• enhancedDatabaseReporting is hardcoded false — SQL parameters (which may contain post content or credentials) are never captured.
• db.statement and db.query.text span attributes are overwritten with [REDACTED] unless capturePgStatement is explicitly enabled via the opt-in config.

Adapter Architecture & Sentry Co-existence#

telemetry-registry.ts supports three configurations 17:

TelemetryService exposes startSpan, startSpanWithTraceContext (for BullMQ worker context propagation), and captureMessage to the rest of the application 2.

Queue trace-context propagation is handled by queue-instrumentation.ts, which wraps Queue.add / Queue.addBulk to inject the active OTel context into BullMQ job data before serialization to Redis 18.