Телеметрия на уровне окружающей среды с Application Insights (предварительный просмотр)

[Эта статья является предварительной документацией и может быть изменена.]

Используйте приложение Azure Insights для мониторинга трассировок агента Copilot Studio, экспортированных из управляемой среды. После настройки экспорта используйте Azure Monitor и Application Insights для проверки запусков агентов, мониторинга выполнения узлов и инструмента, создания оповещений и создания собственных запросов и дашбордов для операционного анализа.

В этой статье объясняется, как настроить экспорт на уровне среды трассировки агентов Copilot Studio в приложение Azure Insights через административный центр Power Platform.

Prerequisites

Прежде чем настроить соединение для экспорта данных, выполните предварительные требования для экспорта данных в Application Insights.

Что экспортируется

При включении экспорта телеметрия агента Copilot Studio записывается в Application Insights в формате наблюдаемости, ориентированном на трассировку и выравниванию с OpenTelemetry, который поддерживает расследование, панели управления и оповещения.

События агентов Copilot Studio записываются на dependencies стол в виде протяжек. Каждое экспортированное событие (, , и InvokeAgent) — это одна спринговая строка (ExecuteToolOutputMessagesitemType). = dependency

Как пролёты образуют след

Телеметрия следует модели trace-and-span OpenTelemetry, реконструированной через operation_Id столбцы и operation_ParentId и:

• Каждый ход агента — это отдельная трасса, идентифицируемая общим operation_Id , что позволяет Application Insights группировать ход и отображать его в сквозной транзакции.
• Пролёт InvokeAgent — это корень следа своего хода. Её ExecuteTool и связанные OutputMessages пролёты гнездятся под ним, каждый несущий operation_ParentId = InvokeAgent пролёт id.
• Разговор охватывает несколько ходов, каждый из которых передаётся как отдельный след. Группируйтесь или фильтруйте gen_ai.conversation.id , чтобы связать повороты одного разговора.
• OutputMessages Span-ы не всегда излучают InvokeAgent корень, то есть они могут (по замыслу) появиться без совпадающего родителя и выглядеть как отдельная трассировка, с одним узлом.

Создание пакета экспорта

Создайте экспортный пакет с типом экспорта, установленным на Copilot Studio, следуя инструкциям в разделе «Создать экспортный пакет» в документации административного центра Power Platform.

Проверка конфигурации

После сохранения конфигурации экспорта запустите тестовый разговор с агентом и убедитесь, что телеметрия поступает в Application Insights. Доставка телеметрии может занять до 24 часов в новых конфигурациях. Убедитесь, что:

• В таблице отображаются агентские dependencies интервалы.
• Каждый ход InvokeAgent, ExecuteToolи OutputMessages , разделяет общий operation_Id.

Поля аналитики приложений

В следующей таблице показаны поля в dependencies таблице и какие поля заполнены для каждого из трёх экспортированных событий агента: InvokeAgent, ExecuteTool, и OutputMessages. Семантика агента и операций находится в customDimensions (ключах gen_ai.* , таких gen_ai.operation.nameкак ), а не в родных столбцах.

customDimensions свойства

Каждый отрезок включает customDimensions JSON. В следующей таблице приведены общие ключи, которые встречаются на каждом пролёте:

Ключи, специфичные для события

В следующей таблице показаны ключи, специфичные для события:

Откройте для себя текущую схему

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

Список столбцов нативной таблицы

Следующий запрос возвращает схему столбца таблицы dependencies . Используйте его для подтверждения доступных родных столбцов при создании запросов, дашбордов или оповещений.

dependencies
| getschema
| project ColumnName, ColumnType
| order by ColumnName asc

Откройте ключи customDimensions (динамические свойства)

Следующий запрос перечисляет все ключи внутри customDimensions JSON в dependencies таблице: имя свойства, события агента, на которых оно появляется (InvokeAgent, ExecuteTool, OutputMessages), и примерное значение. В отличие от родной схемы столбцов, эти свойства динамичны, поэтому этот запрос остаётся точным, когда SDK добавляет новые gen_ai.* или другие ключи. Используйте его как живой источник истины для доступных атрибутов.

