Condividi tramite

Flussi di lavoro di Microsoft Agent Framework - Osservabilità

L'osservabilità fornisce informazioni dettagliate sullo stato interno e sul comportamento dei flussi di lavoro durante l'esecuzione. Sono incluse funzionalità di registrazione, metriche e traccia che consentono di monitorare ed eseguire il debug dei flussi di lavoro.

Suggerimento

L'osservabilità è una funzionalità a livello di framework e non è limitata ai flussi di lavoro. Per ulteriori informazioni, vedere Observability.

Oltre ai dati di telemetria genAI standard, i flussi di lavoro di Agent Framework generano intervalli, log e metriche aggiuntivi per fornire informazioni più approfondite sull'esecuzione del flusso di lavoro. Queste funzionalità di osservabilità consentono agli sviluppatori di comprendere il flusso dei messaggi, le prestazioni degli executor e gli eventuali errori che potrebbero verificarsi.

Abilitare l'osservabilità

Per istruzioni sull'abilitazione dell'osservabilità nelle applicazioni, vedere Abilitare l'osservabilità .

Per istruzioni sull'abilitazione dell'osservabilità nelle applicazioni, vedere Abilitare l'osservabilità .

Intervalli del flusso di lavoro

Durante l'esecuzione del flusso di lavoro vengono generati gli intervalli seguenti:

Nome dello span Descrzione
workflow.build Generato per ogni build del flusso di lavoro.
workflow.session Intervallo esterno che rappresenta l'intera durata di un'esecuzione del flusso di lavoro, dall'avvio fino all'arresto o all'errore.
workflow_invoke Generato per ogni ciclo di input-interruzione all'interno di una sessione del flusso di lavoro.
executor.process {executor_id} Emesso per ogni executor che elabora un messaggio. L'ID executor viene aggiunto al nome dell'intervallo.
edge_group.process Generato per ogni gruppo perimetrale che elabora un messaggio.
message.send Generato per ogni messaggio inviato da un executor a un altro executor.

Durante l'esecuzione del flusso di lavoro vengono generati gli intervalli seguenti:

Nome dello span Descrzione
workflow.build Emesso per ogni compilazione del flusso di lavoro.
workflow.run Generato per ogni esecuzione del flusso di lavoro.
executor.process {executor_id} Generato per ogni executor che processa un messaggio. L'ID dell'esecutore viene aggiunto al nome dello span.
edge_group.process {edge_group_type} Emesso per ogni gruppo di edge che elabora un messaggio. Il tipo di gruppo di bordi viene aggiunto al nome dell'intervallo.
message.send Generato per ogni messaggio inviato da un executor a un altro executor.

Attributi Span

Gli intervalli contengono attributi che forniscono contesto aggiuntivo sull'operazione. Gli attributi seguenti vengono impostati negli intervalli del flusso di lavoro:

Attribute Intervallo(i) Descrzione
workflow.id workflow.build, workflow.session Identificatore univoco del flusso di lavoro.
workflow.name workflow.session Nome del flusso di lavoro.
workflow.description workflow.session Descrizione del flusso di lavoro.
workflow.definition workflow.build Definizione JSON del grafico del flusso di lavoro.
session.id workflow.session Identificatore di sessione univoco.
executor.id executor.process Identificatore univoco dell'esecutore.
executor.type executor.process Nome del tipo dell'executor.
executor.input executor.process Messaggio di input. Impostato solo quando i dati sensibili sono abilitati.
executor.output executor.process Output dell'esecutore. Impostato solo quando i dati sensibili sono abilitati.
message.type executor.process, message.send Nome del tipo del messaggio.
message.content message.send Contenuto del messaggio. Impostato solo quando i dati sensibili sono abilitati.
message.source_id message.send ID dell'esecutore che ha inviato il messaggio.
message.target_id message.send ID dell'esecutore di destinazione, se specificato.
edge_group.type edge_group.process Tipo del gruppo di bordi.
edge_group.delivered edge_group.process Indica se il messaggio è stato recapitato (booleano).
edge_group.delivery_status edge_group.process Esito della consegna (vedere Stato consegna del gruppo Edge).
error.type Qualsiasi intervallo di errore Nome del tipo di eccezione.
Attribute Intervallo Descrzione
workflow.id workflow.build, workflow.run Identificatore univoco del flusso di lavoro.
workflow.name workflow.run Nome del flusso di lavoro.
workflow.description workflow.run Descrizione del flusso di lavoro.
workflow.definition workflow.build Definizione JSON del grafico del flusso di lavoro.
workflow_builder.name workflow.build Nome del generatore di flussi di lavoro.
workflow_builder.description workflow.build Descrizione del generatore di flussi di lavoro.
executor.id executor.process Identificatore univoco dell'esecutore.
executor.type executor.process Nome del tipo dell'esecutore.
message.type executor.process, message.send Nome del tipo del messaggio.
message.payload_type executor.process Tipo di dati del payload del messaggio.
message.destination_executor_id message.send L'identificativo dell'esecutore di destinazione, se specificato.
message.source_id edge_group.process L'ID dell'esecutore che ha inviato il messaggio.
message.target_id edge_group.process L'identificativo dell'executor di destinazione, se specificato.
edge_group.type edge_group.process Tipo del gruppo di bordo.
edge_group.id edge_group.process Identificatore univoco del gruppo di bordi.
edge_group.delivered edge_group.process Indica se il messaggio è stato recapitato (booleano).
edge_group.delivery_status edge_group.process Risultato della consegna (vedere lo Stato di consegna dell'Edge Group).

Eventi span

Gli eventi span sono voci di log strutturate associate a intervalli, fornendo una sequenza temporale di momenti chiave all'interno di ogni intervallo.

Nome evento Span/s Descrzione
build.started workflow.build Generato all'avvio del processo di compilazione.
build.validation_completed workflow.build Generato quando viene superata la convalida della compilazione.
build.completed workflow.build Emesso con successo al termine della compilazione.
build.error workflow.build Generato quando la compilazione ha esito negativo.
session.started workflow.session Generato all'avvio di una sessione del flusso di lavoro.
session.completed workflow.session Generato al termine di una sessione del flusso di lavoro.
session.error workflow.session Generato quando si verifica un errore in una sessione del flusso di lavoro.
workflow.started workflow_invoke Generato all'avvio di una chiamata al flusso di lavoro.
workflow.completed workflow_invoke Generato al termine di una chiamata al flusso di lavoro.
workflow.error workflow_invoke Generato quando una chiamata al flusso di lavoro rileva un errore.
Nome evento Span/s Descrzione
build.started workflow.build Generato all'avvio del processo di compilazione.
build.validation_completed workflow.build Generato quando viene superata la convalida della compilazione.
build.completed workflow.build Generato al termine della compilazione.
build.error workflow.build Generato quando la compilazione ha esito negativo.
workflow.started workflow.run Generato all'avvio di un'esecuzione del flusso di lavoro.
workflow.completed workflow.run Generato al termine dell'esecuzione di un flusso di lavoro.
workflow.error workflow.run Generato quando un'esecuzione del flusso di lavoro rileva un errore.

Quando un executor invia un messaggio a un altro executor, l'intervallo message.send viene creato come figlio dell'intervallo executor.process . Tuttavia, l'intervallo executor.process dell'esecutore di destinazione non è figlio dell'intervallo message.send perché l'esecuzione non è annidata. Al contrario, l'intervallo executor.process dell'executor di destinazione è collegato all'intervallo dell'executor message.send di origine. Questo collegamento crea un percorso tracciabile attraverso l'esecuzione del flusso di lavoro, senza implicare una gerarchia di chiamate annidata.

Lo stesso approccio di collegamento si applica agli edge_group.process intervalli collegati all'intervallo di origine message.send per il rilevamento della causalità. Questo supporta scenari fan-in in cui più intervalli di origine contribuiscono a un singolo intervallo di elaborazione.

Stato di consegna del gruppo Edge

Gli intervalli di elaborazione dei gruppi perimetrali includono attributi dello stato del recapito che indicano il risultato del routing dei messaggi attraverso ogni gruppo perimetrale. L'attributo edge_group.delivery_status è impostato su uno dei valori seguenti:

Condizione Descrzione
delivered Il messaggio è stato recapitato all'esecutore destinato.
dropped type mismatch L'executor di destinazione non può gestire il tipo di messaggio.
dropped target mismatch Il messaggio ha specificato una destinazione che non è coerente con questa interfaccia.
dropped condition false Condizione di routing perimetrale valutata su false.
exception Si è verificata un'eccezione durante l'elaborazione perimetrale.
buffered Il messaggio è stato memorizzato nel buffer, in attesa di messaggi aggiuntivi (fan-in).

L'attributo edge_group.delivered booleano fornisce un rapido controllo per verificare se il messaggio è stato recapitato correttamente.

Configurazione della telemetria

I dati di telemetria del flusso di lavoro possono essere abilitati tramite il WithOpenTelemetry metodo di estensione nel generatore di flussi di lavoro. La WorkflowTelemetryOptions classe fornisce un controllo granulare su quali intervalli vengono generati:

Opzione Impostazione predefinita Descrzione
EnableSensitiveData false Includere input, output e contenuto del messaggio non elaborati negli attributi span.
DisableWorkflowBuild false Disabilita gli workflow.build intervalli.
DisableWorkflowRun false Disabilita workflow.session e workflow_invoke.
DisableExecutorProcess false Disabilita gli executor.process intervalli.
DisableEdgeGroupProcess false Disabilita gli edge_group.process intervalli.
DisableMessageSend false Disabilita gli message.send intervalli.

Avviso

L'abilitazione dei dati sensibili causa l'inserimento nei dati di telemetria di contenuti non elaborati dei messaggi, input e output dell'esecutore. Abilitare questa opzione solo in ambienti sicuri in cui i dati di telemetria sono protetti in modo appropriato.

La telemetria del flusso di lavoro è abilitata tramite la funzione globale enable_instrumentation(). Quando la strumentazione è abilitata, tutti gli intervalli del flusso di lavoro vengono generati automaticamente. La configure_otel_providers() funzione può essere usata per configurare gli esportatori per tracce, metriche e log.

Avviso

Esaminare la configurazione della pipeline di telemetria per assicurarsi che i dati sensibili siano protetti in modo appropriato durante l'esportazione delle tracce.

Passaggi successivi

  • Last updated on