Skip to content

Commit d77ef3d

Browse files
committed
Update monitoring docs with realistic trace examples and schema details
- Change heading to 'OpenTelemetry traces topic' for clarity - Document auto-created Protobuf schema 'redpanda.otel_traces-value' - Update trace data structure example with realistic values (hex IDs, numeric enums) - Refine field descriptions and reference schema for details - Remove Custom dashboards and Best practices sections (too implementation-specific)
1 parent 2ac3688 commit d77ef3d

1 file changed

Lines changed: 32 additions & 18 deletions

File tree

modules/ai-agents/pages/mcp/remote/monitor-activity.adoc

Lines changed: 32 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ You must have an existing MCP server. If you do not have one, see xref:ai-agents
1111

1212
When you create an MCP server, Redpanda automatically creates the `redpanda.otel_traces` topic in your cluster. This topic stores OpenTelemetry span data in JSON format, following the https://opentelemetry.io/docs/specs/otel/protocol/[OpenTelemetry Protocol (OTLP)] specification.
1313

14+
A Protobuf schema named `redpanda.otel_traces-value` is also automatically registered with the topic, enabling clients to deserialize trace data correctly.
15+
1416
Each span represents a unit of work performed by your MCP server, such as:
1517

1618
* Tool invocation requests
@@ -61,31 +63,43 @@ Each trace message contains an OpenTelemetry span with the following structure:
6163
[,json]
6264
----
6365
{
64-
"traceId": "ustSLaZz5ZAIUDRlGUUp9g==",
65-
"spanId": "yrhA78Cfigg=",
66+
"traceId": "71cad555b35602fbb35f035d6114db54",
67+
"spanId": "43ad6bc31a826afd",
6668
"parentSpanId": "",
67-
"name": "tool_invocation",
68-
"kind": "SPAN_KIND_INTERNAL",
69-
"startTimeUnixNano": "1764946399331666916",
70-
"endTimeUnixNano": "1764946399431892103",
69+
"name": "http_processor",
70+
"kind": 1,
71+
"startTimeUnixNano": "1765198415253280028",
72+
"endTimeUnixNano": "1765198424660663434",
7173
"attributes": [
72-
{"key": "mcp.server.id", "value": {"stringValue": "d4pf2npsubec73f3fhbg"}},
73-
{"key": "mcp.tool.name", "value": {"stringValue": "echo_processor"}},
74-
{"key": "mcp.request.id", "value": {"stringValue": "req_123abc"}}
74+
{
75+
"key": "city_name",
76+
"value": {"stringValue": "london"}
77+
},
78+
{
79+
"key": "result_length",
80+
"value": {"intValue": "198"}
81+
}
7582
],
7683
"status": {
77-
"code": "STATUS_CODE_OK"
78-
}
84+
"code": 0,
85+
"message": ""
86+
},
87+
"instrumentationScope": {
88+
"name": "rpcn-mcp"
89+
},
90+
"flags": 1
7991
}
8092
----
8193

82-
* `traceId`: Unique identifier for the entire trace.
83-
* `spanId`: Unique identifier for this specific span.
84-
* `parentSpanId`: Links child spans to parent operations.
85-
* `name`: Descriptive name of the span.
86-
* `startTimeUnixNano` / `endTimeUnixNano`: Timing information in nanoseconds.
87-
* `attributes`: Key-value pairs with contextual information.
88-
* `status`: Success or error status.
94+
* `traceId`: Unique identifier for the entire trace (hex-encoded string).
95+
* `spanId`: Unique identifier for this specific span (hex-encoded string).
96+
* `parentSpanId`: Links child spans to parent operations (empty string if root span).
97+
* `name`: Descriptive name of the operation (typically the tool name in the case of MCP servers).
98+
* `kind`: Span kind as integer (see the `redpanda.otel_traces-value` schema for details).
99+
* `startTimeUnixNano` / `endTimeUnixNano`: Timing information in nanoseconds since Unix epoch.
100+
* `attributes`: Array of key-value pairs with contextual information about the operation.
101+
* `status`: Operation status with `code` (0 = OK, 2 = ERROR) and optional `message`.
102+
* `instrumentationScope`: Identifies the library or component that created the span.
89103

90104
=== Real trace examples
91105

0 commit comments

Comments
 (0)