Рабочие процессы Microsoft Agent Framework — наблюдаемость

Наблюдаемость предоставляет аналитические сведения о внутреннем состоянии и поведении рабочих процессов во время выполнения. К ним относятся возможности ведения журнала, метрик и трассировки, которые помогают отслеживать и отлаживать рабочие процессы.

Tip

Наблюдаемость — это функция на уровне платформы и не ограничивается рабочими процессами. Дополнительные сведения см. в разделе "Наблюдаемость".

Помимо стандартной телеметрии GenAI рабочие процессы Agent Framework предоставляют дополнительные диапазоны, журналы и метрики для более глубокого анализа выполнения рабочих процессов. Эти функции наблюдения помогают разработчикам понять поток сообщений, производительность исполнителей и любые ошибки, которые могут возникнуть.

Включение наблюдаемости

Ознакомьтесь с инструкциями по включению наблюдаемости в приложениях.

Ознакомьтесь с инструкциями по включению наблюдаемости в приложениях.

Диапазоны рабочих процессов

Во время выполнения рабочего процесса генерируются следующие спаны:

Имя диапазона Описание
workflow.build Выдается для каждой сборки рабочего процесса.
workflow.session Внешний диапазон, представляющий всю жизнь выполнения рабочего процесса, начиная с начала до остановки или ошибки.
workflow_invoke Издается для каждого цикла от ввода до остановки в сеансе рабочего процесса.
executor.process {executor_id} Выдается для каждого исполнителя, обрабатывающего сообщение. Идентификатор исполнителя добавляется к имени спана.
edge_group.process Генерируется для каждой группы узлов, обрабатывающей сообщение.
message.send Излучается для каждого сообщения, отправленного исполнителем другому исполнителю.

Во время выполнения рабочего процесса генерируются следующие спаны:

Имя диапазона Описание
workflow.build Выдается для каждой сборки рабочего процесса.
workflow.run Генерируется для каждого выполнения рабочего процесса.
executor.process {executor_id} Выдается для каждого исполнителя, обрабатывающего сообщение. Идентификатор исполнителя добавляется к имени спана.
edge_group.process {edge_group_type} Генерируется для каждой группы узлов, обрабатывающей сообщение. Тип периферийной группы добавляется к имени диапазона.
message.send Излучается для каждого сообщения, отправленного исполнителем другому исполнителю.

Во время выполнения рабочего процесса генерируются следующие спаны:

Имя диапазона Описание
workflow.build Выдается для каждой сборки рабочего процесса.
workflow.session Внешний диапазон, представляющий время существования сеанса выполнения рабочего процесса.
workflow_invoke Издается для каждого цикла от ввода до остановки в сеансе рабочего процесса.
executor.process {executor_id} Выдается для каждого исполнителя, обрабатывающего сообщение. Идентификатор исполнителя добавляется к имени спана.
edge_group.process Генерируется для каждой группы узлов, обрабатывающей сообщение.
message.send Генерируется для каждого сообщения, отправленного от одного исполнителя другому.

Атрибуты диапазона

Диапазоны содержат атрибуты, предоставляющие дополнительный контекст для операции. Следующие атрибуты задаются в диапазонах рабочих процессов:

