Repository navigation
feat(plugin-opentelemetry): open a span per gateway dispatch and flush on destroy - #288
Conversation
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
…h 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
Architecture Inside the changed components — 1 viewComponent view — OpenTelemetry dispatch tracing Internal dispatch wrapper attaching root spans to gateway dispatches
Data flow Review 1 finding · reviewed
|
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Reviewed the full diff of both commits. I also ran packages/plugin-opentelemetry/tests/dispatches.test.ts and packages/plugin-gateway/tests/hooks.test.ts locally, and all 15 tests pass.
plugin-gatewayhook state inWeakMaps:addDispatchWrapperandaddDestroyHookno longer hit private fields that don't exist yet when a plugin'spostInitializationruns inside the baseClientconstructor. A test adds both from a plugin.- Dispatch spans:
attachDispatchTracingopens a rootdispatch <type>span (ROOT_CONTEXT,SpanKind.CONSUMER) around each dispatch. It sets type, shard, partition, guild and outcome, records the exception on failure and rethrows, so the client still reports the error. - Plugin options:
dispatches(boolean | { ignore }) andflushOnDestroy. Both are feature-detected by shape, so@wolfstar/plugin-gatewaystays a devDependency and non-gateway clients are unaffected. - Docs and release: README sections,
AGENTS.md, and aminorchangeset forplugin-opentelemetryplus apatchone forplugin-gateway.
claude-sonnet-5-5 | 𝕏
@wolfstar/plugin-api
@wolfstar/plugin-broker
@wolfstar/plugin-cache
@wolfstar/plugin-gateway
@wolfstar/plugin-i18next
@wolfstar/plugin-logger
@wolfstar/plugin-opentelemetry
@wolfstar/plugin-scheduled-tasks
@wolfstar/plugin-sharder
@wolfstar/plugin-subcommands-advanced
commit: |
…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:<id> partition the gateway already derives for them.
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Reviewed the two commits added since the prior pullfrog review (the base merge c971690 has no net change).
- Guild fallback for guild lifecycle dispatches:
GUILD_CREATE,GUILD_UPDATEandGUILD_DELETEcarry the guild inid, notguild_id, sodiscord.guild.idwas missing.guildOfPartitionnow derives it from theguild:<id>partition, which matches howDispatchQueue.tsbuilds the partition for those types. - Test and docs: a
test.eachcovers the three types, and the README attribute table notes where the guild comes from.
claude-sonnet-5-5 | 𝕏

Stacked on #287.
🔗 Linked issue
Resolves #261
🧭 Context
Last part of #261's second half:
plugin-gatewaydispatch wrappers and destroy hooksplugin-sharderexit and destroy hooksplugin-opentelemetrydispatch spans and theflushTraces()wiringUntil now the cache and database spans of a gateway dispatch had no parent of their own.
@discordjs/wsreceives every dispatch in the context of the request that opened the WebSocket, so the gateway's work also had nowhere to go but one trace that never ends.📚 Description
On a
GatewayClient, the plugin now usesaddDispatchWrapperto open adispatch <type>span around each dispatch. The span is the root of a trace of its own and carries the type, the shard, the partition, the guild and the outcome. Its cache writes and listeners run in its context, and a failing dispatch records the exception and is still reported by the client.dispatches: falseturns this off, anddispatches.ignoreskips noisy types.The plugin also adds
flushTracesas a destroy hook (flushOnDestroy, on by default), soGatewayClient#destroyexports what is left. The plugin can't see aShardClientor aShardManager, so the README shows how to passflushTracesto their hooks from #287.This PR also fixes #285. A plugin's
postInitializationruns inside the baseClientconstructor, beforeGatewayClient's private fields exist, soaddDispatchWrapperandaddDestroyHookthrew aTypeErrorexactly where a plugin calls them. They now keep their state in module-levelWeakMaps, with a test that adds both from a plugin. It ships as aplugin-gatewaypatch.Departures from Pullfrog's plan:
flushTraces()into the shard manager and shards. The plugin only ever sees the client, so the sharder gets generic hooks (feat(plugin-sharder): add shard exit hooks and manager destroy hooks #287) and the user wires them.Key changes
plugin-opentelemetry:src/lib/dispatches.ts, thedispatchesandflushOnDestroyoptions,DispatchAttributesandOpenTelemetryDispatchesOptions, andtests/dispatches.test.ts, which runs a realGatewayClient.@wolfstar/plugin-gatewaybecomes a devDependency only: the plugin checks the client's shape instead of importing the gateway.plugin-gateway: wrappers and hooks move toWeakMaps, plus a test that adds them from a plugin.AGENTS.md, aminorchangeset forplugin-opentelemetryand apatchone forplugin-gateway.Type of Change
Pre-flight Checklist
pnpm changeset(orpnpm changeset add --emptyif no release is needed). See .changeset/README.md.

Confidence Score: 5/5
The PR appears safe to merge, with the previous finding addressed and no new actionable issues found.Reviews (2) · Last reviewed commit: "docs(plugin-opentelemetry): note where t..." · Reviewed by Greptile