Skip to content

Commit 4e46202

Browse files
authored
RFC 0058: propose gen_ai.conversation.id (#2696)
Proposal RFC to add gen_ai.conversation.id (keyword, extended, beta) to the existing gen_ai fieldset, matching the OpenTelemetry GenAI attribute of the same name.
1 parent 2179e78 commit 4e46202

2 files changed

Lines changed: 130 additions & 0 deletions

File tree

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
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)

‎rfcs/text/0058/gen_ai.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
# Additive field for schemas/gen_ai.yml (alphabetical after agent.* / before data_source.* if present).
3+
# Proposed for beta maturity; otel relation match to gen_ai.conversation.id.
4+
- name: conversation.id
5+
type: keyword
6+
description: >
7+
The unique identifier for a conversation (session, thread), used to store
8+
and correlate messages within this conversation.
9+
example: conv_5j66UpCpwteGg4YSxUnt7lPY
10+
level: extended
11+
beta: This field is beta and subject to change.
12+
otel:
13+
- relation: match

0 commit comments

Comments
 (0)