cloudwego / cloudwego/eino-ext
feat(callbacks/tls): add opt-in TLS observability callback
- Dominant language
- Go
- Stars
- 811
- Forks
- 368
- Avg merge
- 16h 22m
- Merged PRs (30d)
- 13
Description
## Problem
Eino currently offers generic callback integrations, but applications that use Volcengine TLS need an opt-in, first-class path to export Eino callback spans to TLS while preserving the existing callback and OpenTelemetry integrations.
## Proposed design
Add a standalone `callbacks/tls` Go module that:
- builds Eino callback events into OpenTelemetry spans and maps them to TLS trace logs;
- keeps TLS export disabled by default, so existing users are unaffected;
- accepts credentials and endpoint configuration only through `TLSConfig` or environment variables, never hard-coded values;
- exposes an explicit exporter lifecycle (flush/shutdown) and leaves the generic OTLP exporter unchanged;
- models `agent.turn`, `llm.request`, and `tool.call` spans so traces remain queryable across text, multimodal, streaming, and tool-call flows.
Streaming output is coalesced before it is recorded, rather than persisting every chunk as a separate payload. Token usage, model/provider identity, tool arguments/results, errors, and duration are attached when available.
## Scope
This proposal also adds TLS connection options to `libs/acl/opentelemetry` and enriches the Ark model adapter with callback usage metadata. The implementation is intentionally additive and does not change Eino public behavior when TLS exporting is not configured.
## Validation
- unit tests for callback/span mapping, exporter configuration, streaming aggregation, tool calls, and error paths;
- integration coverage guarded by `TLS_EXPORTER_E2E=1`, so ordinary upstream CI does not require a TLS account;
- race-enabled tests for the affected `callbacks/tls`, `libs/acl/opentelemetry`, and Ark model modules.
## Alternatives
Users can assemble a custom callback handler or export generic OTLP spans. A dedicated module provides stable TLS resource/schema conventions and reduces repeated application-side integration work.
Contributor guide
Research direction
Start by reading the existing callback integrations and libs/acl/opentelemetry, then inspect the Ark model adapter and the new callbacks/tls module boundary. Run the affected unit and race-enabled tests; done means TLS export remains opt-in, mapping and streaming/tool/error coverage passes, and TLS_EXPORTER_E2E=1 integration coverage is available without changing generic OTLP behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100