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/.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-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"]); + }); +}); diff --git a/packages/plugin-opentelemetry/README.md b/packages/plugin-opentelemetry/README.md index a820e280..2065e021 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 (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 +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..0f34cd19 --- /dev/null +++ b/packages/plugin-opentelemetry/src/lib/dispatches.ts @@ -0,0 +1,114 @@ +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) ?? guildOfPartition(dispatch.partition); + 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; +} + +// `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/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..42c42793 --- /dev/null +++ b/packages/plugin-opentelemetry/tests/dispatches.test.ts @@ -0,0 +1,162 @@ +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.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[] = []; + 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)