Distributed Tracing

Распределённая трассировка MCP вызовов через correlation_id, OpenTelemetry и W3C Trace Context

Обзор

FlowLink реализует full-stack распределённую трассировку для каждого MCP запроса. Каждый вызов получает уникальный correlation_id, который автоматически распространяется через все слои архитектуры: Agent → Relay → Shield → Policy → Execute → Audit. Это позволяет восстанавливать полную цепочку вызовов для debugging, compliance и incident response. Поддерживается экспорт в OpenTelemetry, интеграция с Jaeger/Zipkin и SIEM системами.

correlation_id

Автоматическая трассировка через все слои

Все тарифы

OpenTelemetry

Экспорт spans в OTLP

Team+

W3C Trace Context

Стандарт propagation заголовков

Все тарифы

SIEM экспорт

CEF/LEEF события с trace ID

Team+

Архитектура трассировки

Трассировка в FlowLink построена на двух уровнях: встроенный correlation_id (всегда активен) и OpenTelemetry spans (опционально). correlation_id привязан к запросу и логируется на каждом этапе обработки. OpenTelemetry добавляет детальные spans с таймингами для каждого внутреннего вызова.

# 7-шаговый pipeline трассировки

1. Agent → MCP Request

correlation_id assigned, W3C traceparent header set

2. Relay → receives & forwards

logs received, propagates trace context to Shield

3. Shield → L1-L4 scan

correlation_id in scan context, separate span per layer

4. Policy → rule evaluation

correlation_id in policy decision, rules matched logged

5. Execute → command execution

correlation_id in result, stdout/stderr captured

6. Audit → log all events

correlation_id in every audit event

7. Response → return to Agent

full timing breakdown included

Формат correlation_id

correlation_id генерируется при получении MCP запроса и имеет формат с timestamp и random hex суффиксом для уникальности.

json

1{
2  "format": "mcp:{timestamp_ms}:{random_hex}",
3  "example": "mcp:1705332000123:a1b2c3d4",
4  "length": "36 characters",
5  "unique_per": "request",
6  "propagated_to": [
7    "shield_scan",
8    "policy_check",
9    "command_execution",
10    "audit_log",
11    "siem_events",
12    "otel_spans"
13  ]
14}

W3C Trace Context

FlowLink поддерживает стандарт W3C Trace Context для совместимости с внешними системами трассировки. Заголовок `traceparent` распространяется через все HTTP вызовы между сервисами. Входящие `traceparent` заголовки от агентов используются для создания child spans.

bash

1# Заголовки W3C Trace Context
2traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
3tracestate: fl=1,otel=1
4
5# Части traceparent
6# 00             - version
7# 4bf92f...4736  - trace-id (32 hex)
8# 00f067...2b7   - parent-id (16 hex)
9# 01             - sampled flag

json

1{
2  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
3  "span_id": "00f067aa0ba902b7",
4  "correlation_id": "mcp:1705332000123:a1b2c3d4",
5  "flags": {
6    "sampled": true,
7    "recorded": true
8  }
9}

OpenTelemetry

FlowLink нативно экспортирует telemetry данные в формате OTLP (OpenTelemetry Protocol). Поддерживаются gRPC и HTTP экспортеры. Каждый MCP запрос создаёт trace с несколькими spans, соответствующими этапам обработки.

Конфигурация

yaml

1# OpenTelemetry конфигурация
2otel:
3  enabled: true
4  exporter: "otlp"              # otlp | jaeger | zipkin | none
5  protocol: "grpc"               # grpc | http
6  endpoint: "http://jaeger:4317"
7  
8  # Sampling конфигурация
9  sampling:
10    type: "parent_based_trace_id_ratio"  # always | never | parent_based_trace_id_ratio
11    rate: 0.1                            # 10% выборка (применяется при ratio)
12
13  # Resource attributes
14  resource:
15    service.name: "flowlink-relay"
16    deployment.environment: "production"
17
18  # Инструментация
19  instrumentation:
20    http: true
21    grpc: true
22    db: true

Span структура

json

1{
2  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
3  "spans": [
4    {
5      "span_id": "00f067aa0ba902b7",
6      "name": "mcp.request",
7      "parent_span_id": null,
8      "kind": "SERVER",
9      "attributes": {
10        "mcp.tool": "flowlink_exec",
11        "mcp.agent_id": "claude-code-prod",
12        "mcp.correlation_id": "mcp:1705332000123:a1b2c3d4"
13      },
14      "events": [],
15      "status": { "code": "OK" },
16      "start_time": "2026-01-15T14:00:00.000Z",
17      "end_time": "2026-01-15T14:00:00.030Z"
18    },
19    {
20      "span_id": "a1b2c3d4e5f6a7b8",
21      "name": "shield.scan",
22      "parent_span_id": "00f067aa0ba902b7",
23      "kind": "INTERNAL",
24      "attributes": {
25        "shield.layers": "L1,L2,L3,L4",
26        "shield.risk_score": 8
27      },
28      "status": { "code": "OK" },
29      "start_time": "2026-01-15T14:00:00.002Z",
30      "end_time": "2026-01-15T14:00:00.014Z"
31    },
32    {
33      "span_id": "b2c3d4e5f6a7b8c9",
34      "name": "policy.evaluate",
35      "parent_span_id": "00f067aa0ba902b7",
36      "kind": "INTERNAL",
37      "attributes": {
38        "policy.id": "pol_default",
39        "policy.action": "allow"
40      },
41      "status": { "code": "OK" },
42      "start_time": "2026-01-15T14:00:00.014Z",
43      "end_time": "2026-01-15T14:00:00.016Z"
44    }
45  ]
46}

