Compartir a través de

Flujos de trabajo de Microsoft Agent Framework: observabilidad

La observabilidad proporciona información sobre el estado interno y el comportamiento de los flujos de trabajo durante la ejecución. Esto incluye las funcionalidades de registro, métricas y seguimiento que ayudan a supervisar y depurar flujos de trabajo.

Sugerencia

La observabilidad es una característica de todo el marco y no se limita a los flujos de trabajo. Para obtener más información, consulte Observabilidad.

Además de la telemetría estándar de GenAI, los flujos de trabajo del marco de agente emiten intervalos, registros y métricas adicionales para proporcionar información más detallada sobre la ejecución del flujo de trabajo. Estas características de observabilidad ayudan a los desarrolladores a comprender el flujo de mensajes, el rendimiento de los ejecutores y los errores que puedan producirse.

Habilitación de la observabilidad

Consulte Habilitación de la observabilidad para obtener instrucciones sobre cómo habilitar la observabilidad en las aplicaciones.

Consulte Habilitación de la observabilidad para obtener instrucciones sobre cómo habilitar la observabilidad en las aplicaciones.

Intervalos de flujo de trabajo

Los intervalos siguientes se emiten durante la ejecución del flujo de trabajo:

Nombre del tramo Description
workflow.build Se emite para cada ejecución de flujo de trabajo.
workflow.session Intervalo externo que representa toda la duración de una ejecución de flujo de trabajo, desde el inicio hasta la detención o el error.
workflow_invoke Se emite para cada ciclo de entrada para detenerse dentro de una sesión de flujo de trabajo.
executor.process {executor_id} Se emite para cada ejecutor que procesa un mensaje. El identificador del ejecutor se anexa al nombre del span.
edge_group.process Se emite para cada grupo perimetral que procesa un mensaje.
message.send Se emite para cada mensaje enviado desde un ejecutor a otro ejecutor.

Los intervalos siguientes se emiten durante la ejecución del flujo de trabajo:

Nombre del tramo Description
workflow.build Se emite para cada construcción de flujo de trabajo.
workflow.run Se emite para cada ejecución de flujo de trabajo.
executor.process {executor_id} Se emite para cada ejecutor que procesa un mensaje. El ID del ejecutor se adjunta al nombre del span.
edge_group.process {edge_group_type} Se emite para cada grupo perimetral que procesa un mensaje. El tipo de grupo perimetral se anexa al nombre del intervalo.
message.send Se emite para cada mensaje enviado desde un ejecutor a otro ejecutor.

Atributos de span

Los intervalos llevan atributos que proporcionan contexto adicional sobre la operación. Los atributos siguientes se establecen en intervalos de flujo de trabajo:

Atributo Intervalos Description
workflow.id workflow.build, workflow.session Identificador único del flujo de trabajo.
workflow.name workflow.session El nombre del flujo de trabajo.
workflow.description workflow.session La descripción del flujo de trabajo.
workflow.definition workflow.build Definición JSON del gráfico de flujo de trabajo.
session.id workflow.session Identificador de sesión único.
executor.id executor.process Identificador único del ejecutor.
executor.type executor.process Nombre de tipo del ejecutor.
executor.input executor.process Mensaje de entrada. Solo se establece cuando se habilitan los datos confidenciales.
executor.output executor.process Salida del ejecutor. Solo se establece cuando se habilitan los datos confidenciales.
message.type executor.process, message.send Nombre de tipo del mensaje.
message.content message.send Contenido del mensaje. Solo se establece cuando se habilitan los datos confidenciales.
message.source_id message.send Identificador del ejecutor que envió el mensaje.
message.target_id message.send Identificador del ejecutor de destino, si se especifica.
edge_group.type edge_group.process Tipo del grupo perimetral.
edge_group.delivered edge_group.process Indica si el mensaje se entregó (booleano).
edge_group.delivery_status edge_group.process El resultado de la entrega (consulte Estado de entrega del grupo perimetral).
error.type Cualquier intervalo en caso de error Nombre del tipo de excepción.
Atributo Intervalos Description
workflow.id workflow.build, workflow.run Identificador único del flujo de trabajo.
workflow.name workflow.run El nombre del flujo de trabajo.
workflow.description workflow.run La descripción del flujo de trabajo.
workflow.definition workflow.build Definición JSON del gráfico de flujo de trabajo.
workflow_builder.name workflow.build Nombre del generador de flujos de trabajo.
workflow_builder.description workflow.build Descripción del generador de flujos de trabajo.
executor.id executor.process Identificador único del ejecutor.
executor.type executor.process Nombre de tipo del ejecutor.
message.type executor.process, message.send Nombre de tipo del mensaje.
message.payload_type executor.process Tipo de datos de la carga del mensaje.
message.destination_executor_id message.send Identificador del ejecutor de destino, si se especifica.
message.source_id edge_group.process Identificador del ejecutor que envió el mensaje.
message.target_id edge_group.process Identificador del ejecutor de destino, si se especifica.
edge_group.type edge_group.process Tipo del grupo perimetral.
edge_group.id edge_group.process Identificador único del grupo perimetral.
edge_group.delivered edge_group.process Indica si el mensaje se entregó (booleano).
edge_group.delivery_status edge_group.process El resultado de la entrega (consulte Estado de entrega del grupo perimetral).

