0xPlaygrounds / 0xPlaygrounds/rig

telemetry: investigate legacy chat_streaming operation naming

Aperta
#2,117 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Rust
Stelle
8.6k
Fork
959
Merge medio
4h 32m
PR unite (30g)
117

Descrizione

## Summary

Investigate whether Rig should continue treating streaming chat as a distinct GenAI operation (`chat_streaming`) or migrate to the standard `chat` operation with streaming represented separately.

This surfaced while reviewing #2115. `CompletionOperation` currently couples the span name and `gen_ai.operation.name`:

- `Chat` -> span `chat`, operation `chat`
- `ChatStreaming` -> span `chat_streaming`, operation `chat_streaming`

Provider behavior is not uniform: OpenAI-compatible Chat Completions streaming deliberately uses `Chat` to preserve its existing telemetry contract, while most other streaming providers use `ChatStreaming`. The agent streaming path already separates these concepts: its span is named `chat_streaming`, but its initial operation is `chat`.

## Why investigate

OpenTelemetry's GenAI semantic conventions define `chat` as the well-known operation. Streaming is transport/request behavior and can be represented by `gen_ai.request.stream`; `chat_streaming` does not appear to be a standard operation value.

References:

- https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
- https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-metrics.md
- https://github.com/open-telemetry/semantic-conventions-genai

Changing existing span names or operation values may break dashboards, filters, sampling rules, or stored-query assumptions, so this should not be changed incidentally in #2115.

## Questions to answer

1. Is `chat_streaming` intentionally part of Rig's public telemetry compatibility contract?
2. Do any supported observability integrations depend on the span name, operation value, or both?
3. Should operation and delivery mode be modeled separately, for example:

```rust
CompletionSpanBuilder::new(provider, model, CompletionOperation::Chat)
.streaming(true)
```

4. If span-name compatibility matters, can Rig retain `chat_streaming` as the span name while emitting:

```text
gen_ai.operation.name = "chat"
gen_ai.request.stream = true
```

5. Does migration require a deprecation window, compatibility option, or release note?

## Acceptance criteria

- Document the intended semantic and compatibility contract for streaming completion spans.
- Audit provider and agent call sites for current span names and operation values.
- Compare the chosen representation against current OpenTelemetry GenAI conventions.
- If migration is appropriate, make operation values consistent across providers and agent/direct surfaces.
- Add coverage for span name, `gen_ai.operation.name`, and streaming indication.
- Document any compatibility impact and migration guidance.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Start by reading the OpenTelemetry GenAI semantic conventions linked in the issue. Then audit the codebase for `CompletionOperation`, `Chat`, and `ChatStreaming` usage, particularly in provider implementations and the agent streaming path. The goal is to document the current telemetry contract and propose a migration plan that aligns with standards, considering compatibility impacts.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
rust
Ambito
ai-infra-agents, observability
Tipo di issue
Refactoring
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Tranquilla
Chiarezza
Specificata chiaramente
Idoneità per principianti
45/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.