Sampling стратегия

Для высоконагруженных deployments рекомендуется использовать sampling для уменьшения объёма telemetry данных. FlowLink поддерживает несколько стратегий.

Стратегия	Описание	Рекомендация
always	Все запросы трассируются	< 100 req/s
never	Трассировка отключена	Disabled
parent_based_trace_id_ratio	Выборка по ratio (0.0-1.0)	> 100 req/s
adaptive	Автоматическая коррекция rate	> 1000 req/s

Trace API

Получить трассировку по correlation_id

bash

1curl -s "https://api.flowlink.io/v1/traces/mcp:1705332000123:a1b2c3d4" \
2  -H "Authorization: Bearer $TOKEN" | jq

json

1{
2  "correlation_id": "mcp:1705332000123:a1b2c3d4",
3  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
4  "agent_id": "claude-code-prod",
5  "tool_name": "flowlink_exec",
6  "tool_params": { "command": "ls -la /tmp" },
7  "steps": [
8    { "step": "relay_received", "timestamp": "2026-01-15T14:00:00.000Z", "duration_ms": 0 },
9    { "step": "shield_scan", "timestamp": "2026-01-15T14:00:00.002Z", "duration_ms": 12, "result": { "passed": true, "risk_score": 8, "threats": [] } },
10    { "step": "policy_check", "timestamp": "2026-01-15T14:00:00.014Z", "duration_ms": 2, "result": { "action": "allow", "policy_id": "pol_default" } },
11    { "step": "command_execution", "timestamp": "2026-01-15T14:00:00.016Z", "duration_ms": 15, "result": { "exit_code": 0, "stdout": "total 32
12drwxr-xr-x  4 root root 4096 Jan 15 14:00 ." } },
13    { "step": "audit_logged", "timestamp": "2026-01-15T14:00:00.031Z", "duration_ms": 1 }
14  ],
15  "total_duration_ms": 31,
16  "status": "completed"
17}

Поиск трассировок

bash

1# Поиск по агенту и времени
2curl -s "https://api.flowlink.io/v1/traces?agent_id=claude-code-prod&from=2026-01-15T00:00:00Z&to=2026-01-15T23:59:59Z&limit=50" \
3  -H "Authorization: Bearer $TOKEN" | jq
4
5# Поиск по результату Shield
6curl -s "https://api.flowlink.io/v1/traces?shield_result=blocked&limit=20" \
7  -H "Authorization: Bearer $TOKEN" | jq

json

1{
2  "traces": [
3    {
4      "correlation_id": "mcp:1705332000123:a1b2c3d4",
5      "agent_id": "claude-code-prod",
6      "tool_name": "flowlink_exec",
7      "status": "completed",
8      "total_duration_ms": 31,
9      "created_at": "2026-01-15T14:00:00Z"
10    }
11  ],
12  "total": 1,
13  "limit": 50
14}

Propagation контекста

В multi-agent workflow correlation_id распространяется через все слои, создавая единый trace. Каждый downstream вызов получает тот же trace_id и новый parent_span_id.

# Multi-agent trace propagation

Claude Code

└── trace_id: 4bf92f3577b...

├── span: flowlink_exec (agent-prod-01)

│ ├── span: shield.scan

│ ├── span: policy.evaluate

│ └── span: command.execute

└── span: flowlink_exec (agent-prod-02)

├── span: shield.scan

└── span: command.execute

Интеграция с SIEM

correlation_id включается в каждый SIEM event (CEF/LEEF). Это позволяет строить transaction traces в SIEM и находить все события, связанные с одним MCP вызовом.

bash

1# Splunk — поиск по correlation_id
2index=flowlink correlation_id="mcp:1705332000123:a1b2c3d4" | transaction correlation_id
3
4# Elasticsearch — aggregation trace timeline
5{
6  "query": {
7    "term": { "correlation_id": "mcp:1705332000123:a1b2c3d4" }
8  },
9  "sort": [{ "@timestamp": "asc" }],
10  "size": 100
11}

Производительность

Метрика	Значение	Примечание
Overhead correlation_id	< 0.1ms	При каждом запросе
Overhead OpenTelemetry	< 1ms	При включённом экспорте
Trace storage	7 дней (rotating)	Настроивается
Поиск трейса	< 10ms	Indexed lookup
OTLP batch export	каждые 5 секунд	Настраиваемый интервал

Устранение неполадок

Traces не отображаются в Jaeger

Проверьте otel.enabled: true и корректный endpoint. Убедитесь что sampling rate не 0. Проверьте подключение: curl -v http://jaeger:4317. Проверьте логи FlowLink на ошибки OTLP exporter.

correlation_id отсутствует в логах

Убедитесь что запрос проходит через Relay (не прямой вызов агента). correlation_id назначается только на уровне Relay. Проверьте формат заголовка traceparent.

Лучшие практики

Настройте sampling для production

Начните с 10% sampling и увеличьте при необходимости. Для debugging конкретных проблем — переключите на always.

Используйте W3C Trace Context

Если ваши агенты уже отправляют traceparent, FlowLink автоматически присоединится к существующему trace.

Мониторьте overhead

Следите за временем трассировки в /metrics. Если overhead > 5ms, уменьшите sampling rate или отключите некоторые instrumentation.

Интегрируйте с SIEM

Свяжите correlation_id с SIEM для end-to-end visibility. Это особенно полезно для compliance и incident response.

← Compliance Change Management →

Форензика

Карта инфраструктуры

Edit this page