dependencies
| where timestamp > ago(7d)
| mv-expand Key = bag_keys(customDimensions) to typeof(string)
| summarize Events = make_set(name), SampleValue = take_any(tostring(customDimensions[Key])) by Key
| order by Key asc

Экспортируемая телеметрия монитора

Используйте Application Insights Logs для запросов активности агентов и изучения работы агентов или инструментов. Вся экспортируемая телеметрия помещается в dependencies таблицу в виде спансов:

• Каждый ход агента — это трассировка, сгруппированная по общей operation_Id.
• Пролёт InvokeAgent — это следовый корень; ExecuteTool и OutputMessages пролёты гнездятся под ним через operation_ParentId.
• Сгруппируйте gen_ai.conversation.id , чтобы переплести несколько оборотов одного и того же разговора, и раздельте этот идентификатор _ , чтобы включить следы субагентов.

Клинки Agents (предварительный просмотр)

Помимо журналов, Application Insights предоставляет встроенные виды агентов (preview ), которые визуализируют экспортированную телеметрию GenAI без написания запросов Kusto. Когда Copilot Studio записывает свои пролеты в dependencies таблицу, эти лопасти читают напрямую из этих данных:

• Agent Runs: Перечисляет призывы агентов, построенные из этих InvokeAgent пролётов, с их продолжительностью, успехом и разговором, к которому принадлежит каждый забег. Существуют некоторые ограничения; Узнайте больше в разделе «Известные ограничения и соображения».
• Инструменты: Агрегирует ExecuteTool диапазоны, чтобы показать, какие инструменты агенты вызывают, как часто и как они работают.
• Модели: Суммирует использование моделей по разным запускам, выявляя вызываемые модели и их паттерны вызовов.

Анализ телеметрии агентов с помощью Application Insights

После подключения вашей среды к Application Insights она регистрирует данные телеметрии агента при взаимодействии пользователей с агентом, в том числе во время тестирования внутри Copilot Studio. Чтобы просмотреть зарегистрированные телеметрические данные, перейдите в раздел «Журналы» вашего ресурса Application Insights в Azure. Здесь вы можете использовать запросы Kusto для запроса и анализа ваших данных. Узнайте больше в разделе «Примеры запросов».

Примеры запросов

Следующие примеры запросов Kusto воссоздают диалоги агентов Copilot Studio из dependencies таблицы в разделе Application Insights. Поскольку каждый отсек имеет общий трассировку operation_Id за ход, порядок запросов располагается с корнем вперёд (до InvokeAgent дочернего спына) внутри каждой трассы.

Запрос 1: Вернуть полную трассу для конкретного идентификатора разговора

Этот запрос возвращает все отсеки для одного известного разговора, упорядоченный хронологически, при этом каждый корневой спан, указанный перед его дочерними спанами. Замените заполнитель Conversation ID на ID разговора вашего агента. Вы можете найти его, введя следующую команду во время тестирования вашего пользовательского агента: /debug conversationid.

let LatestConvo = "<Conversation ID>"; 
dependencies
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| project timestamp, name, id, operation_Id,
          operation_ParentId, duration, target, type, cloud_RoleName,
          resultCode, customDimensions

Запрос 2: Вернуть последнюю переписку конкретного агента

Этот запрос находит самый свежий диалог с именованым агентом в указанном временном окне. Он возвращает все отрезки для этого разговора в том же хронологическом порядке, с корнем вперёд. Замените временное имя агента на имя вашего агента.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo = toscalar(
    dependencies
    | where timestamp > ago(Window)
    | where tostring(customDimensions["gen_ai.agent.name"]) == AgentName
    | where isnotempty(tostring(customDimensions["gen_ai.conversation.id"]))
    | top 1 by timestamp desc
    | project tostring(customDimensions["gen_ai.conversation.id"])
);
dependencies
| where timestamp > ago(Window)
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| project timestamp, name, id, operation_Id,
          operation_ParentId, duration, target, type, cloud_RoleName,
          resultCode, customDimensions

