Compartilhar via

Fluxos de trabalho do Microsoft Agent Framework – Observabilidade

A observabilidade fornece insights sobre o estado interno e o comportamento dos fluxos de trabalho durante a execução. Isso inclui recursos de log, métricas e rastreamento que ajudam a monitorar e depurar fluxos de trabalho.

Dica

A observabilidade é um recurso de toda a estrutura e não se limita a fluxos de trabalho. Para obter mais informações, consulte Observabilidade.

Além da telemetria genai padrão, os fluxos de trabalho do Agent Framework emitem intervalos, logs e métricas adicionais para fornecer insights mais profundos sobre a execução do fluxo de trabalho. Esses recursos de observabilidade ajudam os desenvolvedores a entender o fluxo de mensagens, o desempenho dos executores e quaisquer erros que possam ocorrer.

Habilitar a Observabilidade

Consulte Habilitar a Observabilidade para obter instruções sobre como habilitar a observabilidade em seus aplicativos.

Consulte Habilitar a Observabilidade para obter instruções sobre como habilitar a observabilidade em seus aplicativos.

Intervalos de fluxo de trabalho

Os seguintes intervalos são emitidos durante a execução do fluxo de trabalho:

Nome do intervalo DESCRIÇÃO
workflow.build Emitido para cada construção de fluxo de trabalho.
workflow.session Intervalo externo que representa todo o tempo de vida de uma execução de fluxo de trabalho, desde o início até a parada ou o erro.
workflow_invoke Emitido para cada ciclo de entrada para parada dentro de uma sessão de fluxo de trabalho.
executor.process {executor_id} Emitido para cada executor que processa uma mensagem. O ID do executor é acrescentado ao nome do span.
edge_group.process Emitido para cada grupo de borda que processa uma mensagem.
message.send Emitido para cada mensagem enviada de um executor para outro executor.

Os seguintes intervalos são emitidos durante a execução do fluxo de trabalho:

Nome do intervalo DESCRIÇÃO
workflow.build Emitido para cada compilação de workflow.
workflow.run Emitido para cada execução de fluxo de trabalho.
executor.process {executor_id} Emitido para cada executor que processa uma mensagem. O ID do executor é acrescentado ao nome do span.
edge_group.process {edge_group_type} Emitido para cada grupo de extremidade que processa uma mensagem. O tipo de grupo de borda é acrescentado ao nome do intervalo.
message.send Emitido para cada mensagem enviada de um executor para outro executor.

Atributos de "span"

Os spans carregam atributos que fornecem contexto adicional sobre a operação. Os seguintes atributos são definidos em intervalos de fluxo de trabalho:

Attribute Intervalo(s) DESCRIÇÃO
workflow.id workflow.build, workflow.session O identificador exclusivo do fluxo de trabalho.
workflow.name workflow.session Nome do fluxo de trabalho.
workflow.description workflow.session Descrição do fluxo de trabalho.
workflow.definition workflow.build A definição JSON do grafo de fluxo de trabalho.
session.id workflow.session O identificador de sessão exclusivo.
executor.id executor.process O identificador exclusivo do executor.
executor.type executor.process O nome do tipo de executor.
executor.input executor.process A mensagem de entrada. Definir somente quando os dados confidenciais estiverem habilitados.
executor.output executor.process A saída do executor. Definir somente quando os dados confidenciais estiverem habilitados.
message.type executor.process, message.send O nome do tipo da mensagem.
message.content message.send O conteúdo da mensagem. Definir somente quando os dados confidenciais estiverem habilitados.
message.source_id message.send A ID do executor que enviou a mensagem.
message.target_id message.send O ID do executor de destino, se especificado.
edge_group.type edge_group.process O tipo do grupo de aresta.
edge_group.delivered edge_group.process Se a mensagem foi entregue (booleano).
edge_group.delivery_status edge_group.process O resultado da entrega (consulte o Status de Entrega do Grupo de Borda).
error.type Qualquer intervalo de erros O nome do tipo de exceção.
Attribute Intervalo(s) DESCRIÇÃO
workflow.id workflow.build, workflow.run O identificador exclusivo do fluxo de trabalho.
workflow.name workflow.run Nome do fluxo de trabalho.
workflow.description workflow.run Descrição do fluxo de trabalho.
workflow.definition workflow.build A definição JSON do grafo de fluxo de trabalho.
workflow_builder.name workflow.build O nome do construtor de fluxo de trabalho.
workflow_builder.description workflow.build A descrição do construtor de fluxo de trabalho.
executor.id executor.process O identificador exclusivo do executor.
executor.type executor.process O nome do tipo do executor.
message.type executor.process, message.send O nome do tipo da mensagem.
message.payload_type executor.process O tipo de dados do conteúdo da mensagem.
message.destination_executor_id message.send O ID do executor-alvo, caso especificado.
message.source_id edge_group.process A ID do executor que enviou a mensagem.
message.target_id edge_group.process O ID do executor de destino, se especificado.
edge_group.type edge_group.process O tipo do grupo de aresta.
edge_group.id edge_group.process O identificador exclusivo do grupo de borda.
edge_group.delivered edge_group.process Se a mensagem foi entregue (booleano).
edge_group.delivery_status edge_group.process O resultado da entrega (consulte o Status de Entrega do Grupo de Borda).

