docs(telemetry): comprehensive documentation update to match current implementation - #5960
Merged
Conversation
- Add Last-Event-ID client reconnect guide (10-event-bus, 13-sdk-daemon-client) - Add cross-connection vote routing section (04-permission-mediation) - Add new capability tags: daemon_status, workspace_permissions, workspace_trust, workspace_github_setup, workspace_voice, workspace_voice_transcription, voice_transcribe (11-capabilities-versioning) - Add new event types: trust_change_requested, github_setup_completed, extensions_changed, mid_turn_message_injected (09-event-schema) - Fix _meta.serverTimestamp source description (09-event-schema, 10-event-bus) - Fix async function* syntax in SDK example (13-sdk-daemon-client) - Sync event/capability counts across all docs (43->47 events, 67->75 tags)
Design document for the sessionless workspace remember API proposed in PR #5884. Covers API endpoints, task lifecycle, implementation details, events, error handling, and SDK integration. Status: Proposed (not yet merged).
Added 34 undocumented events, 17 metrics, 11 daemon metrics, 2 spans. Fixed diff_stat attribute schema (was documented as JSON string, actually individual attributes). Added Performance Monitoring reserved section. Standardized attribute annotations with type and optionality markers.
…qwen-code prefix Extracted hardcoded event name to constant for consistency with other telemetry events. Added standard qwen-code. namespace prefix. Updated test assertion to match the new prefixed event name.
Collaborator
|
Thanks for the PR! Template looks good ✓ On direction: this fills a real gap — the telemetry docs were severely outdated (only 11 of 45 events documented). Accurate telemetry documentation is essential for anyone working on observability, performance, or debugging features. Clearly aligned with the project's needs. On approach: the scope feels right for a comprehensive docs refresh. The only behavioral code change — extracting Moving on to code review. 🔍 中文说明感谢贡献！ 模板完整 ✓ 方向：填补了真实空白——遥测文档严重过时（45 个事件中仅记录了 11 个）。准确的遥测文档对于可观测性、性能和调试功能的开发者至关重要，与项目需求高度对齐。 方案：作为全面的文档刷新，范围合理。唯一的行为性代码变更——将 进入代码审查 🔍 — Qwen Code · qwen3.7-max |
Contributor
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
Collaborator
Code ReviewIndependent proposal: If I were updating stale telemetry docs, I'd (1) audit every event/metric/span constant in Comparison: The PR's approach matches my baseline. It adds 34 previously undocumented events, 17 metrics, 11 daemon metrics, and 2 spans — all with accurate attribute schemas verified against source. The No critical blockers found. The code changes are minimal and correct. The docs are comprehensive and accurate based on spot-checks against TestingUnit tests (worktree on PR branch): Real-scenario test (installed build): Installed build responds correctly. The --- Qwen Code · qwen3.7-max |
Collaborator
|
Stepping back: this PR does what it says on the tin. The telemetry docs were genuinely outdated — 34 undocumented events, incorrect attribute schemas, missing daemon metrics. The PR fills all those gaps with accurate, well-organized documentation that I verified against the source code. The one behavioral change — extracting All 56 telemetry tests pass. The formatting-only changes in test files are minor noise from the branch base but don't affect behavior. Maintainer wenshao has already approved after the author addressed earlier feedback. Clean docs PR, ships as described. ✅ 中文说明回顾整体：这个 PR 如其所述。遥测文档确实过时——34 个未记录的事件、错误的属性模式、缺失的守护进程指标。PR 用准确、组织良好的文档填补了所有空白，我已对照源代码进行了验证。 唯一的行为变更——将 全部 56 个遥测测试通过。测试文件中的纯格式化变更来自分支基础的少量噪音，不影响行为。维护者 wenshao 在作者处理了早期反馈后已批准。 干净的文档 PR，按描述交付。✅ — Qwen Code · qwen3.7-max |
qwen-code-ci-bot
previously approved these changes
Jun 28, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
LGTM, looks ready to ship. ✅
…-documentation # Conflicts: # docs/design/daemon-workspace-remember.md # docs/developers/daemon/00-index.md # docs/developers/daemon/13-sdk-daemon-client.md
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
Testing comment 1 of 3...
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
Testing comment 2 of 3...
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
Review Summary
5 findings across 3 categories after multi-dimensional review (correctness, security, code quality, performance, test coverage, 3x undirected audit, build/test). All findings are Suggestion-level — no blocking issues.
1. Dual event-name field in tool_output_truncated log records
ToolOutputTruncatedEvent in types.ts:776 still has readonly eventName = 'tool_output_truncated' (un-prefixed). Since loggers.ts spreads ...event into attributes, the emitted log record now contains two event-name fields with different values: 'event.name' = 'qwen-code.tool_output_truncated' (from the new constant) and eventName = 'tool_output_truncated' (stale class property).
Fix: update types.ts:776 to use the EVENT_TOOL_OUTPUT_TRUNCATED constant, or remove the eventName property.
2. Inaccurate "not yet enabled in production" claim for resource metrics
memoryPressureMonitor.ts:361-367 actively calls recordMemoryUsage and recordCpuUsage, and the gate at metrics.ts:682 is isPerformanceMonitoringEnabled = config.getTelemetryEnabled() — so qwen-code.memory.usage and qwen-code.cpu.usage are live whenever telemetry is enabled, not behind a dedicated flag.
Fix: move these two metrics into a live "Resource Metrics" section. Keep the remaining metrics (startup.duration, tool.queue.depth, etc.) under "Reserved".
3. Stale UI type count in 14-cli-tui-adapter.md (pre-existing)
ui/types.ts defines 42 union members in DaemonUiEventType, but 14-cli-tui-adapter.md lines 9, 44, and 120 still say 37. This file is not in the current PR diff (the merge from main already brought in the wave-2 changes), but the stale count persists. Consider fixing in a follow-up.
4. Missing attributes in updated telemetry event docs
Several events in the updated docs are missing attributes that exist in source and are emitted via ...event spread:
api_erroromitsprompt_id(required inApiErrorEvent)api_responseomitsprompt_id,response_id,total_token_count(all required inApiResponseEvent)api_retrymarkserror_typeas(string)but it's optional (error_type?: stringin source)tool_callomitsstatus(string: "success"/"error"/"cancelled") andprompt_idgithub_setup_completedomitswarnings(requiredstring[]in daemon events interface)
5. Inconsistent type annotations across events
Some events fully annotate (prompt_length (int)) while others list bare names (model, status_code). Token counts use (int) everywhere except compression_input_token_count/compression_output_token_count which use (number, optional).
Verified: 647 telemetry tests pass across 20 test files. Build and typecheck clean.
— qwen3.7-max via Qwen Code /review
wenshao
reviewed
Jun 28, 2026
qwen-code-ci-bot
requested changes
Jun 28, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
Independent review confirms no new issues beyond the existing feedback.
Review summary:
- Deterministic analysis (tsc, eslint): 0 findings
- Build & test: all 647 telemetry tests pass
- Security: no issues (no secrets, no data exposure, TRACEPARENT/TRACESTATE docs verified accurate against shellContextEnv.ts)
- Correctness: constant extraction is correct; test assertion properly validates the namespaced event name while retaining the short-form
eventNamefrom the class spread - Performance: no impact (constant reference vs string literal is indistinguishable)
- 9 parallel review agents (correctness, security, code quality, performance, test coverage, 3× undirected audit, build/test) all converged — the 4 open threads from the prior review cover the substantive remaining items
The 4 open items from the prior review are the outstanding action items: (1) error_message vs error.message attribute naming for api_error/chat.invalid_chunk, (2) missing OTel attribute aliases (model_name, duration, http.status_code), (3) duration_ms semantics clarification for api_retry, and (4) missing type annotations on arena events.
— qwen3.7-max via Qwen Code /review
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
No review findings. Downgraded from Approve to Comment: CI still running. LGTM! ✅
— qwen3.7-max via Qwen Code /review
Collaborator
|
@qwen-code /triage |
wenshao
approved these changes
Jun 28, 2026
qwen-code-ci-bot
approved these changes
Jun 28, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
LGTM, looks ready to ship. ✅
wenshao
approved these changes
Jun 28, 2026
wenshao
left a comment
wenshao
left a comment
Collaborator
There was a problem hiding this comment.
Second-opinion review (glm-5.2) — no new issues found. LGTM! ✅
Verified across 9 dimensions (correctness, security, code quality, performance, test coverage, 3× undirected audit, build/test): the event-name constant extraction is consistent with the qwen-code.* namespace convention, all 647 telemetry tests pass, and the documented events/metrics/spans match their emit/recording call sites.
— glm-5.2 via Qwen Code /review
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Comprehensively updates the telemetry documentation to match the current implementation. Adds documentation for 34 previously undocumented events, 17 metrics, 11 daemon metrics, and 2 spans. Fixes an incorrect attribute schema for diff_stat (was documented as a single JSON string attribute, but the implementation emits individual numeric attributes). Adds new sections for Daemon Metrics and Performance Monitoring (Reserved). Standardizes attribute type annotations and optionality markers throughout. Also extracts a hardcoded event name (
tool_output_truncated) into a named constant with the standardqwen-code.namespace prefix for consistency.EVENT_TOOL_OUTPUT_TRUNCATEDchanges the emitted telemetry event name fromtool_output_truncatedtoqwen-code.tool_output_truncated. This aligns it with every other event constant inconstants.tswhich all use theqwen-code.namespace prefix. If any downstream consumers filter on the old un-prefixed name, they will need to update their filters.Scope note: This branch includes commits from
docs/daemon-refresh-wave2(daemon developer docs updates) as a base. The telemetry-specific changes are in commits6956f11d6andda7918983.Why it's needed
The telemetry documentation was severely outdated — only 11 of 45 events, 8 of 23+ metrics, and 5 of 7 spans were documented. Critical attribute schema errors existed (e.g.,
diff_statdocumented as a JSON string when the code actually emits individual attributes likemodel_added_lines,model_removed_lines). This made it difficult for developers to understand what telemetry the system produces, leading to potential misuse or duplication. The constant extraction fixes an inconsistency where one event name was hardcoded inline rather than declared alongside the others.Reviewer Test Plan
How to verify
packages/core/src/telemetry/— each documented event/metric/span should correspond to an actual emit call in the source.npm run build && cd packages/core && npx vitest run src/telemetry/to confirm all telemetry tests pass with the updated constant name.Evidence (Before & After)
N/A (documentation and minor constant refactor)
Tested on
Environment (optional)
N/A — documentation change plus unit test verification.
Risk & Scope
tool_output_truncated→qwen-code.tool_output_truncated) could affect downstream telemetry consumers filtering on the old name. The fix is correct (consistent with all other events), but consumers should be aware.tool_output_truncatedshould update toqwen-code.tool_output_truncated.Linked Issues
None.