[OTEL] Logging setup - #2853
Open
George Ng (GeorgeNgMsft) wants to merge 13 commits into
Open
Conversation
Add severity-aware Structured Logger events, bounded cycle-safe OTel body mapping, trace correlation, and defense-in-depth redaction. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 67859676-8c6c-43f7-bfe4-ee784f8db79d
Add multi-instance debug bridging, bounded process-safe JSONL log export, configuration, failure diagnostics, and correlated local integration coverage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 67859676-8c6c-43f7-bfe4-ee784f8db79d
### Summary
Builds on the previously-landed `OtelLoggerSink`, debug bridge, and
JSONL
exporter by **wiring them into every TypeAgent-owned Node host** and
making
structured-log export **explicitly opt-in**. No new telemetry primitives
— this
is composition, gating, and hardening. Existing `debug`/`DEBUG` output
is
unchanged.
### Changes
**Configuration-driven structured logs**
• Adds telemetry.structuredLogs , defaulting to false because
dispatcher event payloads may contain user data.
• Supports the TYPEAGENT_OTEL_STRUCTURED_LOGS environment override.
• Hosts resolve telemetry configuration once and pass the effective
value into DispatcherOptions.telemetry.structuredLogs .
• getLoggerSink attaches OtelLoggerSink only when structured logging
is enabled. Existing debug and database sinks are unchanged.
• Agent server, API, and standalone shell apply the setting to the
dispatchers they create.
**Host telemetry and debug-bridge wiring**
• Wires initTelemetry({ config, debugModules, debugBridge }) into the
agent server, API, and shell composition roots.
• CLI entry points and agent subprocesses provide their debug module
instances to telemetry initialization.
• Agent-server hosts include the legacy agent-server:* namespace
without renaming namespaces or breaking existing DEBUG configurations.
• Prompt logger output remains intentionally excluded from the debug
bridge.
**Agent subprocess support**
• Resolves an agent’s local debug package before telemetry
initialization so separately installed module instances are bridged.
• Uses CommonJS resolution rather than importing an absolute filesystem
path, preserving Windows compatibility.
• Extracts this behavior into agentDebug.ts with coverage for
agent-local and shared module instances.
**Debug-bridge hardening**
• Adds configurable included namespace prefixes while retaining
typeagent:* as the default.
• Tracks effective bridge options for each installed module.
• Rejects repeated installation with conflicting namespace or redaction
options instead of silently ignoring the later policy.
• Preserves idempotent, reference-counted installation when options
match.
**Tests**
• Covers real debug instances created before and after bridge
installation.
• Covers multiple debug module instances, restoration, reference
counting, and conflicting options.
• Verifies legacy namespace inclusion and continued prompt logger
exclusion.
• Covers YAML and environment resolution for telemetry.structuredLogs .
• Covers Windows-safe agent-local debug module loading.
---------
Copilot-Session: 6407aa6e-4d59-49ec-9fa4-5a321f2971ef
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> # Conflicts: # ts/packages/telemetry/src/otel/bootstrap.ts
Dominic Nguyen (datduyng)
approved these changes
Aug 13, 2026
George Ng (GeorgeNgMsft)
marked this pull request as ready for review
August 13, 2026 04:42
…/github.com/microsoft/TypeAgent into dev/georgeng/otel-phase2-structured-logging
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5d8cccd6-408a-4f05-90ae-71e254022055
George Ng (GeorgeNgMsft)
enabled auto-merge
August 13, 2026 06:47
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
2 participants
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.
Summary
Adds opt-in OpenTelemetry logging to TypeAgent. Logs can be written to a local JSONL file, exported through OTLP, and correlated with traces.
Logging Pipeline
Export and Privacy
Configuration and Developer Tools
Data Flow
Structured Logger → privacy filter → OTel Logs API ─┬→ local JSONL
Enabled debug output → debug bridge ────────────────└→ OTLP → Loki/Grafana
Active spans ─────────────────────────────────────────→ OTLP → Tempo/Grafana