UAT: Specification describes OpenTelemetry `TelemetryService` and `@trace` decorator that do not exist — spec contradicts ADR-025 #4041

New issue

Open

opened 2026-04-06 09:06:29 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 09:06:29 +00:00

Owner

Metadata

Branch: fix/docs/remove-opentelemetry-spec-contradiction
Commit Message: docs(spec): remove OpenTelemetry TelemetryService and @trace decorator — align spec with ADR-025
Milestone: (none — backlog)
Parent Epic: #3374

Bug Report

What Was Tested

Code-level analysis of the telemetry and observability implementation against the specification.

Expected Behavior (from spec)

The specification (docs/specification.md) describes two components that should exist:

1. TelemetryService — responsible for collecting and exporting telemetry data with multiple exporters:

otlp_http — Exports to an OpenTelemetry collector via HTTP
otlp_grpc — Exports to an OpenTelemetry collector via gRPC
console — Prints telemetry data to the console (for debugging)
in_memory — Stores telemetry data in memory (for testing)

With configuration:

[telemetry]
service_name = "cleveragents"
enabled = true

[[telemetry.exporters]]
type = "otlp_http"
endpoint = "http://localhost:4318"

2. TraceService (per spec) — described as "the central component for managing OpenTelemetry tracing" with:

TracerProvider initialization
SpanExporter configuration
BatchSpanProcessor pipeline
Context propagation across async tasks
A @trace decorator from cleveragents.telemetry:

from cleveragents.telemetry import trace

@trace
def my_function(arg1, arg2):
    # This function is now traced
    ...

Actual Behavior

No TelemetryService exists — there is no TelemetryService class anywhere in src/cleveragents/
No cleveragents.telemetry module exists — from cleveragents.telemetry import trace raises ImportError
No @trace decorator exists — no such decorator is defined anywhere in the codebase
No OpenTelemetry integration — no opentelemetry imports, no TracerProvider, no SpanExporter, no BatchSpanProcessor
The actual TraceService (src/cleveragents/application/services/trace_service.py) is a completely different component — it manages LLMTrace persistence and LangSmith forwarding, NOT OpenTelemetry spans

Root Cause

ADR-025 (docs/adr/ADR-025-observability-and-logging.md) explicitly decided NOT to use OpenTelemetry:

"OpenTelemetry for tracing — A more general-purpose observability framework, but adds significant complexity. LangSmith provides LLM-specific tracing that is more targeted to CleverAgents' needs. OpenTelemetry could be added later as a complementary integration."

The specification was not updated to reflect this ADR decision, creating a contradiction between the spec and the ADR.

Impact

Developers reading the spec will attempt to use from cleveragents.telemetry import trace and get an ImportError
The TOML configuration for [telemetry] exporters has no effect (no code reads it)
Any code expecting a TelemetryService in the DI container will fail

Code Locations

Missing: src/cleveragents/telemetry/ module (does not exist)
Missing: TelemetryService class (does not exist)
Spec: docs/specification.md — Telemetry section (describes OpenTelemetry)
ADR: docs/adr/ADR-025-observability-and-logging.md — explicitly rejected OpenTelemetry

Fix Required

Either:

Update the specification to remove the OpenTelemetry TelemetryService and @trace decorator sections, replacing them with the actual structlog + LangSmith approach described in ADR-025
OR implement the TelemetryService and @trace decorator as described in the spec (implementing OpenTelemetry)

Option 1 is recommended since ADR-025 was accepted and the implementation follows it.

Subtasks

Identify all OpenTelemetry references in docs/specification.md (TelemetryService, @trace decorator, TOML exporter config)
Update spec to remove or replace OpenTelemetry TelemetryService section with actual structlog + LangSmith approach
Update spec to remove @trace decorator documentation and replace with actual tracing API
Update spec TOML configuration examples to remove [telemetry] exporter blocks that have no implementation
Verify no other spec sections reference cleveragents.telemetry module
Run nox (all default sessions), fix any errors

Definition of Done