Запрос 3: Развернуть известные свойства genAI OpenTelemetry в столбцы

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

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo =
    toscalar(
        dependencies
        | where timestamp > ago(Window)
        | extend
            AgentName_ = tostring(customDimensions["gen_ai.agent.name"]),
            ConversationId_ = tostring(customDimensions["gen_ai.conversation.id"])
        | where AgentName_ == AgentName
        | where isnotempty(ConversationId_)
        | summarize arg_max(timestamp, ConversationId_)
        | project ConversationId_
    );
dependencies
| where timestamp > ago(Window)
| extend
    ConversationId = tostring(customDimensions["gen_ai.conversation.id"])
| where ConversationId == LatestConvo
| extend
    OperationName    = tostring(customDimensions["gen_ai.operation.name"]),
    AgentId          = tostring(customDimensions["gen_ai.agent.id"]),
    AgentName        = tostring(customDimensions["gen_ai.agent.name"]),
    Model            = tostring(customDimensions["gen_ai.request.model"]),
    ToolName         = tostring(customDimensions["gen_ai.tool.name"]),
    ToolType         = tostring(customDimensions["gen_ai.tool.type"]),
    ToolCallId       = tostring(customDimensions["gen_ai.tool.call.id"]),
    ToolArguments    = tostring(customDimensions["gen_ai.tool.call.arguments"]),
    ToolResult       = tostring(customDimensions["gen_ai.tool.call.result"]),
    EnvironmentId    = tostring(customDimensions["env.id"]),
    TenantId         = tostring(customDimensions["microsoft.tenant.id"]),
    ChannelName      = tostring(customDimensions["microsoft.channel.name"]),
    BlueprintId      = tostring(customDimensions["microsoft.a365.agent.blueprint.id"]),
    PlatformId       = tostring(customDimensions["microsoft.a365.agent.platform.id"]),
    ResourceProvider = tostring(customDimensions["resource.provider"]),
    SignalCategory   = tostring(customDimensions["signal.category"]),
    UserId           = tostring(customDimensions["user.id"]),
    UserName         = tostring(customDimensions["user.name"]),
    UserEmail        = tostring(customDimensions["user.email"])
| extend
    InputMessages  = parse_json(tostring(customDimensions["gen_ai.input.messages"])),
    OutputMessages = parse_json(tostring(customDimensions["gen_ai.output.messages"]))
| extend
    UserInput   = tostring(InputMessages[0].parts[0].content),
    AgentOutput = tostring(OutputMessages[0].parts[0].content)
| order by
    operation_Id asc,
    iff(name == "InvokeAgent", 0, 1) asc,
    timestamp asc
| project
    timestamp, name, id, operation_Id, operation_ParentId, OperationName, ConversationId,
    AgentId, AgentName, Model, ToolName, ToolType, ToolCallId, ToolArguments, ToolResult,
    UserInput, AgentOutput, EnvironmentId, TenantId, ChannelName, BlueprintId, PlatformId,
    ResourceProvider, SignalCategory, UserId, UserName, UserEmail, duration, target, type,
    cloud_RoleName, resultCode, customDimensions

Запрос 4: Динамическое расширение всех свойств genAI OpenTelemetry

Этот запрос возвращает те же spans, что и запрос 3, но каждый gen_ai.* ключ динамически распаковывается из customDimensions в отдельный ga_столбец с префиксом -prefix. Поскольку проекция динамична, любой новый gen_ai.* атрибут, который SDK излучает позже, появляется автоматически без изменения запроса. Замените временное имя агента на имя вашего агента.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo = toscalar(
    dependencies
    | where timestamp > ago(Window)
    | where tostring(customDimensions["gen_ai.agent.name"]) == AgentName
    | where isnotempty(tostring(customDimensions["gen_ai.conversation.id"]))
    | top 1 by timestamp desc
    | project tostring(customDimensions["gen_ai.conversation.id"])
);
dependencies
| where timestamp > ago(Window)
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| mv-apply Key = bag_keys(customDimensions) on (
    where Key startswith "gen_ai."
    | summarize OTelGenAI = make_bag(bag_pack(tostring(Key), customDimensions[tostring(Key)]))
  )
