Convert opencode transcripts to otel (or agent) traces
Use meaningful node identifiers in mermaid diagrams
+117
+117
doc/PLAN-nested.md
+117
doc/PLAN-nested.md
···
11
11
3. **Misaligned with OpenTelemetry**: OpenTelemetry tracing relies on span hierarchies to show execution flow
12
12
4. **Ambiguous ownership**: Multiple spans can exist for the same timestamp without clear relationships
13
13
14
+
### Current Flat Span Structure
15
+
16
+
```mermaid
17
+
graph LR
18
+
subgraph Flat Vector
19
+
USER_CHAT[User Chat Span]
20
+
ASSISTANT_THINKING[Assistant Thinking Span]
21
+
TOOL_CALL_1[Tool Call 1]
22
+
TOOL_CALL_2[Tool Call 2]
23
+
COMPLETION_CHAT[Completion Chat Span]
24
+
end
25
+
26
+
style USER_CHAT fill:#ffcccc
27
+
style ASSISTANT_THINKING fill:#ccffcc
28
+
style TOOL_CALL_1 fill:#ccccff
29
+
style TOOL_CALL_2 fill:#ccccff
30
+
style COMPLETION_CHAT fill:#ffcccc
31
+
```
32
+
33
+
All spans exist in a flat vector with no relationships between them.
34
+
14
35
### Current Span Structure (FLAT)
15
36
16
37
```
···
68
89
└─ Completion content stored in parent Chat span
69
90
```
70
91
92
+
### Desired Nested Span Hierarchy
93
+
94
+
```mermaid
95
+
graph TD
96
+
subgraph Conversation Turn
97
+
CHAT_SPAN[Chat Span<br/>gen_ai.input<br/>gen_ai.completion]
98
+
99
+
CHAT_SPAN --> THINKING_SPAN[Thinking Span<br/>opencode.assistant.thinking]
100
+
CHAT_SPAN --> TOOL_CALL_READ[Tool Call: read<br/>gen_ai.tool.call.arguments<br/>gen_ai.tool.call.result]
101
+
CHAT_SPAN --> TOOL_CALL_WRITE[Tool Call: write<br/>gen_ai.tool.call.arguments<br/>gen_ai.tool.call.result]
102
+
end
103
+
104
+
style CHAT_SPAN fill:#ffcc99,stroke:#333,stroke-width:2px
105
+
style THINKING_SPAN fill:#99ccff
106
+
style TOOL_CALL_READ fill:#99ffcc
107
+
style TOOL_CALL_WRITE fill:#99ffcc
108
+
109
+
CHAT_SPAN -.->|parent_span_id| THINKING_SPAN
110
+
CHAT_SPAN -.->|parent_span_id| TOOL_CALL_READ
111
+
CHAT_SPAN -.->|parent_span_id| TOOL_CALL_WRITE
112
+
```
113
+
114
+
Parent Chat span contains the conversation context (user input and final completion). Child spans (thinking, tools) represent the internal processing steps.
115
+
71
116
### Key Design Decisions
72
117
73
118
1. **User messages are context, not spans**: User messages don't create independent spans. Instead, they're stored as `gen_ai.input` attribute in the Chat span for that conversation turn.
···
93
138
pub parent_span_id: Option<String>, // NEW: Link to parent span
94
139
}
95
140
```
141
+
142
+
### Concrete Example: Single Conversation Turn
143
+
144
+
Given this conversation:
145
+
146
+
```
147
+
## User
148
+
Help me read a file
149
+
150
+
## Assistant (opencode · claude-3-5-sonnet)
151
+
_Thinking:_
152
+
I'll read the file first to understand its contents.
153
+
154
+
Done!
155
+
156
+
Tool: read
157
+
{"path": "README.md"}
158
+
159
+
Tool: read
160
+
Output: File contents here...
161
+
162
+
Here's what's in the file: [summary]
163
+
```
164
+
165
+
The resulting span hierarchy would be:
166
+
167
+
```mermaid
168
+
graph TD
169
+
subgraph Spans Created
170
+
CHAT_SPAN[Chat Span ID: session-0-1234567890<br/>span_type: Chat<br/>parent_span_id: null]
171
+
172
+
THINKING_SPAN[Thinking Span ID: session-1-1234567891<br/>span_type: Thinking<br/>parent_span_id: session-0-1234567890]
173
+
174
+
TOOL_CALL_READ_SPAN[Tool Call Span ID: session-2-1234567892<br/>span_type: ToolCall<br/>parent_span_id: session-0-1234567890]
175
+
end
176
+
177
+
CHAT_SPAN --> THINKING_SPAN
178
+
CHAT_SPAN --> TOOL_CALL_READ_SPAN
179
+
180
+
CHAT_SPAN -.gen_ai.input.->|Help me read a file| CHAT_SPAN
181
+
CHAT_SPAN -.gen_ai.completion.->|Here's what's in the file: [summary]| CHAT_SPAN
182
+
THINKING_SPAN -.opencode.assistant.thinking.->|I'll read the file first...| THINKING_SPAN
183
+
TOOL_CALL_READ_SPAN -.gen_ai.tool.name.->|read| TOOL_CALL_READ_SPAN
184
+
TOOL_CALL_READ_SPAN -.gen_ai.tool.call.arguments.->|{path: README.md}| TOOL_CALL_READ_SPAN
185
+
TOOL_CALL_READ_SPAN -.gen_ai.tool.call.result.->|File contents here...| TOOL_CALL_READ_SPAN
186
+
```
187
+
188
+
**Chat Span (PARENT):**
189
+
- `span_type`: Chat
190
+
- `span_id`: session-0-1234567890
191
+
- `parent_span_id`: null
192
+
- `attributes`:
193
+
- `gen_ai.input`: "Help me read a file"
194
+
- `gen_ai.completion`: "Here's what's in the file: [summary]"
195
+
- `gen_ai.model.name`: "claude-3-5-sonnet"
196
+
- `opencode.agent`: "opencode"
197
+
198
+
**Thinking Span (CHILD):**
199
+
- `span_type`: Thinking
200
+
- `span_id`: session-1-1234567891
201
+
- `parent_span_id`: session-0-1234567890
202
+
- `attributes`:
203
+
- `opencode.assistant.thinking`: "I'll read the file first to understand its contents."
204
+
205
+
**Tool Call Span (CHILD):**
206
+
- `span_type`: ToolCall
207
+
- `span_id`: session-2-1234567892
208
+
- `parent_span_id`: session-0-1234567890
209
+
- `attributes`:
210
+
- `gen_ai.tool.name`: "read"
211
+
- `gen_ai.tool.call.arguments`: `{"path": "README.md"}`
212
+
- `gen_ai.tool.call.result`: "File contents here..."
96
213
97
214
### Revised Parsing Algorithm
98
215