Attribute Диапазоны Описание
workflow.id workflow.build, workflow.session Уникальный идентификатор рабочего процесса.
workflow.name workflow.session Название рабочего процесса.
workflow.description workflow.session Описание рабочего процесса.
workflow.definition workflow.build Определение JSON графа рабочего процесса.
session.id workflow.session Уникальный идентификатор сеанса.
executor.id executor.process Уникальный идентификатор исполнителя.
executor.type executor.process Имя типа исполнителя.
executor.input executor.process Входное сообщение. Устанавливается только в том случае, если конфиденциальные данные включены.
executor.output executor.process Выходные данные исполнителя. Устанавливается только в том случае, если конфиденциальные данные включены.
message.type executor.process, message.send Имя типа сообщения
message.content message.send Содержимое сообщения. Устанавливается только в том случае, если конфиденциальные данные включены.
message.source_id message.send Идентификатор исполнителя, отправляющего сообщение.
message.target_id message.send Идентификатор целевого исполнителя, если он указан.
edge_group.type edge_group.process Тип пограничной группы.
edge_group.delivered edge_group.process Было ли доставлено сообщение (булево значение).
edge_group.delivery_status edge_group.process Результат доставки (см. состояние доставки группы Edge).
error.type Любой диапазон при ошибке Имя типа исключения.
Attribute Диапазоны Описание
workflow.id workflow.build, workflow.run Уникальный идентификатор рабочего процесса.
workflow.name workflow.run Название рабочего процесса.
workflow.description workflow.run Описание рабочего процесса.
workflow.definition workflow.build Определение JSON графа рабочего процесса.
workflow_builder.name workflow.build Имя конструктора рабочих процессов.
workflow_builder.description workflow.build Описание построителя рабочих процессов.
executor.id executor.process Уникальный идентификатор исполнителя.
executor.type executor.process Имя типа исполнителя.
message.type executor.process, message.send Имя типа сообщения
message.payload_type executor.process Тип данных нагрузки сообщения.
message.destination_executor_id message.send Идентификатор целевого исполнителя, если он указан.
message.source_id edge_group.process Идентификатор исполнителя, отправляющего сообщение.
message.target_id edge_group.process Идентификатор целевого исполнителя, если он указан.
edge_group.type edge_group.process Тип пограничной группы.
edge_group.id edge_group.process Уникальный идентификатор пограничной группы.
edge_group.delivered edge_group.process Было ли доставлено сообщение (булево значение).
edge_group.delivery_status edge_group.process Результат доставки (см. состояние доставки группы Edge).
Attribute Диапазоны Описание
workflow.id workflow.build, workflow.session, workflow_invoke Идентификатор исполнителя запуска рабочего процесса.
workflow.name workflow.session, workflow_invoke Имя рабочего процесса при установке.
workflow.description workflow.session, workflow_invoke Описание рабочего процесса при установке.
workflow.definition workflow.build Определение JSON графа рабочего процесса.
session.id workflow.session, workflow_invoke Идентификатор сеанса рабочего процесса.
executor.id executor.process Идентификатор исполнителя.
executor.implementation.id executor.process Идентификатор реализации исполнителя.
executor.input executor.process Входное сообщение. Устанавливается только в том случае, если конфиденциальные данные включены.
executor.output executor.process Выходные данные исполнителя. Устанавливается только в том случае, если конфиденциальные данные включены.
message.type executor.process Имя типа обработанного сообщения.
message.content message.send Содержимое сообщения. Устанавливается только в том случае, если конфиденциальные данные включены.
message.source_id edge_group.process, message.send Идентификатор исполнителя, отправляющего сообщение.
message.target_id edge_group.process, message.send Идентификатор целевого исполнителя, если указан.
edge_group.type edge_group.process Тип обрабатываемой группы рёбер.
edge_group.delivered edge_group.process Было ли доставлено сообщение.
edge_group.delivery_status edge_group.process Результат доставки (см. состояние доставки группы Edge).
error.type Любой диапазон при ошибке Имя типа исключения.
error.message Любой диапазон при ошибке Сообщение об исключении.

События диапазона

События спана являются структурированными записями логов, прикрепленными к спанам, предоставляя временную последовательность ключевых событий в каждом спане.

Название мероприятия Диапазоны Описание
build.started workflow.build Генерируется при запуске процесса сборки.
build.validation_completed workflow.build Выдаётся при успешном прохождении проверки сборки.
build.completed workflow.build Излучается при успешном завершении сборки.
build.error workflow.build Генерируется при сбое сборки.
session.started workflow.session Инициируется при запуске сеанса рабочего процесса.
session.completed workflow.session Создается при завершении сеанса рабочего процесса.
session.error workflow.session Выдается при возникновении ошибки в сеансе рабочего процесса.
workflow.started workflow_invoke Срабатывает при запуске вызова рабочего процесса.
workflow.completed workflow_invoke Сигнализируется при завершении инвокации рабочего процесса.
workflow.error workflow_invoke Генерируется событие при возникновении ошибки во время вызова рабочего процесса.
Название мероприятия Диапазоны Описание
build.started workflow.build Генерируется при запуске процесса сборки.
build.validation_completed workflow.build Выдаётся при успешном прохождении проверки сборки.
build.completed workflow.build Излучается при успешном завершении сборки.
build.error workflow.build Генерируется при сбое сборки.
workflow.started workflow.run Выдается при запуске выполнения рабочего процесса.
workflow.completed workflow.run Генерируется при завершении выполнения рабочего процесса.
workflow.error workflow.run Генерируется событие при обнаружении ошибки во время запуска рабочего процесса.
Название мероприятия Диапазоны Описание
build.started workflow.build Генерируется при запуске процесса сборки.
build.validation_completed workflow.build Выдаётся при успешном прохождении проверки сборки.
build.completed workflow.build Излучается при успешном завершении сборки.
build.error workflow.build Генерируется при сбое сборки.
session.started workflow.session Инициируется при запуске сеанса рабочего процесса.
session.completed workflow.session Создается при завершении сеанса рабочего процесса.
session.error workflow.session Выдается при возникновении ошибки в сеансе рабочего процесса.
workflow.started workflow_invoke Срабатывает при запуске вызова рабочего процесса.
workflow.completed workflow_invoke Сигнализируется при завершении инвокации рабочего процесса.
workflow.error workflow_invoke Генерируется событие при возникновении ошибки во время вызова рабочего процесса.

Когда шаг выполнения отправляет сообщение другому шагу выполнения, диапазон message.send создается как дочерний элемент диапазона executor.process. Однако диапазон целевого исполнителя executor.process является дочерним элементом диапазона, поскольку выполнение не является вложенным. Вместо этого executor.process диапазон целевого исполнителя связан с message.send диапазоном исходного исполнителя. Это связывание создает трассируемый путь через выполнение рабочего процесса, не подразумевая вложенную иерархию вызовов.

Тот же подход связывания применяется к edge_group.process диапазонам, которые связаны с диапазонами источника message.send для отслеживания причинности. Это поддерживает сценарии слияния, в которых несколько участков источников способствуют одному участку обработки.

Статус доставки Edge-групп

Диапазоны обработки пограничных групп включают атрибуты состояния доставки, указывающие результат маршрутизации сообщений через каждую граничную группу. Атрибут edge_group.delivery_status имеет одно из следующих значений:

Статус Описание
delivered Сообщение было доставлено целевому исполнителю.
dropped type mismatch Целевой исполнитель не может обрабатывать тип сообщения.
dropped target mismatch Сообщение указало целевой объект, который не соответствует этому краю.
dropped condition false Условие маршрутизации ребра оказалось ложным.
exception Исключение произошло во время пограничной обработки.
buffered Сообщение было буферизованно, ожидая дополнительных сообщений (вентилятор).

Логический edge_group.delivered атрибут обеспечивает быструю проверку успешности доставки сообщения.

Конфигурация телеметрии

Телеметрию рабочего процесса можно включить с помощью WithOpenTelemetry метода расширения в конструкторе рабочих процессов. Класс WorkflowTelemetryOptions обеспечивает точный контроль над тем, какие диапазоны выводятся:

Опция Default Описание
EnableSensitiveData false Включает необработанные входные данные, выходные данные и содержимое сообщения в атрибутах диапазона.
DisableWorkflowBuild false Отключает workflow.build диапазоны.
DisableWorkflowRun false Отключает диапазоны workflow.session и workflow_invoke.
DisableExecutorProcess false Отключает executor.process диапазоны.
DisableEdgeGroupProcess false Отключает edge_group.process диапазоны.
DisableMessageSend false Отключает message.send диапазоны.

Предупреждение

Включение конфиденциальных данных приводит к тому, что содержимое необработанных сообщений, входные данные исполнителя и выходные данные исполнителя будут включены в данные телеметрии. Это можно включить только в безопасных средах, где данные телеметрии надлежащим образом защищены.

Телеметрия рабочего процесса активируется через глобальную enable_instrumentation() функцию. Если инструментирование включено, все трассы рабочих процессов выдаются автоматически. Функцию configure_otel_providers() можно использовать для настройки экспортеров для трассировок, метрик и журналов.

Предупреждение

Просмотрите конфигурацию конвейера телеметрии, чтобы обеспечить соответствующую защиту конфиденциальных данных при экспорте трассировок.

Наблюдаемость рабочего процесса

Телеметрию рабочего процесса можно включить с помощью WithTelemetry в конструкторе рабочих процессов. Используйте пакет трассировщика OpenTelemetry для workflow, чтобы подключить спаны к вашему провайдеру OpenTelemetry.

Включение трассировки рабочих процессов

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 позволяет отключить спаны этапов сборки и запуска рабочего процесса, процесса исполнителя, пограничной группы или отправки сообщений, а также включать сериализованные входные и выходные данные, если задан EnableSensitiveData.

Наблюдение за событиями рабочего процесса

Мониторинг выполнения рабочего процесса с помощью потоков событий:

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

Дальнейшие шаги

  • Last updated on