La risposta è giusta, il percorso no
Il caso più fastidioso dei sistemi con più agenti non è il crash: è la risposta corretta ottenuta in modo sbagliato. Un coordinatore passa il lavoro a un ricercatore, che interroga uno strumento; lo strumento va in timeout, il ricercatore riprova, il secondo tentativo riesce e il redattore consegna un testo ineccepibile. L'utente non vede niente. Tu scopri solo, a fine mese, che la latenza è raddoppiata o che i costi non tornano. Per questo l'osservabilità di un sistema agentico non serve ad analizzare gli errori finali: serve a leggere il percorso.
La risposta breve è questa: registra ogni invocazione di agente e ogni chiamata di strumento come uno span di una trace, con il rapporto padre-figlio, la durata e l'esito, e leggi l'albero. OpenTelemetry è il formato neutrale per farlo, e dispone di convenzioni dedicate agli agenti, con un'avvertenza che condiziona tutto il resto: sono in stato Development. Più sotto trovi un programma che produce davvero un albero di span e lo analizza; non chiama alcun modello.
Che cosa dicono le convenzioni per gli agenti
Le convenzioni semantiche per l'AI generativa descrivono nomi e attributi degli span che gli strumenti di analisi sanno interpretare. Un dettaglio utile: quel lavoro è stato spostato dal repository principale delle convenzioni a un repository dedicato, open-telemetry/semantic-conventions-genai, e la pagina sul sito ufficiale ora rinvia là. Il documento sugli span degli agenti dichiara in testa Status: Development, quindi nomi e attributi possono ancora cambiare. Nei documenti che ho letto il 13 novembre 2026 si legge quanto segue:
- l'invocazione di un agente o di un workflow nel tuo processo è uno span
INTERNALcongen_ai.operation.nameuguale ainvoke_agent(quando è un modello a guidare il flusso) o ainvoke_workflow(quando il flusso lo definisce l'applicazione), e nome{operazione} {gen_ai.agent.name}; - la chiamata di uno strumento è uno span
INTERNALcon operazioneexecute_tool, nomeexecute_tool {gen_ai.tool.name}e attributogen_ai.tool.nameobbligatorio; gen_ai.agent.namedeve avere bassa cardinalità: l'identificatore di un'istanza non va nel nome;- il contenuto dei messaggi e le istruzioni di sistema sono attributi Opt-In: non vanno registrati se non lo decidi tu.
Interpreta l'elenco come un contratto minimo. I primi due punti dicono come chiamare gli span, in modo che uno strumento li riconosca senza configurazione. Il terzo ti impedisce di far esplodere i costi di archiviazione: un nome di agente diverso per ogni utente produce milioni di serie. Il quarto è una scelta di privacy messa in chiaro: i prompt contengono dati personali e segreti. Il documento elenca tre modi d'uso: non registrare istruzioni, ingressi e uscite (è il predefinito), registrarli sugli span (adatto, dice il documento, ad ambienti di pre-produzione o dove la normativa non si applica), oppure conservarli altrove e registrare sullo span solo un riferimento, che è il modo raccomandato in produzione quando il volume è alto o i dati sono sensibili.
Un albero di span che puoi eseguire
Il programma simula la pipeline dell'esempio con tre agenti e uno strumento che fallisce una volta. Non usa modelli: i tempi li dichiaro io con un orologio finto, che avanza solo quando lo dico, e questo rende l'uscita identica a ogni esecuzione; in un sistema vero userai l'orologio vero e i tempi cambieranno. Il contesto traccia apre uno span con tempo di inizio esplicito, lo rende corrente per i figli con trace.use_span(..., end_on_exit=False), e in caso di eccezione registra l'eccezione, imposta lo stato su errore e aggiunge error.type, poi rilancia.
from collections import Counter, defaultdict
from contextlib import contextmanager
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
from opentelemetry.trace import SpanKind, Status, StatusCode
esportatore = InMemorySpanExporter()
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(esportatore))
tracer = provider.get_tracer("demo.agenti")
_t = {"ms": 0} # orologio finto: i tempi sono quelli che dichiariamo noi
def avanza(ms: int) -> None:
_t["ms"] += ms
def ora_ns() -> int:
return _t["ms"] * 1_000_000
@contextmanager
def traccia(nome, kind=SpanKind.INTERNAL, **attributi):
span = tracer.start_span(nome, kind=kind, attributes=attributi, start_time=ora_ns())
with trace.use_span(span, end_on_exit=False):
try:
yield span
except Exception as exc: # registra l'eccezione e marca lo span, poi rilancia
span.record_exception(exc)
span.set_status(Status(StatusCode.ERROR, str(exc)))
span.set_attribute("error.type", type(exc).__name__)
raise
finally:
span.end(end_time=ora_ns())
def esegui_tool(nome, durata_ms, fallisce=False):
with traccia(f"execute_tool {nome}", **{"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": nome, "gen_ai.tool.type": "function"}):
avanza(durata_ms)
if fallisce:
raise TimeoutError(f"{nome}: nessuna risposta dopo {durata_ms} ms")
def agente(nome, lavoro):
with traccia(f"invoke_agent {nome}", **{"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": nome}):
lavoro()
def ricercatore():
for tentativo in (1, 2):
try:
esegui_tool("cerca_db", 800 if tentativo == 1 else 120, fallisce=(tentativo == 1))
break
except TimeoutError:
avanza(50) # attesa prima del secondo tentativo
def redattore():
avanza(300)
def coordinatore():
agente("ricercatore", ricercatore)
agente("redattore", redattore)
with traccia("invoke_workflow pipeline-report", **{"gen_ai.operation.name": "invoke_workflow"}):
agente("coordinatore", coordinatore)
spans = esportatore.get_finished_spans()
per_id = {s.context.span_id: s for s in spans}
def profondita(s):
return 0 if s.parent is None else 1 + profondita(per_id[s.parent.span_id])
print(f"{len(spans)} span, un solo trace_id: {len({s.context.trace_id for s in spans}) == 1}")
for s in sorted(spans, key=lambda s: (s.start_time, profondita(s))):
ms = (s.end_time - s.start_time) // 1_000_000
print(f"{' ' * profondita(s) + s.name:<44}{ms:>5} ms {s.status.status_code.name}")
print("--- span in errore")
for s in spans:
if s.status.status_code is StatusCode.ERROR:
print(s.name, "|", s.attributes["error.type"], "|", s.status.description)
print("--- chiamate per strumento")
for nome, n in sorted(Counter(s.attributes["gen_ai.tool.name"] for s in spans
if s.attributes.get("gen_ai.operation.name") == "execute_tool").items()):
print(f"{nome}: {n}")
print("--- tempo del padre non coperto dai figli")
figli = defaultdict(list)
for s in spans:
if s.parent is not None:
figli[s.parent.span_id].append(s)
for s in sorted(spans, key=lambda s: (s.start_time, profondita(s))):
if s.context.span_id in figli:
durata = (s.end_time - s.start_time) // 1_000_000
coperto = sum((f.end_time - f.start_time) // 1_000_000 for f in figli[s.context.span_id])
if durata != coperto:
print(f"{s.name}: {durata - coperto} ms fuori da ogni span figlio")
# Output:
# 6 span, un solo trace_id: True
# invoke_workflow pipeline-report 1270 ms UNSET
# invoke_agent coordinatore 1270 ms UNSET
# invoke_agent ricercatore 970 ms UNSET
# execute_tool cerca_db 800 ms ERROR
# execute_tool cerca_db 120 ms UNSET
# invoke_agent redattore 300 ms UNSET
# --- span in errore
# execute_tool cerca_db | TimeoutError | cerca_db: nessuna risposta dopo 800 ms
# --- chiamate per strumento
# cerca_db: 2
# --- tempo del padre non coperto dai figli
# invoke_agent ricercatore: 50 ms fuori da ogni span figlio
Nell'albero si legge subito ciò che il risultato finale nascondeva. Lo strumento cerca_db compare due volte sotto il ricercatore: la prima durata 800 ms e finita in errore, la seconda durata 120 ms. Il ricercatore dura 970 ms, il coordinatore 1.270. Il conteggio per strumento dice che cerca_db è stato chiamato due volte per una sola richiesta, e l'errore ha il tipo e il messaggio già pronti. Un ritentativo riuscito non fa notizia se nessuno lo cerca: per questo l'uscita conta anche le chiamate per strumento.
L'ultima sezione dell'uscita è la più istruttiva. Il ricercatore dura 970 ms, ma i suoi due span figli ne coprono 920: i 50 ms mancanti sono l'attesa prima del secondo tentativo, che nessuno span ha misurato. Un buco fra padre e figli è tempo non osservato, e nei sistemi agentici è spesso lì che stanno code, attese di un limite di frequenza o riprove silenziose. La regola pratica: se la somma dei figli è molto inferiore al padre, manca uno span, e va aggiunto prima di cominciare a ottimizzare.
Mandare gli span a un collettore
InMemorySpanExporter serve ai test. In esercizio gli span vanno a un collettore con il protocollo OTLP. Il listato seguente costruisce il provider con un Resource che nomina il servizio, un esportatore OTLP su HTTP e un BatchSpanProcessor. L'ho eseguito fino alla costruzione, senza creare span: non invia nulla. Il collegamento a un collettore vero è uno schema da adattare, perché richiede un servizio in ascolto che qui non ho avviato.
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider(resource=Resource.create({"service.name": "pipeline-report"}))
esportatore = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
provider.add_span_processor(BatchSpanProcessor(esportatore))
trace.set_tracer_provider(provider)
print("endpoint:", esportatore._endpoint)
provider.shutdown() # nessuno span creato: non parte alcun invio
# Output:
# endpoint: http://localhost:4318/v1/traces
service.name è la proprietà che separa i tuoi servizi nell'interfaccia del collettore. L'endpoint, se non lo passi, viene dalla variabile OTEL_EXPORTER_OTLP_TRACES_ENDPOINT e in mancanza vale http://localhost:4318/v1/traces, che ho letto nel pacchetto installato. Il BatchSpanProcessor accumula gli span e li invia a gruppi: nella versione 1.45.2 attende fino a 5 secondi, esporta fino a 512 span per volta e tiene una coda di 2.048; se la coda si riempie, il processore scarta gli span e lo scrive nel log. Meglio saperlo prima di un incidente: una raffica di span può sparire proprio quando ti servirebbe.
Il collettore può essere Jaeger: il suo README indica che accetta tracce in OTLP su gRPC alla porta 4317 e su HTTP alla 4318. Se trovi un vecchio tutorial con opentelemetry.exporter.jaeger.thrift, sappi che il pacchetto opentelemetry-exporter-jaeger-thrift ha l'ultima versione, la 1.21.0, del 7 novembre 2023, mentre l'SDK è alla 1.45.2: è un esportatore fermo, e il percorso attuale è OTLP.
Che cosa offre il tuo framework
Non devi sempre scrivere gli span a mano. Ogni framework della serie ha una sua risposta, e le differenze contano:
- Mastra documenta il tracing come segnale integrato: span gerarchici per agenti, workflow, tool e chiamate al modello, con campi di esito (
success,error,suspend,limit,blockede altri) e una causa di arresto comemax_steps. - LangGraph indica nella documentazione il percorso LangSmith, che nella forma documentata richiede un account e una chiave: le tracce vanno a un servizio di LangChain (non ho verificato altre forme di installazione).
- CrewAI ha una propria telemetria anonima su un TracerProvider privato che non diventa mai quello globale: i suoi span non arrivano al tuo collettore, e i tuoi non arrivano a CrewAI. La tracciatura per il tuo backend passa da integrazioni esterne, che la documentazione cita (Langfuse, Braintrust, Phoenix).
Il criterio che emerge è dove finiscono gli span. Con Mastra vanno nello storage che configuri tu, e il collegamento a sistemi di terzi è una scelta tua; con LangSmith e con le integrazioni esterne di CrewAI vanno a un fornitore, e che cosa finisca nelle tracce, prompt e risposte compresi, dipende dalla configurazione: verificalo. Se i dati sono sensibili, la scelta dello strumento di tracing è una scelta sul trattamento dei dati, non solo sulla comodità: leggi le condizioni del fornitore prima di accendere l'esportazione.
Che cosa va storto
Ho incontrato un tranello mentre costruivo gli esempi di questa serie. La documentazione di CrewAI dice che la variabile OTEL_SDK_DISABLED=true disattiva anche la sua telemetria, e io l'avevo impostata per le prove di CrewAI. Rilanciando il programma di questo articolo con quella variabile ancora nell'ambiente, l'albero di span era vuoto: zero span, nessun errore. Un interruttore globale spegne l'SDK di tutto il processo. Quando le tracce spariscono, controlla l'ambiente prima del codice.
Altri guasti ricorrenti, che conviene mettere in una lista di controllo:
- Contesto perso: gli span figli si agganciano al padre solo se il contesto arriva fin lì; un thread non lo eredita da solo e va passato in modo esplicito.
- Troppi span: un ciclo senza tetto produce uno span per giro; con il limite predefinito di LangGraph, 10007 superpassi, è una trace enorme.
- Dati sensibili negli attributi: ciò che non è Opt-In per convenzione non va nei tuoi attributi per abitudine.
- Nomi ad alta cardinalità: identificatori di utente o di richiesta nel nome dell'agente fanno esplodere l'archivio.
Sono quattro errori diversi con lo stesso effetto: la telemetria diventa un costo senza dare risposte. Il rimedio è lo stesso in tutti i casi e si fa prima di accendere l'esportazione: decidi quali domande vuoi poter porre (quale strumento ha fallito, quante volte, dove è finito il tempo) e registra solo ciò che serve a rispondere. Per costruire il vocabolario degli span in un sistema reale, l'articolo sul design degli span va nel dettaglio.
Che cosa sai fare adesso
Sai leggere un albero di span di un sistema multi-agente, trovare un ritentativo nascosto e un buco di tempo non misurato, e sai scrivere gli span di agenti e strumenti con i nomi delle convenzioni, sapendo che sono ancora in stato Development. Sai dove mandare le tracce e che cosa implica la scelta, e hai una lista dei guasti che le svuotano. La serie si chiude qui: la scelta del framework e l'analisi dei costi hanno dato i criteri, la memoria dell'agente con Letta e il framework Mastra i mattoni; con le tracce puoi misurare se funzionano.
Domande frequenti
Perché OpenTelemetry e non uno strumento specifico per agenti?
OpenTelemetry è un formato neutrale: gli span che produci li può leggere qualunque collettore che parla OTLP, compreso Jaeger. Le convenzioni per gli agenti sono però in stato Development, quindi fissa le versioni e rileggi il documento quando aggiorni l'SDK o la libreria di strumentazione.
Come traccio un ritentativo o un fallimento che poi si risolve?
Dai a ogni tentativo il suo span e segna errore quello fallito con record_exception e error.type, come nel programma: poi conta gli span per nome di strumento in una trace. Due chiamate dello stesso strumento sotto lo stesso agente sono la firma di un ritentativo, e il tempo di attesa fra i due va coperto con uno span proprio.
Posso registrare i prompt negli span?
Le convenzioni li classificano come attributi Opt-In: il modo d'uso predefinito è non registrare né istruzioni né ingressi né uscite. Per la produzione raccomandano di conservare il contenuto altrove e di mettere sullo span solo un riferimento, così puoi controllare l'accesso al contenuto separatamente. Se li registri comunque, trattali come dati personali e verifica le condizioni del fornitore, se il collettore non è tuo.
Fonti
- OpenTelemetry GenAI semantic conventions: agent spans - stato Development; invoke_agent, invoke_workflow, nome dello span, bassa cardinalità di gen_ai.agent.name, consultata il 2026-11-13
- OpenTelemetry GenAI semantic conventions: execute tool - span execute_tool {gen_ai.tool.name} e attributi, consultata il 2026-11-13
- OpenTelemetry: pagina «Moved» delle convenzioni GenAI - lo spostamento nel repository semantic-conventions-genai, consultata il 2026-11-13
- Jaeger, README - OTLP su gRPC 4317 e HTTP 4318, consultata il 2026-11-13
- Mastra docs: Tracing - span per agenti, workflow, tool e modello; campi outcome e stopReason, consultata il 2026-11-13
- CrewAI docs: Telemetry - telemetria anonima, TracerProvider privato, variabili che la disattivano, consultata il 2026-11-13
- LangGraph docs: Observability - tracciatura documentata tramite LangSmith, con account e chiave, consultata il 2026-11-13
Versioni lette sui registri il 2026-11-13: opentelemetry-sdk 1.45.2, opentelemetry-exporter-otlp-proto-http 1.45.2, opentelemetry-exporter-jaeger-thrift 1.21.0 (ultimo rilascio 2023-11-07). I valori del BatchSpanProcessor (5000 ms, 512, 2048) e l'endpoint predefinito sono stati letti nei sorgenti installati. Il programma degli span è stato eseguito due volte con la stessa uscita; il listato OTLP è stato eseguito solo fino alla costruzione, senza creare span né aprire connessioni; nessun collettore è stato avviato.

Commenti
Caricamento commenti...
Accedi per commentare