2026-02-01 23:38:43 -08:00
|
|
|
{
|
|
|
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
|
|
|
"definitions": {
|
|
|
|
|
"RequestId": {
|
|
|
|
|
"anyOf": [
|
|
|
|
|
{
|
|
|
|
|
"type": "string"
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"format": "int64",
|
|
|
|
|
"type": "integer"
|
|
|
|
|
}
|
|
|
|
|
]
|
feat(app-server): add tracing to all app-server APIs (#13285)
### Overview
This PR adds the first piece of tracing for app-server JSON-RPC
requests.
There are two main changes:
- JSON-RPC requests can now take an optional W3C trace context at the
top level via a `trace` field (`traceparent` / `tracestate`).
- app-server now creates a dedicated request span for every inbound
JSON-RPC request in `MessageProcessor`, and uses the request-level trace
context as the parent when present.
For compatibility with existing flows, app-server still falls back to
the TRACEPARENT env var when there is no request-level traceparent.
This PR is intentionally scoped to the app-server boundary. In a
followup, we'll actually propagate trace context through the async
handoff into core execution spans like run_turn, which will make
app-server traces much more useful.
### Spans
A few details on the app-server span shape:
- each inbound request gets its own server span
- span/resource names are based on the JSON-RPC method (`initialize`,
`thread/start`, `turn/start`, etc.)
- spans record transport (stdio vs websocket), request id, connection
id, and client name/version when available
- `initialize` stores client metadata in session state so later requests
on the same connection can reuse it
2026-03-02 16:01:41 -08:00
|
|
|
},
|
|
|
|
|
"W3cTraceContext": {
|
|
|
|
|
"properties": {
|
|
|
|
|
"traceparent": {
|
|
|
|
|
"type": [
|
|
|
|
|
"string",
|
|
|
|
|
"null"
|
|
|
|
|
]
|
|
|
|
|
},
|
|
|
|
|
"tracestate": {
|
|
|
|
|
"type": [
|
|
|
|
|
"string",
|
|
|
|
|
"null"
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"type": "object"
|
2026-02-01 23:38:43 -08:00
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"description": "A request that expects a response.",
|
|
|
|
|
"properties": {
|
|
|
|
|
"id": {
|
|
|
|
|
"$ref": "#/definitions/RequestId"
|
|
|
|
|
},
|
|
|
|
|
"method": {
|
|
|
|
|
"type": "string"
|
|
|
|
|
},
|
feat(app-server): add tracing to all app-server APIs (#13285)
### Overview
This PR adds the first piece of tracing for app-server JSON-RPC
requests.
There are two main changes:
- JSON-RPC requests can now take an optional W3C trace context at the
top level via a `trace` field (`traceparent` / `tracestate`).
- app-server now creates a dedicated request span for every inbound
JSON-RPC request in `MessageProcessor`, and uses the request-level trace
context as the parent when present.
For compatibility with existing flows, app-server still falls back to
the TRACEPARENT env var when there is no request-level traceparent.
This PR is intentionally scoped to the app-server boundary. In a
followup, we'll actually propagate trace context through the async
handoff into core execution spans like run_turn, which will make
app-server traces much more useful.
### Spans
A few details on the app-server span shape:
- each inbound request gets its own server span
- span/resource names are based on the JSON-RPC method (`initialize`,
`thread/start`, `turn/start`, etc.)
- spans record transport (stdio vs websocket), request id, connection
id, and client name/version when available
- `initialize` stores client metadata in session state so later requests
on the same connection can reuse it
2026-03-02 16:01:41 -08:00
|
|
|
"params": true,
|
|
|
|
|
"trace": {
|
|
|
|
|
"anyOf": [
|
|
|
|
|
{
|
|
|
|
|
"$ref": "#/definitions/W3cTraceContext"
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"type": "null"
|
|
|
|
|
}
|
|
|
|
|
],
|
|
|
|
|
"description": "Optional W3C Trace Context for distributed tracing."
|
|
|
|
|
}
|
2026-02-01 23:38:43 -08:00
|
|
|
},
|
|
|
|
|
"required": [
|
|
|
|
|
"id",
|
|
|
|
|
"method"
|
|
|
|
|
],
|
|
|
|
|
"title": "JSONRPCRequest",
|
|
|
|
|
"type": "object"
|
|
|
|
|
}
|