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 Span externo que representa toda a duração da execução de um fluxo de trabalho, do início ao fim ou erro.
workflow_invoke Emitido para cada ciclo de entrada-parada em 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 arestas 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 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} Emitido para cada grupo de arestas que processa uma mensagem. O tipo do grupo de arestas é anexado ao nome do span.
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 construção de fluxo de trabalho.
workflow.session Span externo que representa a duração de uma sessão de execução de fluxo de trabalho.
workflow_invoke Emitido para cada ciclo de entrada-parada em 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 arestas que processa uma mensagem.
message.send Emitido para cada mensagem enviada de um executor para outro.

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 do executor.
executor.input executor.process A mensagem de entrada. Definido somente quando dados confidenciais estão habilitados.
executor.output executor.process A saída do executor. Definido somente quando dados confidenciais estão habilitados.
message.type executor.process, message.send O nome do tipo da mensagem.
message.content message.send O conteúdo da mensagem. Definido somente quando dados confidenciais estão 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 arestas.
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 span em caso de erro. 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 da carga útil da mensagem.
message.destination_executor_id message.send O ID do executor de destino, se 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 arestas.
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).
Attribute Intervalo(s) DESCRIÇÃO
workflow.id workflow.build, workflow.session, workflow_invoke O ID do executor que inicia o fluxo de trabalho.
workflow.name workflow.session, workflow_invoke O nome do fluxo de trabalho, quando definido.
workflow.description workflow.session, workflow_invoke A descrição do fluxo de trabalho, quando definida.
workflow.definition workflow.build A definição JSON do grafo de fluxo de trabalho.
session.id workflow.session, workflow_invoke O identificador de sessão de fluxo de trabalho.
executor.id executor.process O ID do executor.
executor.implementation.id executor.process A ID de implementação do executor.
executor.input executor.process A mensagem de entrada. Definido somente quando dados confidenciais estão habilitados.
executor.output executor.process A saída do executor. Definido somente quando dados confidenciais estão habilitados.
message.type executor.process O nome do tipo da mensagem processada.
message.content message.send O conteúdo da mensagem. Definido somente quando dados confidenciais estão habilitados.
message.source_id edge_group.process, message.send A ID do executor que enviou a mensagem.
message.target_id edge_group.process, message.send A ID do executor de destino, quando especificada.
edge_group.type edge_group.process O tipo de grupo de borda que está sendo processado.
edge_group.delivered edge_group.process Se a mensagem foi entregue.
edge_group.delivery_status edge_group.process O resultado da entrega (consulte o Status de Entrega do Grupo de Borda).
error.type Qualquer span em caso de erro. O nome do tipo de exceção.
error.message Qualquer span em caso de erro. A mensagem de exceção.

Eventos de Span

Os eventos de span são entradas de log estruturadas anexadas aos spans, fornecendo uma linha do tempo dos principais momentos dentro de cada span.

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 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.
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.
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.

Quando um executor envia uma mensagem para outro executor, o message.send intervalo é criado como um filho do executor.process intervalo. No entanto, o span executor.process do executor de destino não é filho do span message.send 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 vinculação se aplica aos spans edge_group.process, que são vinculados aos spans message.send de origem para rastreamento de causalidade. Isso suporta cenários de fan-in, nos quais vários spans de origem contribuem para um único span de processamento.

Status de Entrega do Grupo de Bordas

Os spans de processamento do grupo de bordas incluem atributos de status de entrega que indicam o resultado do roteamento de mensagens por meio de cada grupo de bordas. 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 falsa.
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 Desativa os spans workflow.build.
DisableWorkflowRun false Desativa os spans workflow.session e workflow_invoke.
DisableExecutorProcess false Desativa os spans executor.process.
DisableEdgeGroupProcess false Desativa os spans edge_group.process.
DisableMessageSend false Desativa os spans message.send.

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 está habilitada, todos os spans do 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.

Observabilidade do fluxo de trabalho

A telemetria de fluxos de trabalho pode ser habilitada com WithTelemetry no construtor de fluxos de trabalho. Use o pacote de rastreamento OpenTelemetry do fluxo de trabalho para conectar os spans ao seu provedor OpenTelemetry.

Habilitar rastreamento de fluxo de trabalho

import workflowotel "github.com/microsoft/agent-framework-go/workflow/observability/opentelemetry"

wf, err := workflow.NewBuilder(startExecutor).
    AddEdge(startExecutor, nextExecutor).
    WithTelemetry(
        workflowotel.New(workflowotel.Config{}),
        workflow.TelemetryOptions{EnableSensitiveData: true},
    ).
    Build()

TelemetryOptions pode desativar os spans de compilação/execução do fluxo de trabalho, processo executor, grupo de arestas ou envio de mensagens e pode incluir entradas e saídas serializadas quando EnableSensitiveData estiver definido.

Observar eventos de fluxo de trabalho

Monitorar a execução do fluxo de trabalho por meio de fluxos de eventos:

for evt := range run.NewEvents() {
    switch e := evt.(type) {
    case workflow.ExecutorCompletedEvent:
        log.Printf("Executor %s completed", e.ExecutorID)
    }
}

Próximas etapas

  • Last updated on