|
| 1 | +# 0058: Add gen_ai.conversation.id |
| 2 | + |
| 3 | +- Stage: **Proposal** |
| 4 | +- Date: **TBD** |
| 5 | +- Target maturity: **beta** |
| 6 | + |
| 7 | +## Summary |
| 8 | + |
| 9 | +Add `gen_ai.conversation.id` to the existing `gen_ai` fieldset so GenAI telemetry can correlate turns, tool calls, and detections that belong to the same conversation (session/thread). The field already exists in the OpenTelemetry GenAI semantic conventions as a string attribute; ECS already mirrors adjacent identifiers such as `gen_ai.agent.id` and `gen_ai.response.id` but does not yet define this conversation-level key. |
| 10 | + |
| 11 | +## Usage |
| 12 | + |
| 13 | +Security and observability pipelines emit one or more events per model turn. Without a stable conversation key, analysts must reconstruct multi-turn attacks (prompt injection across turns, tool misuse spanning a session, policy violations in Agent Builder / assistant chats) by guesswork or vendor-specific headers. |
| 14 | + |
| 15 | +With `gen_ai.conversation.id`: |
| 16 | + |
| 17 | +- Detection rules and hunts can group alerts and traces for a single chat session. |
| 18 | +- Kibana Agent Builder and related eval/trace tooling can join workflow step `conversation_id` values to OTel/ECS attributes already named `gen_ai.conversation.id`. |
| 19 | +- OTel-instrumented GenAI apps map the attribute 1:1 into ECS without inventing a custom field. |
| 20 | + |
| 21 | +## Fields |
| 22 | + |
| 23 | +Proposed definition (also in [`rfcs/text/0058/gen_ai.yaml`](./0058/gen_ai.yaml)): |
| 24 | + |
| 25 | +```yaml |
| 26 | +- name: conversation.id |
| 27 | + type: keyword |
| 28 | + description: > |
| 29 | + The unique identifier for a conversation (session, thread), used to store |
| 30 | + and correlate messages within this conversation. |
| 31 | + example: conv_5j66UpCpwteGg4YSxUnt7lPY |
| 32 | + level: extended |
| 33 | + beta: This field is beta and subject to change. |
| 34 | + otel: |
| 35 | + - relation: match |
| 36 | +``` |
| 37 | +
|
| 38 | +This is a single additive keyword under the existing `gen_ai` group. No child objects or `flattened` fields are required. |
| 39 | + |
| 40 | +## Source data |
| 41 | + |
| 42 | +### OTel GenAI attribute |
| 43 | + |
| 44 | +OTel documents `gen_ai.conversation.id` as the unique identifier for a conversation (session, thread), example `conv_5j66UpCpwteGg4YSxUnt7lPY` ([GenAI attributes registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/)). |
| 45 | + |
| 46 | +```json |
| 47 | +{ |
| 48 | + "attributes": { |
| 49 | + "gen_ai.conversation.id": "conv_5j66UpCpwteGg4YSxUnt7lPY", |
| 50 | + "gen_ai.operation.name": "chat", |
| 51 | + "gen_ai.request.model": "gpt-4o", |
| 52 | + "gen_ai.response.id": "chatcmpl-123" |
| 53 | + } |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +### Kibana Agent Builder / assistant converse API |
| 58 | + |
| 59 | +Agent Builder converse responses expose a `conversation_id` that is already correlated in Security evals to `attributes.gen_ai.conversation.id`. |
| 60 | + |
| 61 | +```json |
| 62 | +{ |
| 63 | + "conversation_id": "conv_5j66UpCpwteGg4YSxUnt7lPY", |
| 64 | + "response": { |
| 65 | + "message": "Here is a summary of the alert triage steps." |
| 66 | + } |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +### Security detection / trace join (illustrative ECS event) |
| 71 | + |
| 72 | +```json |
| 73 | +{ |
| 74 | + "@timestamp": "2026-09-21T12:00:00.000Z", |
| 75 | + "event": { |
| 76 | + "kind": "event", |
| 77 | + "category": ["api"], |
| 78 | + "type": ["info"] |
| 79 | + }, |
| 80 | + "gen_ai": { |
| 81 | + "conversation.id": "conv_5j66UpCpwteGg4YSxUnt7lPY", |
| 82 | + "operation.name": "chat", |
| 83 | + "provider.name": "openai", |
| 84 | + "request.model": "gpt-4o", |
| 85 | + "response.id": "chatcmpl-123" |
| 86 | + }, |
| 87 | + "user": { |
| 88 | + "name": "analyst" |
| 89 | + } |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +## Scope of impact |
| 94 | + |
| 95 | +* **Ingestion:** Additive only. OTel Collector / EDOT paths that already export `gen_ai.conversation.id` can land the field without remapping. Custom integrations may add a one-line copy from vendor session/thread ids. |
| 96 | +* **Usage:** Enables session-scoped detections, dashboards, and alert correlation. No breaking change to existing `gen_ai.*` consumers. |
| 97 | +* **ECS project:** One new field in `schemas/gen_ai.yml` after Proposal acceptance; docs/generated artifacts updated in the follow-on schema PR (or automation on merge). |
| 98 | + |
| 99 | +## Concerns |
| 100 | + |
| 101 | +* **Overlap with `gen_ai.response.id`:** Response id identifies a single completion; conversation id spans many turns. Resolution: keep both; document conversation as session/thread scope. |
| 102 | +* **Overlap with tracing `trace.id`:** A conversation may span multiple traces. Resolution: conversation id is application-level session identity, not a substitute for W3C trace context. |
| 103 | +* **Cardinality:** Keyword session ids are high-cardinality by design (same class as `gen_ai.agent.id` / `gen_ai.response.id`). Resolution: `level: extended`; producers SHOULD use stable opaque ids, not free-text titles. |
| 104 | + |
| 105 | +## People |
| 106 | + |
| 107 | +* @Mikaayenson | author |
| 108 | + |
| 109 | +## References |
| 110 | + |
| 111 | +* [ECS RFC process](https://github.com/elastic/ecs/blob/main/rfcs/PROCESS.md) |
| 112 | +* [OTel GenAI attributes — `gen_ai.conversation.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/) |
| 113 | +* Related RFCs: [0050](./0050-gen_ai-security-fields.md), [0052](./0052-gen_ai-additional-fields.md) |
| 114 | + |
| 115 | +### RFC Pull Requests |
| 116 | + |
| 117 | +* Proposal: (this PR) |
0 commit comments