Partilhar via

Fluxos de trabalho do Microsoft Agent Framework - Observabilidade

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

Sugestão

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

Além da telemetria padrão do GenAI, o Agent Framework Workflows emite extensões adicionais, logs e métricas para fornecer informações mais detalhadas sobre a execução do fluxo de trabalho. Estas funcionalidades de observabilidade ajudam os programadores a compreender o fluxo das mensagens, o desempenho dos executores e quaisquer erros que possam ocorrer.

Ativar observabilidade

Por favor, consulte Habilitar a Observabilidade para instruções sobre como ativar a observabilidade nas suas aplicações.

Por favor, consulte Habilitar a Observabilidade para instruções sobre como ativar a observabilidade nas suas aplicações.

Abrangência de fluxo de trabalho

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

Nome do intervalo Description
workflow.build Emitido para cada build de workflow.
workflow.session O intervalo externo representa toda a vida útil de uma execução de fluxo de trabalho, desde o início até ao fim ou erro.
workflow_invoke Emitido para cada ciclo de entrada-para-paragem numa sessão de fluxo de trabalho.
executor.process {executor_id} Emitida para cada executor que está a processar uma mensagem. O ID do executor é acrescentado ao nome do span.
edge_group.process Emitido para cada grupo de arestas ao processar 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 Description
workflow.build Emitido para cada construção de fluxo de trabalho.
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} Gerado para cada grupo de arestas para o processamento de uma mensagem. O tipo de grupo de arestas é adicionado ao nome do span.
message.send Emitida para cada mensagem enviada de um executor para outro executor.

Atributos de Intervalo

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

Attribute Vão(s) Description
workflow.id workflow.build, workflow.session O identificador único do fluxo de trabalho.
workflow.name workflow.session o nome do fluxo de trabalho.
workflow.description workflow.session A descrição do fluxo de trabalho.
workflow.definition workflow.build A definição JSON do grafo de workflow.
session.id workflow.session O identificador único da sessão.
executor.id executor.process O identificador único do executor.
executor.type executor.process O tipo de nome do executor.
executor.input executor.process A mensagem de entrada. Só é definido quando os dados sensíveis estão ativados.
executor.output executor.process A saída do executor. Só é definido quando os dados sensíveis estão ativados.
message.type executor.process, message.send O nome do tipo da mensagem.
message.content message.send O conteúdo da mensagem. Só é definido quando os dados sensíveis estão ativados.
message.source_id message.send O ID do executor que enviou a mensagem.
message.target_id message.send O ID do executor alvo, se especificado.
edge_group.type edge_group.process O tipo do grupo de arestas.
edge_group.delivered edge_group.process Se a mensagem foi entregue (booleano).
edge_group.delivery_status edge_group.process O resultado da entrega (ver Estado de Entrega do Grupo Edge).
error.type Qualquer intervalo no caso de um erro O nome do tipo de exceção.
Attribute Vão(s) Description
workflow.id workflow.build, workflow.run O identificador único do fluxo de trabalho.
workflow.name workflow.run o nome do fluxo de trabalho.
workflow.description workflow.run A descrição do fluxo de trabalho.
workflow.definition workflow.build A definição JSON do grafo de workflow.
workflow_builder.name workflow.build O nome do construtor de fluxos de trabalho.
workflow_builder.description workflow.build A descrição do construtor de fluxos de trabalho.
executor.id executor.process O identificador único do executor.
executor.type executor.process O nome tipo do executor.
message.type executor.process, message.send O tipo de nome da mensagem.
message.payload_type executor.process O tipo de dados da carga útil da mensagem.
message.destination_executor_id message.send O ID do executor alvo, se especificado.
message.source_id edge_group.process O ID do executor que enviou a mensagem.
message.target_id edge_group.process O ID do executor alvo, se especificado.
edge_group.type edge_group.process O tipo de grupo de arestas.
edge_group.id edge_group.process O identificador único 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 (ver Estado de Entrega do Grupo Edge).

Eventos Span

Os eventos de segmento são entradas de registo estruturadas ligadas a segmentos, fornecendo uma linha temporal dos momentos-chave dentro de cada segmento.

Nome do evento Vão(s) Description
build.started workflow.build Emitido quando o processo de construção começa.
build.validation_completed workflow.build Emitido quando a validação do build é concluída com êxito.
build.completed workflow.build Emitido quando a construção é concluída com sucesso.
build.error workflow.build Emitido quando a construção falha.
session.started workflow.session Emitido quando uma sessão de workflow começa.
session.completed workflow.session Emitido quando uma sessão de fluxo de trabalho termina.
session.error workflow.session Emitido quando uma sessão de workflow encontra um erro.
workflow.started workflow_invoke Emitido quando uma invocação de fluxo de trabalho começa.
workflow.completed workflow_invoke Emitido quando uma invocação de fluxo de trabalho termina.
workflow.error workflow_invoke Emitido quando uma invocação de workflow encontra um erro.
Nome do evento Intervalo(Intervalos) Description
build.started workflow.build Emitido quando o processo de construção começa.
build.validation_completed workflow.build Emitido quando a validação da build passa.
build.completed workflow.build Emitido quando a construção é concluída com sucesso.
build.error workflow.build Emitido quando a compilação falha.
workflow.started workflow.run Emitido quando uma execução de fluxo de trabalho começa.
workflow.completed workflow.run Emitido quando uma execução de fluxo de trabalho termina.
workflow.error workflow.run É emitido quando uma execução de workflow encontra um erro.

Quando um executor envia uma mensagem para outro executor, a message.send extensão é criada como um filho da executor.process extensão. No entanto, o executor.process span do executor alvo não é filho do message.send span porque a execução não é aninhada. Em vez disso, o executor.process span do executor do destino está ligado ao message.send span do executor de origem. Esta ligação cria um caminho rastreável através da execução do fluxo de trabalho sem implicar uma hierarquia de chamadas aninhada.

A mesma abordagem de ligação aplica-se aos edge_group.process spans, que estão ligados aos spans de origem message.send para fins de rastreamento de causalidade. Isto suporta cenários fan-in onde múltiplos intervalos de origem contribuem para um único intervalo de processamento.

Estado de Entrega do Grupo Edge

Os intervalos de processamento dos grupos de borda incluem atributos de status de entrega que indicam o resultado do encaminhamento de mensagens através de cada grupo de borda. O edge_group.delivery_status atributo é definido para um dos seguintes valores:

Situação Description
delivered A mensagem era entregue ao executor alvo.
dropped type mismatch O executor do destino não consegue lidar com o tipo de mensagem.
dropped target mismatch A mensagem especificava um alvo que não corresponde a este limite.
dropped condition false A condição de encaminhamento da aresta avaliada como falsa.
exception Ocorreu uma exceção durante o processamento de borda.
buffered A mensagem era armazenada em buffer, à espera de mensagens adicionais (fan-in).

O edge_group.delivered atributo booleano fornece uma verificação rápida para saber se a mensagem foi entregue com sucesso.

Configuração de Telemetria

A telemetria de workflow pode ser ativada através do WithOpenTelemetry método de extensão no workflow builder. A classe WorkflowTelemetryOptions fornece controlo detalhado sobre quais intervalos são emitidos.

Option Predefinição Description
EnableSensitiveData false Inclui entradas brutas, saídas e conteúdo de mensagens nos atributos span.
DisableWorkflowBuild false Desativa workflow.build os spans.
DisableWorkflowRun false Desativa workflow.session e workflow_invoke extensões.
DisableExecutorProcess false Desativa executor.process spans.
DisableEdgeGroupProcess false Desativa edge_group.process os spans.
DisableMessageSend false Desativa message.send os spans.

Advertência

Ativar dados sensíveis faz com que o conteúdo bruto das mensagens, entradas do executor e saídas do executor sejam incluídos na telemetria. Ative isto apenas em ambientes seguros onde os dados de telemetria estejam devidamente protegidos.

A telemetria do fluxo de trabalho é ativada através da função global enable_instrumentation() . Quando a instrumentação está ativada, todos os intervalos de fluxo de trabalho são emitidos automaticamente. A configure_otel_providers() função pode ser usada para configurar exportadores para rastreios, métricas e registos.

Advertência

Revise a configuração do seu pipeline de telemetria para garantir que os dados sensíveis estão devidamente protegidos ao exportar traços.

Próximas Etapas

  • Last updated on