Eventos de Span

Os eventos de intervalo são entradas de log estruturadas anexadas a intervalos, fornecendo uma linha do tempo de momentos-chave dentro de cada intervalo.

Nome do evento Intervalo(s) DESCRIÇÃO
build.started workflow.build Emitido quando o processo de build é iniciado.
build.validation_completed workflow.build Emissão ocorrida quando a validação da compilação é aprovada.
build.completed workflow.build Emitido quando o build é concluído com êxito.
build.error workflow.build Emitido quando a compilação falha.
session.started workflow.session Emitido quando uma sessão de fluxo de trabalho é iniciada.
session.completed workflow.session Emitido quando uma sessão de fluxo de trabalho é concluída.
session.error workflow.session Emitido quando uma sessão de fluxo de trabalho encontra um erro.
workflow.started workflow_invoke Emitido quando uma invocação de fluxo de trabalho é iniciada.
workflow.completed workflow_invoke Emitido quando uma invocação de fluxo de trabalho é concluída.
workflow.error workflow_invoke Emitido quando uma invocação de fluxo de trabalho encontra um erro.
Nome do evento Intervalo(s) DESCRIÇÃO
build.started workflow.build Emitido quando o processo de build é iniciado.
build.validation_completed workflow.build Emitido quando a validação do build é concluída com sucesso.
build.completed workflow.build Emitido quando o build é concluído com êxito.
build.error workflow.build Emitido quando a compilação falha.
workflow.started workflow.run Emitido quando uma execução de fluxo de trabalho é iniciada.
workflow.completed workflow.run Emitido quando uma execução de fluxo de trabalho é concluída.
workflow.error workflow.run Emitido quando uma execução de fluxo de trabalho encontra um erro.

Quando um executor envia uma mensagem para outro executor, o message.send intervalo é criado como um filho do executor.process intervalo. No entanto, o executor.process intervalo do executor de destino não é um filho do message.send intervalo porque a execução não está aninhada. Em vez disso, o executor.process intervalo do executor de destino está vinculado ao message.send intervalo do executor de origem. Essa vinculação cria um caminho rastreável por meio da execução do fluxo de trabalho sem implicar uma hierarquia de chamadas aninhada.

A mesma abordagem de ligação se aplica aos spans edge_group.process, que estão ligados aos spans de origem message.send para rastreamento de causalidade. Isso dá suporte a cenários de "fan-in", nos quais múltiplos intervalos de origem contribuem para um único intervalo de processamento.

Status de distribuição do grupo de computação de borda

Os intervalos de processamento de grupo de borda incluem atributos de status de entrega que indicam o resultado do roteamento de mensagens por meio de cada grupo de borda. O edge_group.delivery_status atributo é definido como um dos seguintes valores:

Situação DESCRIÇÃO
delivered A mensagem foi entregue ao executor de destino.
dropped type mismatch O executor de destino não pode lidar com o tipo de mensagem.
dropped target mismatch A mensagem especificou um destino que não corresponde a essa borda.
dropped condition false A condição de roteamento de borda foi avaliada como falso.
exception Ocorreu uma exceção durante o processamento de borda.
buffered A mensagem foi armazenada em buffer, aguardando mensagens adicionais (fan-in).

O edge_group.delivered atributo booliano fornece uma verificação rápida de se a mensagem foi entregue com êxito.

Configuração de telemetria

A telemetria de fluxo de trabalho pode ser habilitada por meio do WithOpenTelemetry método de extensão no construtor de fluxo de trabalho. A WorkflowTelemetryOptions classe fornece controle refinado sobre quais intervalos são emitidos:

Opção Default DESCRIÇÃO
EnableSensitiveData false Inclui entradas brutas, saídas e conteúdo da mensagem em atributos de intervalo.
DisableWorkflowBuild false Desabilita workflow.build intervalos.
DisableWorkflowRun false Desativa workflow.session e workflow_invoke spans.
DisableExecutorProcess false Desabilita executor.process intervalos.
DisableEdgeGroupProcess false Desabilita edge_group.process intervalos.
DisableMessageSend false Desabilita message.send intervalos.

Aviso

Habilitar dados confidenciais faz com que o conteúdo bruto da mensagem, as entradas do executor e as saídas do executor sejam incluídos na telemetria. Habilite-o apenas em ambientes seguros em que os dados de telemetria estão protegidos adequadamente.

A telemetria de fluxo de trabalho é habilitada por meio da função global enable_instrumentation() . Quando a instrumentação é habilitada, todos os intervalos de fluxo de trabalho são emitidos automaticamente. A configure_otel_providers() função pode ser usada para configurar exportadores para rastreamentos, métricas e logs.

Aviso

Examine a configuração do pipeline de telemetria para garantir que os dados confidenciais sejam protegidos adequadamente ao exportar rastreamentos.

Próximas etapas

  • Last updated on