Salta al contenuto principale

06 - Debug multi-agente con OpenTelemetry: span e ritentativi

Come leggere il percorso di un sistema multi-agente con OpenTelemetry: span di agenti e strumenti, ritentativi nascosti, tempo non misurato.

Cosa ne pensi di questo articolo?

06 - Debug multi-agente con OpenTelemetry: span e ritentativi
Agentic PlatformsFoto:Pavel DanilyukPexels

In Breve

Come leggere il percorso di un sistema multi-agente con OpenTelemetry: span di agenti e strumenti, ritentativi nascosti, tempo non misurato.

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 INTERNAL con gen_ai.operation.name uguale a invoke_agent (quando è un modello a guidare il flusso) o a invoke_workflow (quando il flusso lo definisce l'applicazione), e nome {operazione} {gen_ai.agent.name};
  • la chiamata di uno strumento è uno span INTERNAL con operazione execute_tool, nome execute_tool {gen_ai.tool.name} e attributo gen_ai.tool.name obbligatorio;
  • gen_ai.agent.name deve 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.

Span di agenti e strumenti con OpenTelemetry SDK 1.45.2 (eseguito, orologio finto)
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.

Provider con esportatore OTLP (costruito ed eseguito senza inviare span)
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, blocked e altri) e una causa di arresto come max_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

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.

Prova Questi Strumenti

Strumenti gratuiti correlati a questo argomento.

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti