Obserwowalność i śledzenie agentów (OpenTelemetry)

1. Przegląd koncepcji i problem systemowy

Autonomiczny agent działający w środowisku produkcyjnym to czarna skrzynka o wysokiej niepewności:

• Użytkownik skarży się: "Agent odpowiadał 45 sekund i zwrócił nonsens".
• Bez observability programista nie wie: czy model zawiesił się podczas rozumowania? Czy narzędzie wyszukiwania odpowiedziało z opóźnieniem 40 sekund? Czy agent wykonał 12 zbędnych ponownych zapytań przez halucynację?
• Na koniec miesiąca firma otrzymuje fakturę na $15 000 zamiast $1 500 z powodu niewidocznego, zapętlonego workera.

Agent Observability przekształca chaos niedeterministycznego wykonania w przejrzystą hierarchiczną strukturę zdarzeń i spanów (Spans & Traces).

2. Taksonomia architektoniczna i model mentalny

Trace ID: 7f8a91-bc42 (Total: 4.8s, Cost: $0.024)
┌─────────────────────────────────────────────────────────────┐
│ ROOT SPAN: User Task: "Analyze sales and generate summary"  │
│ ├── SPAN 1: LLM Reasoning (Claude 3.7) [1.2s, 1.4k tokens]  │
│ │   └── Output: Tool Call `query_database`                  │
│ ├── SPAN 2: Tool Execution: PostgreSQL [0.3s, 42 rows]     │
│ ├── SPAN 3: LLM Reasoning (Reflect on data) [0.9s]          │
│ │   └── Output: Tool Call `generate_chart`                  │
│ ├── SPAN 4: Tool Execution: Python Sandbox [1.8s]           │
│ └── SPAN 5: Final Response Synthesis [0.6s, 450 tokens]     │
└─────────────────────────────────────────────────────────────┘

Kluczowe filary observability:

1. Traces & Spans: Pełne drzewo wywołań: każde wywołanie modelu lub narzędzia posiada czas rozpoczęcia, czas trwania, argumenty wejściowe oraz wyniki wyjściowe.
2. Token & Cost Attribution: Precyzyjne rozliczanie zużycia tokenów (Input, Output, Cache Read, Cache Write) z podziałem na poszczególne funkcje produktu.
3. Session Replay: Możliwość krok po kroku odtworzenia stanu pamięci agenta w momencie dowolnej awarii.

3. Praktyczne scenariusze inżynierskie w produkcji

01. Wykrywanie anomalii wycieków tokenów

Alerting na Slacku aktywuje się, gdy jedna sesja agenta przekracza próg 100 000 tokenów lub trwa dłużej niż 3 minuty. Inżynier przegląda trace w Langfuse i widzi, że model utknął w pętli poprawiania tego samego konfliktu składniowego.

02. Monitoring cache’owania promptów (Prompt Caching Hit-Rate)

Dashboard śledzi procent zapytań trafiających do statycznego cache Anthropic/OpenAI. Jeśli wskaźnik trafień w cache spada poniżej 80%, sygnalizuje to, że ostatni commit naruszył strukturę prefiksu promptu.

4. Pułapki, typowe błędy i bezpieczeństwo

• Overhead przechowywania (Storage Bloat): Zapisywanie pełnych promptów każdego użytkownika przy obciążeniu 100 000 zapytań/dzień może generować gigabajty logów dziennie. Stosuj sampling (Sampling Rate = 10% dla udanych zapytań, 100% dla błędów) oraz szybkie magazyny analityczne (ClickHouse).
• Wyciek sekretów do trace’ów: Jeśli agent odczytuje plik .env, zawartość kluczy może trafić do interfejsu monitoringu. Włączaj regular expressions sanitizujące na poziomie klienta SDK.

5. Strategiczny wniosek dla inżyniera roku 2026

Observability jest warunkiem koniecznym wyprowadzenia agentów z laboratorium do realnego biznesu. Tego, czego nie można zmierzyć i prześledzić za pomocą spanów, nie da się bezpiecznie zoptymalizować ani skalować na setki tysięcy użytkowników.