Passa al contenuto principale

Tracciamento

Obiettivo: riportare ogni ticket a Langfuse o a un collector OpenTelemetry.

Prerequisiti​

  • Un'istanza Langfuse 4 raggiungibile, oppure un collector OpenTelemetry che accetta OTLP/HTTP JSON.
  • L'host e le chiavi che servono al tracer, in variabili d'ambiente.

Passi​

  1. Nomina un tracer nel manifest Runtime, così ogni ticket viene riportato a un backend di osservabilità. type nomina la porta tracers di un plugin.

  2. Per mandare OTLP/HTTP a un'istanza Langfuse 4, usa il plugin afe-langfuse. Le tre variabili nominano l'host e le chiavi del progetto, mai i loro valori:

    spec:
      tracer:
        type: langfuse
        hostEnv: LANGFUSE_HOST
        publicKeyEnv: LANGFUSE_PUBLIC_KEY
        secretKeyEnv: LANGFUSE_SECRET_KEY

  3. Per mandare gli stessi span a un qualsiasi collector OpenTelemetry via OTLP/HTTP JSON, su <endpoint>/v1/traces, usa il plugin afe-otlp. Tempo, Jaeger e la maggior parte degli agenti dei fornitori lo accettano.

    spec:
      tracer:
        type: otlp                                  # legge le variabili standard degli exporter
        endpointEnv: OTEL_EXPORTER_OTLP_ENDPOINT    # il default, es. http://otel-collector:4318
        headersEnv: OTEL_EXPORTER_OTLP_HEADERS      # il default, facoltativo: chiave=valore,…

Una variabile mancante o un host irraggiungibile fermano il processo prima che parta qualunque run. Le chiavi non compaiono mai in un errore o in un log.

Note​

  • Un tracer accetta solo i campi del suo tipo. I valori degli header vanno solo nella richiesta, mai in uno span, in un errore o in un log. Anche afe serve apre il tracer.
  • Un ticket è un solo trace, qualunque processo lo abbia eseguito. Lo span del ticket è la radice. Ogni round è uno span sotto di esso, ogni nodo uno span sotto il suo round, e ogni chiamata al modello e ogni tool call uno span sotto il suo nodo. Ogni span porta token, costo e durata. Il motore calcola gli id degli span dal ticket, così un ticket ripreso su un altro worker continua lo stesso albero. In Langfuse il ticket è anche la sessione.
  • afe serve registra uno span per ogni ticket.start, ticket.resume e ticket.cancel. Lo span di start è il genitore dello span del ticket. Resume e cancel stanno sotto il ticket. Quando chi chiama passa un traceparent W3C a ticket.start, l'intero ticket entra nel trace del chiamante. Uno non valido viene ignorato, e parte un trace nuovo.
  • Ogni testo — prompt, risposte, argomenti e risultati dei tool — passa dalla redazione del motore prima di uscire dal processo. Senza un tracer non si manda nulla. Un tracer che fallisce viene loggato e non fa mai fallire un ticket.

Risoluzione dei problemi​

runtime: set LANGFUSE_HOST (o LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, OTEL_EXPORTER_OTLP_ENDPOINT) Una delle variabili richieste dal tracer non è impostata nell'ambiente del processo. Esportala prima che parta afe run o afe serve. Il motore controlla ogni variabile richiesta prima di aprire il tracer.

runtime: cannot open the tracer at <host> (ConnectError) L'host si è risolto, ma il processo non è riuscito a raggiungerlo: host sbagliato, porta chiusa, o una policy di rete. Il messaggio non include mai una chiave, solo la classe dell'eccezione e l'host.

Nessuno span appare su Langfuse o sul collector Un guasto all'avvio avrebbe fermato il processo, quindi il tracer si è aperto. È l'invio a fallire in silenzio. Un tracer che fallisce non fa mai fallire un ticket. Guarda il log del worker per un avviso da afe.langfuse o afe.otlp.

Vedi anche​