All subtasks above are completed and checked off
docs/specification.md no longer describes TelemetryService, @trace decorator, or OpenTelemetry exporter config that contradicts ADR-025
Spec accurately reflects the structlog + LangSmith observability approach from ADR-025
A Git commit is created where the first line matches the Commit Message in Metadata exactly
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.5.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/docs/remove-opentelemetry-spec-contradiction` - **Commit Message**: `docs(spec): remove OpenTelemetry TelemetryService and @trace decorator — align spec with ADR-025` - **Milestone**: *(none — backlog)* - **Parent Epic**: #3374 ## Bug Report ### What Was Tested Code-level analysis of the telemetry and observability implementation against the specification. ### Expected Behavior (from spec) The specification (`docs/specification.md`) describes two components that should exist: **1. `TelemetryService`** — responsible for collecting and exporting telemetry data with multiple exporters: - `otlp_http` — Exports to an OpenTelemetry collector via HTTP - `otlp_grpc` — Exports to an OpenTelemetry collector via gRPC - `console` — Prints telemetry data to the console (for debugging) - `in_memory` — Stores telemetry data in memory (for testing) With configuration: ```toml [telemetry] service_name = "cleveragents" enabled = true [[telemetry.exporters]] type = "otlp_http" endpoint = "http://localhost:4318" ``` **2. `TraceService`** (per spec) — described as "the central component for managing OpenTelemetry tracing" with: - `TracerProvider` initialization - `SpanExporter` configuration - `BatchSpanProcessor` pipeline - Context propagation across async tasks - A `@trace` decorator from `cleveragents.telemetry`: ```python from cleveragents.telemetry import trace @trace def my_function(arg1, arg2): # This function is now traced ... ``` ### Actual Behavior 1. **No `TelemetryService` exists** — there is no `TelemetryService` class anywhere in `src/cleveragents/` 2. **No `cleveragents.telemetry` module exists** — `from cleveragents.telemetry import trace` raises `ImportError` 3. **No `@trace` decorator exists** — no such decorator is defined anywhere in the codebase 4. **No OpenTelemetry integration** — no `opentelemetry` imports, no `TracerProvider`, no `SpanExporter`, no `BatchSpanProcessor` 5. **The actual `TraceService`** (`src/cleveragents/application/services/trace_service.py`) is a completely different component — it manages `LLMTrace` persistence and LangSmith forwarding, NOT OpenTelemetry spans ### Root Cause **ADR-025** (`docs/adr/ADR-025-observability-and-logging.md`) explicitly decided NOT to use OpenTelemetry: > "OpenTelemetry for tracing — A more general-purpose observability framework, but adds significant complexity. LangSmith provides LLM-specific tracing that is more targeted to CleverAgents' needs. OpenTelemetry could be added later as a complementary integration." The specification was not updated to reflect this ADR decision, creating a contradiction between the spec and the ADR. ### Impact - Developers reading the spec will attempt to use `from cleveragents.telemetry import trace` and get an `ImportError` - The TOML configuration for `[telemetry]` exporters has no effect (no code reads it) - Any code expecting a `TelemetryService` in the DI container will fail ### Code Locations - **Missing**: `src/cleveragents/telemetry/` module (does not exist) - **Missing**: `TelemetryService` class (does not exist) - **Spec**: `docs/specification.md` — Telemetry section (describes OpenTelemetry) - **ADR**: `docs/adr/ADR-025-observability-and-logging.md` — explicitly rejected OpenTelemetry ### Fix Required Either: 1. **Update the specification** to remove the OpenTelemetry `TelemetryService` and `@trace` decorator sections, replacing them with the actual structlog + LangSmith approach described in ADR-025 2. **OR implement** the `TelemetryService` and `@trace` decorator as described in the spec (implementing OpenTelemetry) Option 1 is recommended since ADR-025 was accepted and the implementation follows it. ## Subtasks - [ ] Identify all OpenTelemetry references in `docs/specification.md` (TelemetryService, @trace decorator, TOML exporter config) - [ ] Update spec to remove or replace OpenTelemetry `TelemetryService` section with actual structlog + LangSmith approach - [ ] Update spec to remove `@trace` decorator documentation and replace with actual tracing API - [ ] Update spec TOML configuration examples to remove `[telemetry]` exporter blocks that have no implementation - [ ] Verify no other spec sections reference `cleveragents.telemetry` module - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] All subtasks above are completed and checked off - [ ] `docs/specification.md` no longer describes `TelemetryService`, `@trace` decorator, or OpenTelemetry exporter config that contradicts ADR-025 - [ ] Spec accurately reflects the structlog + LangSmith observability approach from ADR-025 - [ ] A Git commit is created where the first line matches the Commit Message in Metadata exactly - [ ] The commit is pushed to the remote on the branch matching the Branch in Metadata exactly - [ ] The commit is submitted as a pull request to `master`, reviewed, and merged before this issue is marked done - All nox stages pass - Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 09:07:00 +00:00

#3374 Epic: E2E Workflow Specification Tests & Code Review Tool Examples

freemo referenced this issue

2026-04-06 09:18:32 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 09:33:49 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775