Proposal: OpenTelemetry adapter for standardized trace export

[Copilot]

UACS has robust local observability (semantic search, knowledge extraction, web UI) but no standardized export to enterprise APM platforms or cross-system correlation.

Proposal

Added comprehensive proposal for OpenTelemetry adapter that complements existing features:

• Full Proposal: docs/proposals/OPENTELEMETRY_ADAPTER_PROPOSAL.md (1,012 lines)
• Executive Summary: docs/proposals/README.md (quick reference)

Key Findings

Current Strengths:

• Semantic conversation tracking with natural language search
• Knowledge extraction (decisions, conventions, learnings)
• Next.js visualization with timeline/knowledge browser
• Crash-resistant JSONL storage

Gaps:

• No standardized export (UACS-specific JSONL only)
• No enterprise APM integration (Datadog, New Relic, CloudWatch)
• No multi-system trace correlation (W3C Trace Context)

OTel Value:

• Export to 50+ observability backends via OTLP
• Align with GenAI semantic conventions (2024 standard)
• Enable distributed tracing across agent + infrastructure
• Optional layer—preserves UACS's unique features

Architecture

UACS Core (Conversations + Knowledge)
    │
    ├─→ UACS Visualization [Keep]
    │   - Semantic search, knowledge browsing
    │
    └─→ OpenTelemetry Export [New]
        - Jaeger, Langfuse, Datadog, etc.

Dual-path: local UACS features + standardized export for enterprise integration.

Recommendation

Proceed with MVP (Phases 1-2, 2-4 weeks):

• Core OTel SDK integration with console/OTLP exporters
• Map UserMessage, AssistantMessage, ToolUse to GenAI spans
• YAML configuration + CLI commands
• Validate approach, gather feedback

Production-ready (Phases 3-4, 6-8 weeks):

• Multiple exporters (Langfuse, Datadog, Jaeger)
• Real-time Claude Code hooks
• Performance optimization (async, batching, <5% overhead)

Defer: W3C Trace Context, metrics/logs export (Phase 5—demand-driven)

Trade-offs

Pros: Industry standards, enterprise integration, vendor-neutral, low risk (opt-in)
Cons: Added complexity, ~1ms overhead per event, maintenance burden

Next Steps

1. Review with maintainers
2. Gather community feedback
3. Create implementation issue if approved

Original prompt

Review the repo. See if it's worth adding an open telemetry adapter to capture context. Just write a proposal.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.