cloudwego / cloudwego/eino-ext

feat(callbacks/tls): add opt-in TLS observability callback

Closed
#935 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.