From b19dc5a53043a083df23c2959ef0359188ee2ea1 Mon Sep 17 00:00:00 2001 From: RedStar Date: Fri, 13 Nov 2026 17:30:09 +0100 Subject: [PATCH 1/4] fix(plugin-gateway): let plugins add dispatch wrappers and destroy hooks A plugin's postInitialization runs inside the base Client constructor, before the private fields of GatewayClient are initialized, so addDispatchWrapper and addDestroyHook threw there. Keep them in module-level WeakMaps keyed by the client instead. Refs #261 --- .changeset/gateway-hooks-from-plugins.md | 5 ++++ packages/plugin-gateway/src/GatewayClient.ts | 28 +++++++++++------- packages/plugin-gateway/tests/hooks.test.ts | 30 +++++++++++++++++++- 3 files changed, 51 insertions(+), 12 deletions(-) create mode 100644 .changeset/gateway-hooks-from-plugins.md diff --git a/.changeset/gateway-hooks-from-plugins.md b/.changeset/gateway-hooks-from-plugins.md new file mode 100644 index 00000000..20baeda7 --- /dev/null +++ b/.changeset/gateway-hooks-from-plugins.md @@ -0,0 +1,5 @@ +--- +"@wolfstar/plugin-gateway": patch +--- + +`addDispatchWrapper` and `addDestroyHook` work when a plugin calls them from `postInitialization`, which runs before the fields of `GatewayClient` are initialized; they threw a `TypeError` about a private member there. diff --git a/packages/plugin-gateway/src/GatewayClient.ts b/packages/plugin-gateway/src/GatewayClient.ts index 683e3b77..a6cb8604 100644 --- a/packages/plugin-gateway/src/GatewayClient.ts +++ b/packages/plugin-gateway/src/GatewayClient.ts @@ -356,6 +356,11 @@ export type DispatchWrapper = ( */ export type GatewayClientDestroyHook = () => unknown; +// Outside of the instance: plugins add them from `postInitialization`, which the base `Client` constructor runs before +// the fields of `GatewayClient` exist. See `addDispatchWrapper`: the first added is the outermost. +const dispatchWrappers = new WeakMap(); +const destroyHooks = new WeakMap>(); + /** * A {@link Client} that, on top of serving HTTP interactions, connects to the Discord gateway, writes every dispatch * into its cache, and emits {@link GatewayEventMap} events carrying structures. @@ -539,11 +544,6 @@ export class GatewayClient extends Client { // The `destroy` in progress, which a concurrent call joins instead of changing `#keepSessions` under it. #destroying: Promise | null = null; - // See `addDispatchWrapper`: the first added is the outermost. - #dispatchWrappers: readonly DispatchWrapper[] = []; - - readonly #destroyHooks = new Set(); - public constructor(options: GatewayClientOptions) { super(options); container.gatewayClient = this; @@ -693,9 +693,13 @@ export class GatewayClient extends Client { * @returns A function that removes the wrapper, for the dispatches received after it is called. */ public addDispatchWrapper(wrapper: DispatchWrapper): () => void { - this.#dispatchWrappers = [...this.#dispatchWrappers, wrapper]; + dispatchWrappers.set(this, [...(dispatchWrappers.get(this) ?? []), wrapper]); return () => { - this.#dispatchWrappers = this.#dispatchWrappers.filter((entry) => entry !== wrapper); + const wrappers = dispatchWrappers.get(this) ?? []; + dispatchWrappers.set( + this, + wrappers.filter((entry) => entry !== wrapper), + ); }; } @@ -711,15 +715,17 @@ export class GatewayClient extends Client { * @returns A function that removes the hook. */ public addDestroyHook(hook: GatewayClientDestroyHook): () => void { - this.#destroyHooks.add(hook); + let hooks = destroyHooks.get(this); + if (!hooks) destroyHooks.set(this, (hooks = new Set())); + hooks.add(hook); return () => { - this.#destroyHooks.delete(hook); + hooks.delete(hook); }; } async #runDestroyHooks(): Promise { // A copy: a hook added while the hooks run waits for the next destroy. - for (const hook of Array.from(this.#destroyHooks)) { + for (const hook of Array.from(destroyHooks.get(this) ?? [])) { try { await hook(); } catch (error) { @@ -1361,7 +1367,7 @@ export class GatewayClient extends Client { #wrapDispatch(dispatch: WrappedDispatch): Promise { let run = () => this.handleDispatch(dispatch.payload, dispatch.shardId); // Read once, so a wrapper added or removed meanwhile only changes the next dispatches. - const wrappers = this.#dispatchWrappers; + const wrappers = dispatchWrappers.get(this) ?? []; for (let index = wrappers.length - 1; index >= 0; index--) { const wrapper = wrappers[index]!; const inner = run; diff --git a/packages/plugin-gateway/tests/hooks.test.ts b/packages/plugin-gateway/tests/hooks.test.ts index 2c7c03ce..acea18c6 100644 --- a/packages/plugin-gateway/tests/hooks.test.ts +++ b/packages/plugin-gateway/tests/hooks.test.ts @@ -1,5 +1,6 @@ import { AsyncLocalStorage } from "node:async_hooks"; import { WebSocketShardEvents } from "@discordjs/ws"; +import { definePlugin } from "@wolfstar/http-framework"; import { createInMemoryCache } from "@wolfstar/plugin-cache"; import { GatewayDispatchEvents, @@ -18,13 +19,14 @@ const user: APIUser = { avatar: null, }; -function createClient() { +function createClient(plugins: ReturnType>[] = []) { return new GatewayClient({ discordPublicKey: "0".repeat(64), discordToken: "test-token", clientId: "266624760782258186", intents: 0, cache: createInMemoryCache(), + plugins, }); } @@ -207,3 +209,29 @@ describe("GatewayClient#addDestroyHook", () => { expect(hook).not.toHaveBeenCalled(); }); }); + +describe("hooks added by a plugin", () => { + // `postInitialization` runs from the constructor of the base `Client`, before the fields of `GatewayClient` exist. + test("GIVEN a plugin that adds a wrapper and a destroy hook in postInitialization THEN both run", async () => { + const calls: string[] = []; + const plugin = definePlugin(() => ({ + name: "test-hooks", + postInitialization(client) { + const gateway = client as GatewayClient; + gateway.addDispatchWrapper(async (_dispatch, run) => { + calls.push("wrapper"); + await run(); + }); + gateway.addDestroyHook(() => calls.push("destroy hook")); + }, + })); + const client = createClient([plugin()]); + vi.spyOn(client.gateway, "destroy").mockResolvedValue(); + + send(client, "1"); + await client.idle(); + await client.destroy(); + + expect(calls).toEqual(["wrapper", "destroy hook"]); + }); +}); From 34405f6f5254de0f1e752ce6c35c4eeff4f153fb Mon Sep 17 00:00:00 2001 From: RedStar Date: Fri, 13 Nov 2026 17:30:11 +0100 Subject: [PATCH 2/4] feat(plugin-opentelemetry): open a span per gateway dispatch and flush on destroy On a GatewayClient, the plugin wraps each dispatch in a root span, so its cache writes and listeners get a parent of their own instead of the WebSocket handshake's trace, and calls flushTraces at the end of destroy. The README shows how to wire flushTraces into the exit hooks of plugin-sharder. Resolves #261 --- .changeset/opentelemetry-dispatch-spans.md | 5 + AGENTS.md | 4 +- packages/plugin-opentelemetry/README.md | 37 +++++ packages/plugin-opentelemetry/package.json | 1 + .../src/lib/attributes.ts | 38 +++++ .../src/lib/dispatches.ts | 108 +++++++++++++ packages/plugin-opentelemetry/src/plugin.ts | 65 ++++++-- .../tests/dispatches.test.ts | 148 ++++++++++++++++++ pnpm-lock.yaml | 3 + 9 files changed, 394 insertions(+), 15 deletions(-) create mode 100644 .changeset/opentelemetry-dispatch-spans.md create mode 100644 packages/plugin-opentelemetry/src/lib/dispatches.ts create mode 100644 packages/plugin-opentelemetry/tests/dispatches.test.ts diff --git a/.changeset/opentelemetry-dispatch-spans.md b/.changeset/opentelemetry-dispatch-spans.md new file mode 100644 index 00000000..40b317c2 --- /dev/null +++ b/.changeset/opentelemetry-dispatch-spans.md @@ -0,0 +1,5 @@ +--- +"@wolfstar/plugin-opentelemetry": minor +--- + +On a `GatewayClient` of `@wolfstar/plugin-gateway` 0.17 or later, the plugin opens one span per gateway dispatch, the root of a trace of its own, around its cache writes and listeners (`dispatches`, on by default, with `dispatches.ignore` for noisy types), and calls `flushTraces()` at the end of `GatewayClient#destroy` (`flushOnDestroy`, on by default). The README shows how to wire `flushTraces()` into the exit hooks of `@wolfstar/plugin-sharder`. diff --git a/AGENTS.md b/AGENTS.md index 48f227f0..b9b7816a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ Project conventions discovered for `plugins` (`wolfstar-project/plugins`). - `@wolfstar/plugin-gateway` — Gateway (WebSocket) support: a `GatewayClient` emitting Structures, backed by a pluggable cache. - `@wolfstar/plugin-i18next` — i18next-powered internationalization for HTTP interactions. - `@wolfstar/plugin-logger` — pluggable logger (console, Sentry, and optional consola/evlog/winston adapter subpaths) replacing the framework's built-in console logger. -- `@wolfstar/plugin-opentelemetry` — traces the bot with OpenTelemetry: a `./preload` (loaded with `--import`) that starts the SDK on the main thread only when an OTLP endpoint is set, and a plugin opening one span per interaction; `./register` is a no-op. +- `@wolfstar/plugin-opentelemetry` — traces the bot with OpenTelemetry: a `./preload` (loaded with `--import`) that starts the SDK on the main thread only when an OTLP endpoint is set, and a plugin opening one span per interaction and, on a `GatewayClient`, one root span per dispatch (through `addDispatchWrapper`) plus `flushTraces()` on `destroy` (through `addDestroyHook`); `./register` is a no-op. - `@wolfstar/plugin-scheduled-tasks` — one-off and repeated tasks as pieces, backed by BullMQ; the first package built on `definePlugin` (framework 6.1) and `defineModule` (`@wolfstar/kit`), with a no-op `./register`. - `@wolfstar/plugin-sharder` — multi-process sharding for `plugin-gateway` (processes, cluster workers, or worker threads). - `@wolfstar/plugin-subcommands-advanced` — modularizes slash subcommands into separate command classes. @@ -86,7 +86,7 @@ pnpm exec knip # unused code/dependency check (CI's - `tests/http-framework-peer-range.test.ts` (part of `pnpm test`, so the CI `unit` job) fails when any non-private package's `peerDependencies["@wolfstar/http-framework"]` excludes the framework version the workspace installs (its devDependency, kept on the latest release by Renovate), when a package declaring that peer doesn't also devDepend on it, or when the packages' peer ranges accept different majors (a package whose range starts at a later major, like `plugin-scheduled-tasks`' `^6.1.0`, only has to match from that major up). When Renovate bumps the framework to a new major, widen **every** plugin's peer range (`^x || ^.0.0`) in the same PR **and** add a patch changeset per package — a peer-range change on `main` isn't published without one (that is how `plugin-api`/`plugin-logger`/`plugin-subcommands-advanced` shipped `^3`-only peers to npm after the v5 bump, #121). - Non-trivial structural work (cross-package parity ports, manager/API redesigns, new plugin scaffolding) gets a design doc under `docs/superpowers/` before implementation: a plan at `docs/superpowers/plans/-.md` and, for anything with real design decisions, a matching spec at `docs/superpowers/specs/--design.md` (e.g. `docs/superpowers/specs/2026-10-05-message-types-parity-design.md`). PR descriptions for such changes link the spec/plan instead of re-explaining the design. Check this directory for prior art before redesigning an area that already has one. - Activation has two paths. `plugin-scheduled-tasks` and `plugin-opentelemetry` are module-only (their `./register` is a no-op); `plugin-opentelemetry` also ships a third entrypoint, `./preload` (loaded with `--import`), which starts the OpenTelemetry SDK before the bot's own imports run — `./register` cannot do this, since it only runs after the bot has already started importing. The older plugins ship `./module` (default export: `defineModule` from `@wolfstar/kit`, optional peer) and, for those with runtime hooks, `./plugin` (default export: a `definePlugin` factory); `./register` stays the legacy class + `Client.plugins.register*Hook` path for framework v3/v5/v6. Both call the same functions in `src/hooks.ts`, so change behaviour there. The `stars` CLI never imports `/register` itself; it only preloads the sources registered through `ctx.addPlugin`, so a user's own `import "/register"` (or passing the `./plugin` factory to `plugins` while also importing `/register`) still double-installs the hooks. `tests/module-entries.test.ts` checks that every `src/module.ts` (except `plugin-scheduled-tasks`, excluded on purpose) is exported, built and has kit and schema as optional peers. -- `plugin-opentelemetry` has process-level tests (`tests/preload.test.ts`: worker thread, `SIGTERM`, WebSocket handshake) that spawn Node with the preload. The CI unit job runs vitest with no build, so the test builds `src/preload.ts` itself with `tsdown` into `packages/plugin-opentelemetry/node_modules/.cache/preload-test/`. The `SIGTERM` cases are skipped on Windows (a Windows process cannot handle the signal); run them in WSL or Linux. Interaction spans are made the active span with `context.attach` (`@opentelemetry/api` 1.10), because the framework's `*Run` events do not wrap the command. `protobufjs` is denied in `allowBuilds` (its postinstall is not needed). +- `plugin-opentelemetry` has process-level tests (`tests/preload.test.ts`: worker thread, `SIGTERM`, WebSocket handshake) that spawn Node with the preload. The CI unit job runs vitest with no build, so the test builds `src/preload.ts` itself with `tsdown` into `packages/plugin-opentelemetry/node_modules/.cache/preload-test/`. The `SIGTERM` cases are skipped on Windows (a Windows process cannot handle the signal); run them in WSL or Linux. Interaction spans are made the active span with `context.attach` (`@opentelemetry/api` 1.10), because the framework's `*Run` events do not wrap the command. Hooks a plugin adds to a `GatewayClient` from `postInitialization` run inside the base `Client` constructor, before the subclass fields exist, so `GatewayClient` keeps its dispatch wrappers and destroy hooks in module-level `WeakMap`s, not private fields. `protobufjs` is denied in `allowBuilds` (its postinstall is not needed). - Module config keys: every `defineModule` sets `meta.configKey`, so a project writes the options under that top-level key of `stars.config` instead of the `[specifier, options]` tuple (the tuple is merged over the key and wins). Needs `@wolfstar/kit` `^0.2.0 || ^0.3.0` as the peer range (dev range `^0.2.0`) of every package with a `src/module.ts`, and each `module.ts` augments `StarsConfig` from `@wolfstar/schema` (an optional peer and devDependency) to type the key. Keys: `plugin-api` `api`, `plugin-broker` `broker`, `plugin-cache` `cache`, `plugin-gateway` `gateway`, `plugin-i18next` `i18n`, `plugin-logger` `logger`, `plugin-opentelemetry` `opentelemetry`, `plugin-scheduled-tasks` `scheduledTasks`, `plugin-sharder` `sharder`, `plugin-subcommands-advanced` `subcommandsAdvanced`; `cache`, `gateway`, `sharder` and `subcommandsAdvanced` take no options yet and only reserve the name. A key must be unique and not a built-in key (`BUILT_IN_CONFIG_KEYS` of `@wolfstar/schema`); renaming one is a breaking change. `tests/module-config-keys.test.ts` runs every module through kit's `setupModules`. What sits under a key is written into the build, so it must be JSON. ## Notes for agents diff --git a/packages/plugin-opentelemetry/README.md b/packages/plugin-opentelemetry/README.md index a820e280..44004d50 100644 --- a/packages/plugin-opentelemetry/README.md +++ b/packages/plugin-opentelemetry/README.md @@ -112,6 +112,15 @@ Without an SDK running, `@opentelemetry/api` hands out no-op spans and the plugi `interactions: false` turns them all off, `true` takes the defaults. +| Option | Default | What it does | +| ------------------- | ------- | ------------------------------------------------------------------------------- | +| `dispatches` | `true` | A span per gateway dispatch, on a `GatewayClient` (`@wolfstar/plugin-gateway`). | +| `dispatches.ignore` | `[]` | Dispatch types that get no span, such as `PRESENCE_UPDATE` or `TYPING_START`. | +| `flushOnDestroy` | `true` | Calls `flushTraces()` at the end of `GatewayClient#destroy`. | + +`dispatches` and `flushOnDestroy` need `@wolfstar/plugin-gateway` 0.17 or later, and are ignored on a client that does +not connect to the gateway. + #### The spans A span is named ` ` (`command ping`, `component confirm`) and carries: @@ -127,6 +136,21 @@ A span is named ` ` (`command ping`, `component confirm`) and carrie A failing run records the exception and sets the span status to `ERROR`. +A gateway dispatch gets a span named `dispatch ` (`dispatch MESSAGE_CREATE`) around its cache writes and its +listeners, so what they start has it as a parent. It carries: + +| Attribute | Value | +| ---------------------------- | ------------------------------------------------ | +| `discord.dispatch.type` | The type of the dispatch. | +| `discord.shard.id` | The gateway shard it came from. | +| `discord.dispatch.partition` | The partition it is ordered in, when it has one. | +| `discord.guild.id` | The guild, when the dispatch belongs to one. | +| `dispatch.outcome` | `success` or `error`. | + +Each dispatch span is the root of a trace of its own: `@discordjs/ws` receives every dispatch in the context of the +request that opened the WebSocket, and a span started there would put all of the gateway's work in one trace that never +ends. Dispatches replayed with `replayDispatch` (as by `@wolfstar/plugin-broker`) get no span. + The framework's events do not wrap the run of a command, so the span is made the active one with `context.attach` from the `*Run` event, and the previous context is restored on `*Finish`. That needs a context manager that implements `attach`, @@ -138,6 +162,19 @@ spans are still created, but what a command starts is not attached to them. Exports the spans waiting in the batch. Call it from a shutdown path before the process exits; it never rejects, and does nothing when no SDK is running. +The plugin already calls it at the end of `GatewayClient#destroy`. The preload calls it on `SIGTERM` and `beforeExit`, +but `process.exit` skips `beforeExit`, which is how the shards of `@wolfstar/plugin-sharder` stop. Wire it into the +sharder (0.5 or later) yourself, since the plugin cannot see those objects: + +```ts +import { flushTraces } from "@wolfstar/plugin-opentelemetry"; + +shard.addExitHook(flushTraces); // in a shard: before exit(), restart(), or a close from the manager +manager.addDestroyHook(flushTraces); // in the manager: at the end of manager.destroy() +``` + +For any other path that ends the process: + ```ts import { flushTraces } from "@wolfstar/plugin-opentelemetry"; diff --git a/packages/plugin-opentelemetry/package.json b/packages/plugin-opentelemetry/package.json index 2c0bbb0e..c32a219d 100644 --- a/packages/plugin-opentelemetry/package.json +++ b/packages/plugin-opentelemetry/package.json @@ -89,6 +89,7 @@ "@types/node": "22.15.21", "@wolfstar/http-framework": "^6.5.1", "@wolfstar/kit": "^0.3.1", + "@wolfstar/plugin-gateway": "workspace:^", "@wolfstar/schema": "^0.12.0" }, "peerDependencies": { diff --git a/packages/plugin-opentelemetry/src/lib/attributes.ts b/packages/plugin-opentelemetry/src/lib/attributes.ts index 805b49a3..d1cfaa81 100644 --- a/packages/plugin-opentelemetry/src/lib/attributes.ts +++ b/packages/plugin-opentelemetry/src/lib/attributes.ts @@ -58,3 +58,41 @@ export interface OpenTelemetryInteractionsOptions { */ handlers?: boolean; } + +/** + * The attributes of the span of a gateway dispatch. + */ +export const DispatchAttributes = { + /** + * The type of the dispatch (`MESSAGE_CREATE`, `GUILD_MEMBER_UPDATE`, ...). + */ + Type: "discord.dispatch.type", + /** + * The gateway shard the dispatch came from. + */ + ShardId: "discord.shard.id", + /** + * The partition the dispatch is ordered in (`guild:`, `channel:`...), when it has one. + */ + Partition: "discord.dispatch.partition", + /** + * The guild of the dispatch, when it belongs to one. + */ + GuildId: "discord.guild.id", + /** + * `success` or `error`, set when the processing ends. + */ + Outcome: "dispatch.outcome", +} as const; + +/** + * Which gateway dispatches get a span. + */ +export interface OpenTelemetryDispatchesOptions { + /** + * The dispatch types that get no span, such as `PRESENCE_UPDATE` or `TYPING_START` on a busy bot. + * + * @default [] + */ + ignore?: readonly string[]; +} diff --git a/packages/plugin-opentelemetry/src/lib/dispatches.ts b/packages/plugin-opentelemetry/src/lib/dispatches.ts new file mode 100644 index 00000000..406b79ce --- /dev/null +++ b/packages/plugin-opentelemetry/src/lib/dispatches.ts @@ -0,0 +1,108 @@ +import { + context as otelContext, + ROOT_CONTEXT, + SpanKind, + SpanStatusCode, + trace, +} from "@opentelemetry/api"; +import { + DispatchAttributes, + TRACER_NAME, + type OpenTelemetryDispatchesOptions, +} from "./attributes.js"; + +/** + * The dispatch `GatewayClient#addDispatchWrapper` of `@wolfstar/plugin-gateway` hands to a wrapper. Structural, so this + * package does not depend on the gateway. + */ +interface WrappedDispatch { + payload: { t: string; d?: unknown }; + shardId: number; + partition: string | null; +} + +/** + * The slice of a `GatewayClient` of `@wolfstar/plugin-gateway` this package uses. + */ +export interface DispatchTracingHost { + addDispatchWrapper( + wrapper: (dispatch: WrappedDispatch, run: () => Promise) => Promise, + ): () => void; +} + +/** + * Whether the client is a `GatewayClient` of `@wolfstar/plugin-gateway` 0.17 or later, which can wrap its dispatches. + * + * @param client The client. + */ +export function canTraceDispatches(client: object): client is DispatchTracingHost { + return typeof (client as Partial).addDispatchWrapper === "function"; +} + +/** + * Opens a span around the processing of each gateway dispatch: its cache writes, its listeners, and whatever they start + * (`pg`, `ioredis`, `undici`, ...) become its children. + * + * @remarks + * Each span is the root of a trace of its own. `@discordjs/ws` receives every dispatch in the context of the request + * that opened the WebSocket, so a span started in the active context would put all of the gateway's work in one trace + * that never ends. + * + * @param client The gateway client. + * @param options Which dispatches get a span. + * @returns A function that stops opening spans. + */ +export function attachDispatchTracing( + client: DispatchTracingHost, + options: Required, +): () => void { + const tracer = trace.getTracer(TRACER_NAME); + const ignored = new Set(options.ignore); + + return client.addDispatchWrapper((dispatch, run) => { + const type = dispatch.payload.t; + if (ignored.has(type)) return run(); + + const guildId = guildOf(dispatch.payload.d); + const span = tracer.startSpan( + `dispatch ${type}`, + { + root: true, + kind: SpanKind.CONSUMER, + attributes: { + [DispatchAttributes.Type]: type, + [DispatchAttributes.ShardId]: dispatch.shardId, + ...(dispatch.partition !== null && { + [DispatchAttributes.Partition]: dispatch.partition, + }), + ...(guildId !== null && { [DispatchAttributes.GuildId]: guildId }), + }, + }, + ROOT_CONTEXT, + ); + + return otelContext.with(trace.setSpan(ROOT_CONTEXT, span), async () => { + try { + await run(); + span.setAttribute(DispatchAttributes.Outcome, "success"); + } catch (error) { + const exception = error instanceof Error ? error : String(error); + span.recordException(exception); + span.setStatus({ + code: SpanStatusCode.ERROR, + message: typeof exception === "string" ? exception : exception.message, + }); + span.setAttribute(DispatchAttributes.Outcome, "error"); + throw error; + } finally { + span.end(); + } + }); + }); +} + +function guildOf(data: unknown): string | null { + if (typeof data !== "object" || data === null) return null; + const { guild_id: guildId } = data as { guild_id?: unknown }; + return typeof guildId === "string" ? guildId : null; +} diff --git a/packages/plugin-opentelemetry/src/plugin.ts b/packages/plugin-opentelemetry/src/plugin.ts index 4efb3249..43057ee4 100644 --- a/packages/plugin-opentelemetry/src/plugin.ts +++ b/packages/plugin-opentelemetry/src/plugin.ts @@ -1,5 +1,10 @@ import { definePlugin } from "@wolfstar/http-framework"; -import type { OpenTelemetryInteractionsOptions } from "./lib/attributes.js"; +import type { + OpenTelemetryDispatchesOptions, + OpenTelemetryInteractionsOptions, +} from "./lib/attributes.js"; +import { attachDispatchTracing, canTraceDispatches } from "./lib/dispatches.js"; +import { flushTraces } from "./lib/flush.js"; import { attachInteractionTracing } from "./lib/interactions.js"; /** @@ -13,11 +18,36 @@ export interface OpenTelemetryPluginOptions { * @default true */ interactions?: boolean | OpenTelemetryInteractionsOptions; + + /** + * Opens a span for every gateway dispatch a `GatewayClient` of `@wolfstar/plugin-gateway` (0.17 or later) processes, + * the root of a trace of its own, carrying its type, shard and guild. `true` takes the defaults, `false` turns it off. + * Ignored on a client that does not connect to the gateway. + * + * @default true + */ + dispatches?: boolean | OpenTelemetryDispatchesOptions; + + /** + * Exports the spans left in the batch at the end of `GatewayClient#destroy` (`@wolfstar/plugin-gateway` 0.17 or + * later), with {@link flushTraces}. Ignored on a client that does not connect to the gateway. + * + * @default true + */ + flushOnDestroy?: boolean; +} + +/** + * The slice of a `GatewayClient` of `@wolfstar/plugin-gateway` the plugin flushes the traces from. + */ +interface DestroyHookHost { + addDestroyHook(hook: () => unknown): () => void; } /** - * The OpenTelemetry plugin factory: opens one span per interaction, so the spans of the libraries the SDK instruments - * (`pg`, `ioredis`, `undici`, ...) have the command or the handler that ran them as their parent. + * The OpenTelemetry plugin factory: opens one span per interaction, and one per gateway dispatch on a `GatewayClient`, + * so the spans of the libraries the SDK instruments (`pg`, `ioredis`, `undici`, ...) have the command, the handler or + * the dispatch that ran them as their parent. On a `GatewayClient`, it also flushes the traces when it is destroyed. * * The spans are only exported when an SDK runs: start it with the `@wolfstar/plugin-opentelemetry/preload` entrypoint, * loaded with `--import`. Without one, `@opentelemetry/api` hands out no-op spans and this plugin costs nothing. @@ -33,23 +63,32 @@ export interface OpenTelemetryPluginOptions { * ``` */ const openTelemetryPlugin = definePlugin((options: OpenTelemetryPluginOptions = {}) => { - const { interactions = true } = options; + const { interactions = true, dispatches = true, flushOnDestroy = true } = options; return { name: "@wolfstar/plugin-opentelemetry", postInitialization(client) { - if (!interactions) return; - - attachInteractionTracing(client, { - commands: true, - autocomplete: false, - handlers: true, - ...(interactions === true ? {} : interactions), - }); + if (interactions) { + attachInteractionTracing(client, { + commands: true, + autocomplete: false, + handlers: true, + ...(interactions === true ? {} : interactions), + }); + } + + if (dispatches && canTraceDispatches(client)) { + attachDispatchTracing(client, { ignore: [], ...(dispatches === true ? {} : dispatches) }); + } + + const host = client as Partial; + if (flushOnDestroy && typeof host.addDestroyHook === "function") { + host.addDestroyHook(flushTraces); + } }, }; }); export default openTelemetryPlugin; -export type { OpenTelemetryInteractionsOptions }; +export type { OpenTelemetryDispatchesOptions, OpenTelemetryInteractionsOptions }; diff --git a/packages/plugin-opentelemetry/tests/dispatches.test.ts b/packages/plugin-opentelemetry/tests/dispatches.test.ts new file mode 100644 index 00000000..561dfc46 --- /dev/null +++ b/packages/plugin-opentelemetry/tests/dispatches.test.ts @@ -0,0 +1,148 @@ +import { context, ROOT_CONTEXT, SpanStatusCode, trace } from "@opentelemetry/api"; +import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks"; +import { + InMemorySpanExporter, + SimpleSpanProcessor, + TracerProvider, + type ReadableSpan, +} from "@opentelemetry/sdk-trace"; +import { GatewayClient } from "@wolfstar/plugin-gateway"; +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest"; +import { DispatchAttributes } from "../src/lib/attributes"; +import openTelemetryPlugin, { type OpenTelemetryPluginOptions } from "../src/plugin"; + +const exporter = new InMemorySpanExporter(); +const provider = new TracerProvider({ spanProcessors: [new SimpleSpanProcessor({ exporter })] }); + +beforeAll(() => { + context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable()); + trace.setGlobalTracerProvider(provider); +}); + +afterAll(async () => { + trace.disable(); + context.disable(); + await provider.shutdown(); +}); + +beforeEach(() => { + exporter.reset(); +}); + +afterEach(() => { + vi.restoreAllMocks(); +}); + +function createClient(options?: OpenTelemetryPluginOptions) { + return new GatewayClient({ + discordPublicKey: "0".repeat(64), + discordToken: "test-token", + clientId: "266624760782258186", + intents: 0, + cache: null, + plugins: [openTelemetryPlugin(options)], + }); +} + +function send(client: GatewayClient, t: string, d: Record, shardId = 0) { + // `WebSocketShardEvents.Dispatch` of `@discordjs/ws`. + client.gateway.emit("dispatch" as never, { op: 0, s: 1, t, d } as never, shardId as never); +} + +const typing = { channel_id: "20", guild_id: "10", user_id: "30", timestamp: 0 }; + +function dispatchSpans(): ReadableSpan[] { + return exporter.getFinishedSpans().filter((span) => span.name.startsWith("dispatch ")); +} + +describe("dispatch spans", () => { + test("GIVEN a dispatch THEN its span is the root of a trace and the parent of what its listeners start", async () => { + const client = createClient(); + client.on("typingStart", () => { + trace.getTracer("test").startSpan("listener work").end(); + }); + + // Like `@discordjs/ws`, which receives every dispatch in the context of the request that opened the WebSocket. + const handshake = trace.getTracer("test").startSpan("GET /gateway"); + context.with(trace.setSpan(ROOT_CONTEXT, handshake), () => + send(client, "TYPING_START", typing, 2), + ); + await client.idle(); + handshake.end(); + + const [dispatch] = dispatchSpans(); + const work = exporter.getFinishedSpans().find((span) => span.name === "listener work")!; + expect(dispatch!.name).toBe("dispatch TYPING_START"); + expect(dispatch!.parentSpanContext).toBeUndefined(); + expect(dispatch!.spanContext().traceId).not.toBe(handshake.spanContext().traceId); + expect(work.parentSpanContext?.spanId).toBe(dispatch!.spanContext().spanId); + expect(dispatch!.attributes).toEqual({ + [DispatchAttributes.Type]: "TYPING_START", + [DispatchAttributes.ShardId]: 2, + [DispatchAttributes.Partition]: "guild:10", + [DispatchAttributes.GuildId]: "10", + [DispatchAttributes.Outcome]: "success", + }); + }); + + test("GIVEN a failing listener THEN the span records the error and the client still reports it", async () => { + const client = createClient(); + const errors: unknown[] = []; + client.on("error", (error) => errors.push(error)); + client.on("typingStart", () => { + throw new Error("listener failed"); + }); + + send(client, "TYPING_START", typing); + await client.idle(); + + const [dispatch] = dispatchSpans(); + expect(dispatch!.status).toEqual({ code: SpanStatusCode.ERROR, message: "listener failed" }); + expect(dispatch!.attributes[DispatchAttributes.Outcome]).toBe("error"); + expect(dispatch!.events.map((event) => event.name)).toEqual(["exception"]); + expect(errors).toHaveLength(1); + }); + + test("GIVEN ignored types THEN those dispatches get no span", async () => { + const client = createClient({ dispatches: { ignore: ["TYPING_START"] } }); + const started: unknown[] = []; + client.on("typingStart", (typingStart) => started.push(typingStart)); + + send(client, "TYPING_START", typing); + await client.idle(); + + expect(started).toHaveLength(1); + expect(dispatchSpans()).toEqual([]); + }); + + test("GIVEN dispatches false THEN no dispatch gets a span", async () => { + const client = createClient({ dispatches: false }); + + send(client, "TYPING_START", typing); + await client.idle(); + + expect(dispatchSpans()).toEqual([]); + }); +}); + +describe("flushing on destroy", () => { + test("GIVEN a destroyed gateway client THEN the traces are flushed", async () => { + const client = createClient(); + vi.spyOn(client.gateway, "destroy").mockResolvedValue(); + const flush = vi.spyOn(provider, "forceFlush"); + + await client.destroy(); + + expect(flush).toHaveBeenCalledTimes(1); + }); + + test("GIVEN flushOnDestroy false THEN destroy does not flush", async () => { + const client = createClient({ flushOnDestroy: false }); + vi.spyOn(client.gateway, "destroy").mockResolvedValue(); + const flush = vi.spyOn(provider, "forceFlush"); + + await client.destroy(); + + expect(flush).not.toHaveBeenCalled(); + }); +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 724ca14f..749a71c6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -475,6 +475,9 @@ importers: '@wolfstar/kit': specifier: ^0.3.1 version: 0.3.1(magicast@0.5.5) + '@wolfstar/plugin-gateway': + specifier: workspace:^ + version: link:../plugin-gateway '@wolfstar/schema': specifier: ^0.12.0 version: 0.12.0(magicast@0.5.5) From 9ab2400ad49039bf8698049e712a4ab8a6001f69 Mon Sep 17 00:00:00 2001 From: RedStar Date: Fri, 13 Nov 2026 17:44:50 +0100 Subject: [PATCH 3/4] fix(plugin-opentelemetry): set the guild of guild create, update and delete spans GUILD_CREATE, GUILD_UPDATE and GUILD_DELETE carry the guild in id, not guild_id, so their dispatch spans had no discord.guild.id. Fall back to the guild: partition the gateway already derives for them. --- .../plugin-opentelemetry/src/lib/dispatches.ts | 8 +++++++- .../plugin-opentelemetry/tests/dispatches.test.ts | 14 ++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/packages/plugin-opentelemetry/src/lib/dispatches.ts b/packages/plugin-opentelemetry/src/lib/dispatches.ts index 406b79ce..0f34cd19 100644 --- a/packages/plugin-opentelemetry/src/lib/dispatches.ts +++ b/packages/plugin-opentelemetry/src/lib/dispatches.ts @@ -63,7 +63,7 @@ export function attachDispatchTracing( const type = dispatch.payload.t; if (ignored.has(type)) return run(); - const guildId = guildOf(dispatch.payload.d); + const guildId = guildOf(dispatch.payload.d) ?? guildOfPartition(dispatch.partition); const span = tracer.startSpan( `dispatch ${type}`, { @@ -106,3 +106,9 @@ function guildOf(data: unknown): string | null { const { guild_id: guildId } = data as { guild_id?: unknown }; return typeof guildId === "string" ? guildId : null; } + +// `GUILD_CREATE`, `GUILD_UPDATE` and `GUILD_DELETE` carry the guild in `id`, which the gateway already turned into the +// `guild:` partition, as it does for every other dispatch of a guild. +function guildOfPartition(partition: string | null): string | null { + return partition?.startsWith("guild:") ? partition.slice("guild:".length) : null; +} diff --git a/packages/plugin-opentelemetry/tests/dispatches.test.ts b/packages/plugin-opentelemetry/tests/dispatches.test.ts index 561dfc46..42c42793 100644 --- a/packages/plugin-opentelemetry/tests/dispatches.test.ts +++ b/packages/plugin-opentelemetry/tests/dispatches.test.ts @@ -85,6 +85,20 @@ describe("dispatch spans", () => { }); }); + test.each(["GUILD_CREATE", "GUILD_UPDATE", "GUILD_DELETE"])( + "GIVEN a %s dispatch, whose guild is its id THEN the span carries the guild", + async (type) => { + const client = createClient(); + client.on("error", () => undefined); + + send(client, type, { id: "10", unavailable: true }); + await client.idle(); + + const [dispatch] = dispatchSpans(); + expect(dispatch!.attributes[DispatchAttributes.GuildId]).toBe("10"); + }, + ); + test("GIVEN a failing listener THEN the span records the error and the client still reports it", async () => { const client = createClient(); const errors: unknown[] = []; From 529ae72e98437720f1e88a78bc95693ad76d3c7f Mon Sep 17 00:00:00 2001 From: RedStar Date: Fri, 13 Nov 2026 17:45:14 +0100 Subject: [PATCH 4/4] docs(plugin-opentelemetry): note where the guild of a guild dispatch span comes from --- packages/plugin-opentelemetry/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/plugin-opentelemetry/README.md b/packages/plugin-opentelemetry/README.md index 44004d50..2065e021 100644 --- a/packages/plugin-opentelemetry/README.md +++ b/packages/plugin-opentelemetry/README.md @@ -139,13 +139,13 @@ A failing run records the exception and sets the span status to `ERROR`. A gateway dispatch gets a span named `dispatch ` (`dispatch MESSAGE_CREATE`) around its cache writes and its listeners, so what they start has it as a parent. It carries: -| Attribute | Value | -| ---------------------------- | ------------------------------------------------ | -| `discord.dispatch.type` | The type of the dispatch. | -| `discord.shard.id` | The gateway shard it came from. | -| `discord.dispatch.partition` | The partition it is ordered in, when it has one. | -| `discord.guild.id` | The guild, when the dispatch belongs to one. | -| `dispatch.outcome` | `success` or `error`. | +| Attribute | Value | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `discord.dispatch.type` | The type of the dispatch. | +| `discord.shard.id` | The gateway shard it came from. | +| `discord.dispatch.partition` | The partition it is ordered in, when it has one. | +| `discord.guild.id` | The guild, when the dispatch belongs to one (its `id` for `GUILD_CREATE`, `GUILD_UPDATE` and `GUILD_DELETE`). | +| `dispatch.outcome` | `success` or `error`. | Each dispatch span is the root of a trace of its own: `@discordjs/ws` receives every dispatch in the context of the request that opened the WebSocket, and a span started there would put all of the gateway's work in one trace that never