@wolfstar/plugin-opentelemetry

npm install @wolfstar/plugin-opentelemetry @opentelemetry/api

pnpm add @wolfstar/plugin-opentelemetry @opentelemetry/api

yarn add @wolfstar/plugin-opentelemetry @opentelemetry/api

bun add @wolfstar/plugin-opentelemetry @opentelemetry/api

​

Description

• A preload, @wolfstar/plugin-opentelemetry/preload, loaded with --import. It starts the OpenTelemetry SDK with the automatic instrumentations before the bot imports anything. It also handles the problems a Discord bot runs into when it does that. See What the preload handles.
• A plugin, @wolfstar/plugin-opentelemetry/plugin, that opens one span per interaction. The pg, ioredis, or undici spans of a command then have the command as their parent, instead of floating in the trace of the HTTP request.

​

The preload

node --import @wolfstar/plugin-opentelemetry/preload dist/main.mjs

​

What the preload handles

• ES modules. The bot is ESM, so the SDK must register the import-in-the-middle loader hook before anything is imported. A preload is the only place that runs early enough.
• Worker threads. A worker thread inherits --import and would start its own SDK, costing seconds and hundreds of megabytes each. The preload only starts the SDK on the main thread.
• SIGTERM. The preload shuts the SDK down on SIGTERM to export the last spans. A SIGTERM listener stops the process from exiting on that signal, so the preload raises the signal again once no other listener is left. The broker consumer of a BOT_MODE=worker process does the same, and the two do not keep each other alive.
• Tokens in URLs. Webhook and interaction callback URLs hold a token that lets anybody post there. The preload replaces that token with REDACTED in undici spans before they start.
• The gateway WebSocket. @discordjs/ws opens the gateway with an http request carrying Upgrade: websocket. Everything the bot does with the dispatches it receives afterwards runs in that request’s context, producing one trace that never closes. The preload does not trace WebSocket handshakes.
• Sentry’s transport. Requests from @sentry/node carry the key of the DSN in the query string. The preload does not trace them.
• Two destinations. An OTLP exporter adds the OTEL_EXPORTER_OTLP_* headers to the ones it receives, so a second exporter would send the first destination’s token to Sentry. The preload hides those variables while it creates the Sentry exporter.

​

The plugin

​

Activating with modules

// stars.config.ts
import { defineConfig } from '@wolfstar/http-framework/config';
import type {} from '@wolfstar/plugin-opentelemetry/module'; // types the `opentelemetry` key in `defineConfig`

export default defineConfig({
	modules: ['@wolfstar/plugin-opentelemetry/module'],
	opentelemetry: { interactions: { autocomplete: true } }
});

​

Without the stars CLI

import { Client } from '@wolfstar/http-framework';
import openTelemetryPlugin from '@wolfstar/plugin-opentelemetry/plugin';

const client = new Client({
	plugins: [openTelemetryPlugin({ interactions: { autocomplete: true } })]
});

​

Options

​

Spans

​

flushTraces()

import { flushTraces } from '@wolfstar/plugin-opentelemetry';

process.once('SIGINT', async () => {
	await flushTraces();
	process.exit(0);
});

​

Sentry