| project timestamp, name, id, operation_Id, operation_ParentId,
          duration, target, type, cloud_RoleName, resultCode,
          OTelGenAI, customDimensions
| evaluate bag_unpack(OTelGenAI, 'ga_')

Запрос 5: Вернуть последнюю переписку для корневого агента со всеми его дочерними чертями, включая субагентов

Этот запрос возвращает последнюю переписку с именным агентом. Он возвращает все промежутки для этого разговора и для всех подагентов первого уровня, которых вызвал. Когда агент вызывает другого агента как инструмент, подагент наследует идентификатор разговора родителя с _<subConversationId> суффиксом. Всё дерево восстанавливается путём сопоставления по идентификатору верхнего уровня. Замените временное имя агента на имя вашего агента.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestRoot =
    toscalar(
        dependencies
        | where timestamp > ago(Window)
        | extend
            AgentName_ = tostring(customDimensions["gen_ai.agent.name"]),
            ConversationId = tostring(customDimensions["gen_ai.conversation.id"])
        | where AgentName_ == AgentName
        | where isnotempty(ConversationId)
        | where ConversationId !has "_"
        | summarize arg_max(timestamp, ConversationId)
        | project ConversationId
    );
dependencies
| where timestamp > ago(Window)
| extend
    ConversationId = tostring(customDimensions["gen_ai.conversation.id"]),
    AgentName_ = tostring(customDimensions["gen_ai.agent.name"]),
    ToolName = tostring(customDimensions["gen_ai.tool.name"]),
    ToolResult = tostring(customDimensions["gen_ai.tool.callresult"])
| where isnotempty(ConversationId)
| where ConversationId == LatestRoot
    or ConversationId startswith strcat(LatestRoot, "_")
| extend
    Depth = countof(ConversationId, "_"),
    AgentRole = iff(ConversationId == LatestRoot, "root", "sub-agent")
| extend
    InputMessages = parse_json( tostring(customDimensions["gen_ai.input.messages"]) ),
    OutputMessages = parse_json( tostring(customDimensions["gen_ai.output.messages"]) )
| extend
    UserInput = tostring(InputMessages[0].parts[0].content),
    AgentOutput = tostring(OutputMessages[0].parts[0].content)
| order by timestamp asc
| project
    timestamp, name, AgentRole, Depth, AgentName, ToolName, ToolResult, UserInput,
    AgentOutput, id, operation_Id, operation_ParentId, ConversationId, duration,
    target, type, cloud_RoleName, resultCode, customDimensions

Известные ограничения и рекомендации

• duration Это значение недоступно для классических трассировок агента.
• Ошибки при выполнении агентов и инструментов в настоящее время некорректно отображаются в статусах трассировки.
• Исходя из ваших требований к проживанию данных, возможно, стоит использовать выделенные ресурсы Application Insights для каждого региона среды.
• В настоящее время подагентные spans являются родителями от InvokeAgent того span, который вызвал агента, вместо span InvokeAgent внутри собственной трассы.
• Идентификаторы трассировки и размахов в настоящее время излучаются как GUID (с префиксом по необходимости), а не полностью выровненными по стандарту OpenTelemetry 32-hex-char trace ID и 16-hex-char span ID.
• Убедитесь, что локальная аутентификация включена на целевом ресурсе Application Insights.
• Экспорт телеметрии не является транзакционным. Во время временных сервисных событий могут происходить небольшие потери данных.
• Могут возникать несоответствия данных при внедрении обновлений внета, связанных со схемой.
• Тематические события, такие как TopicStart, TopicAction, и TopicEnd не фиксируются с помощью телеметрии на уровне окружающей среды.
• Чтобы упростить отчётность и устранение неполадок, избегайте отправки телеметрии на уровне агента и среды в один и тот же экземпляр Application Insights.
• Телеметрия, излучаемая агентами, созданными в агентах, работающих на GitHub Copilot, может отличаться от агентов, встроенных в агенты, основанные на стандартном опыте создания жгута.

Связанная информация

• Обзор телеметрии с Application Insights
• Телеметрия на уровне агента с Application Insights
• Экспорт данных в Application Insights
• приложение Azure Insights