Span Events

Los eventos de spans son entradas de registro estructuradas asociadas a spans, proporcionando una cronología de momentos clave dentro de cada span.

Nombre del evento Intervalos Description
build.started workflow.build Se genera cuando comienza el proceso de compilación.
build.validation_completed workflow.build Se genera cuando se supera la validación de compilación.
build.completed workflow.build Se genera cuando la compilación se completa correctamente.
build.error workflow.build Se genera cuando se produce un error en la compilación.
session.started workflow.session Se genera cuando comienza una sesión de flujo de trabajo.
session.completed workflow.session Se genera cuando se completa una sesión de flujo de trabajo.
session.error workflow.session Se genera cuando una sesión de flujo de trabajo encuentra un error.
workflow.started workflow_invoke Se genera cuando comienza una invocación de flujo de trabajo.
workflow.completed workflow_invoke Se genera cuando se completa una invocación de flujo de trabajo.
workflow.error workflow_invoke Se genera cuando una invocación de flujo de trabajo encuentra un error.
Nombre del evento Intervalos Description
build.started workflow.build Se genera cuando comienza el proceso de compilación.
build.validation_completed workflow.build Se genera cuando se supera la validación de compilación.
build.completed workflow.build Se genera cuando la compilación se completa correctamente.
build.error workflow.build Se genera cuando se produce un error en la compilación.
workflow.started workflow.run Se genera cuando comienza una ejecución de flujo de trabajo.
workflow.completed workflow.run Se genera cuando se completa una ejecución de flujo de trabajo.
workflow.error workflow.run Se genera cuando una ejecución de flujo de trabajo encuentra un error.

Cuando un ejecutor envía un mensaje a otro ejecutor, el message.send intervalo se crea como elemento secundario del executor.process intervalo. Sin embargo, el executor.process intervalo del ejecutor de destino no es un elemento secundario del message.send intervalo porque la ejecución no está anidada. En su lugar, el executor.process intervalo del ejecutor de destino está vinculado al message.send intervalo del ejecutor de origen. Esta vinculación crea una ruta de acceso rastreable a través de la ejecución del flujo de trabajo sin implicar una jerarquía de llamadas anidada.

El mismo enfoque de vinculación se aplica a los intervalos edge_group.process, que están vinculados a los intervalos de origen message.send para el seguimiento de causalidad. Esto admite escenarios de convergencia de entradas en los que varios intervalos de origen contribuyen a un único intervalo de procesamiento.

Estado de entrega del grupo perimetral

Los intervalos de procesamiento de grupos perimetrales incluyen atributos de estado de entrega que indican el resultado del enrutamiento de mensajes a través de cada grupo perimetral. El edge_group.delivery_status atributo se establece en uno de los siguientes valores:

Situación Description
delivered El mensaje se entregó al ejecutor de destino.
dropped type mismatch El ejecutor de destino no puede controlar el tipo de mensaje.
dropped target mismatch El mensaje especificó un destino que no coincide con este borde.
dropped condition false La condición de enrutamiento perimetral resultó ser falsa.
exception Se produjo una excepción durante el procesamiento perimetral.
buffered El mensaje fue almacenado en búfer, a la espera de mensajes adicionales (fan-in).

El edge_group.delivered atributo booleano proporciona una comprobación rápida de si el mensaje se entregó correctamente.

Configuración de telemetría

La telemetría del flujo de trabajo se puede habilitar a través del método de extensión WithOpenTelemetry en el generador de flujos de trabajo. La WorkflowTelemetryOptions clase proporciona un control específico sobre qué intervalos se emiten:

Opción Predeterminado Description
EnableSensitiveData false Incluye entradas, salidas y contenido de mensajes sin procesar en atributos de span.
DisableWorkflowBuild false Deshabilita los workflow.build intervalos.
DisableWorkflowRun false workflow.session Deshabilita y workflow_invoke abarca.
DisableExecutorProcess false Deshabilita los executor.process intervalos.
DisableEdgeGroupProcess false Deshabilita los edge_group.process intervalos.
DisableMessageSend false Deshabilita los message.send intervalos.

Advertencia

La habilitación de datos confidenciales provoca que se incluya contenido sin procesar, entradas del ejecutor y salidas del ejecutor en la telemetría. Habilite esto solo en entornos seguros en los que los datos de telemetría estén protegidos adecuadamente.

La telemetría de flujo de trabajo está habilitada a través de la función global enable_instrumentation() . Cuando la instrumentación está habilitada, todos los intervalos de flujo de trabajo se emiten automáticamente. La configure_otel_providers() función se puede usar para configurar exportadores para seguimientos, métricas y registros.

Advertencia

Revise la configuración de la canalización de telemetría para asegurarse de que los datos confidenciales están protegidos correctamente al exportar seguimientos.

Pasos siguientes

  • Last updated on