[OTEL] Logging setup - #2853
Draft
George Ng (GeorgeNgMsft) wants to merge 6 commits into
Draft
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
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 an OpenTelemetry structured-log pipeline for TypeAgent and wires it into every TypeAgent-owned Node host. Structured-log export is explicitly opt-in (default false ) because dispatcher event payloads may contain user data. No changes to existing debug / DEBUG behavior — this builds on the previously-landed OTel bootstrap/config/redaction primitives.
Changes
New telemetry primitives ( packages/telemetry )
• OtelLoggerSink ( logger/otelLoggerSink.ts ) — a LoggerSink that maps severity-aware Structured Logger events onto OTel Logs, promotes correlation fields ( sessionId , activationId , traceId ) to well-known span attributes, does bounded/cycle-safe body mapping, and applies defense-in-depth redaction. Pulls its logger from the global OTel API on demand; never owns a provider.
• Debug bridge ( otel/debugBridge.ts ) — copies enabled typeagent:* debug output to OTel logs. Supports multi-instance bridging, configurable included/excluded namespace prefixes, reference-counted idempotent installation, and rejects conflicting install options. Prompt logger stays excluded.
• JSONL log exporter ( otel/jsonlLogExporter.ts ) — bounded, process-safe local log file export, independent of any OTLP endpoint.
• Config ( otel/config.ts ) — adds telemetry.structuredLogs and telemetry.debugBridge , resolved from layered YAML plus TYPEAGENT_OTEL_* env overrides (e.g. TYPEAGENT_OTEL_STRUCTURED_LOGS ).
• Adds LogEventSeverity ( info | warning | error ) to the Logger / LoggerSink contract; severity is caller-supplied and never inferred.
Host wiring
• Dispatcher ( commandHandlerContext.ts ) — new DispatcherOptions.telemetry.structuredLogs ; getLoggerSink attaches OtelLoggerSink only when enabled. Existing debug + database sinks unchanged.
• Agent server, API, standalone shell — resolve telemetry config once, call initTelemetry({ config, debugModules, debugBridge }) , and pass structuredLogs into the dispatchers they create. Agent-server hosts include the legacy agent-server:* namespace without renaming.
• CLI entry points & agent subprocesses provide their local debug module instances to telemetry init.
Agent subprocess support
• agentDebug.ts resolves an agent's local debug package (via CommonJS createRequire , Windows-safe) so separately-installed module instances are bridged.
Docs & config
• Updates docs/architecture/telemetry/opentelemetry.md and config.sample.yaml with debugBridge / structuredLogs options.
Tests
• New/expanded suites: otelLoggerSink.spec.ts (~1025 lines), otelLocalDiagnostics.spec.ts , otelConfig.spec.ts , logger.spec.ts , agentDebug.spec.ts , plus otelBootstrap.spec.ts updates.
• Cover severity mapping, redaction, correlation, multi-instance debug bridging, reference counting, conflicting options, legacy namespace inclusion, prompt-logger exclusion, YAML/env config resolution, and Windows-safe agent-local debug loading.