Telemetria em nível ambiental com Application Insights (prévia)

[Este artigo é uma documentação de pré-lançamento e está sujeito a alterações.]

Use o Aplicativo Azure Insights para monitorar os rastros de agentes do Copilot Studio exportados de um ambiente gerenciado. Depois de configurar a exportação, use o Azure Monitor e o Application Insights para validar execuções de agentes, monitorar a execução de nós e ferramentas, criar alertas e criar consultas e dashboards personalizados para análise operacional.

Este artigo explica como configurar a exportação em nível ambiente dos rastros de agentes do Copilot Studio para o Aplicativo Azure Insights por meio do centro de administração do Power Platform.

Pré-requisitos

Antes de configurar a conexão de exportação de dados, complete os pré-requisitos de Exportar dados para o Application Insights.

O que é exportado

Quando você habilita a exportação, a telemetria de rastreamento do agente do Copilot Studio é escrita para o Application Insights em um formato de observabilidade orientado a traços e alinhado ao OpenTelemetry, que suporta investigação, dashboards e alertas.

Os eventos de agente do Copilot Studio são gravados na tabela dependencies na forma de spans. Cada evento exportado (InvokeAgent, ExecuteTool e OutputMessages) é uma única linha de span (itemType = dependency).

Como os vãos formam um traço

A telemetria segue o modelo de rastros e spans do OpenTelemetry, e é reconstruída por meio das colunas operation_Id e operation_ParentId:

• Cada turno do agente constitui um rastreamento próprio, identificado por um operation_Id compartilhado, o que permite ao Application Insights agrupar o turno e exibi-lo na visão da transação de ponta a ponta.
• O InvokeAgent vão é a raiz do traço de sua curva. Seus ExecuteTool intervalos e os OutputMessages conectados ficam aninhados abaixo dele, cada um carregando operation_ParentId = o InvokeAgent do intervalo id.
• Uma conversa se estende por vários turnos, cada um emitido como um rastreio separado. Agrupe ou filtre por gen_ai.conversation.id para reunir novamente as interações de uma conversa.
• OutputMessages spans nem sempre emitem uma raiz InvokeAgent, o que significa que podem (por design) chegar sem um pai correspondente e aparecer como um trace independente, composto por um único nó.

Criar um pacote de exportação

Crie um pacote de exportação com o tipo de exportação definido para Copilot Studio seguindo as instruções em Criar um pacote de exportação da documentação do centro de administração do Power Platform.

Validar a configuração

Depois de salvar a configuração de exportação, execute uma conversa de teste com o agente e confirme que a telemetria chegou ao Application Insights. A entrega de telemetria pode levar até 24 horas em novas configurações. Valide isso:

• Os spans de agente aparecem na tabela dependencies.
• Os intervalos InvokeAgent, ExecuteTool e OutputMessages de cada turno compartilham um operation_Id.

Campos do Application Insights

A tabela a seguir mostra os campos na dependencies tabela e quais campos são preenchidos para cada um dos três eventos do agente exportado: InvokeAgent, ExecuteTool, e OutputMessages. A semântica do agente e da operação está em customDimensions (nas chaves gen_ai.*, como gen_ai.operation.name), não nas colunas nativas.

propriedades de customDimensions

Cada span inclui o JSON customDimensions. A tabela a seguir mostra as chaves comuns que aparecem em cada span:

Chaves específicas de eventos

A tabela a seguir mostra as chaves específicas de cada evento:

Descubra o esquema atual

O esquema documentado neste artigo pode evoluir ao longo do tempo. Em vez de depender apenas das tabelas mencionadas anteriormente, use as seguintes consultas para inspecionar o esquema mais recente ao vivo no seu próprio ambiente.

Listar colunas nativas de tabela

A consulta seguinte retorna o esquema em nível de coluna da dependencies tabela. Use-o para confirmar colunas nativas disponíveis ao criar consultas, dashboards ou alertas.

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

Conheça os campos customDimensions (propriedades dinâmicas)

A consulta a seguir lista todas as chaves dentro do customDimensions JSON na dependencies tabela: o nome da propriedade, em quais eventos de agente ele aparece (InvokeAgent, ExecuteTool, OutputMessages), e um valor de exemplo. Ao contrário do esquema nativo de colunas, essas propriedades são dinâmicas, então essa consulta permanece precisa à medida que o SDK adiciona novas gen_ai.* ou outras chaves. Use-o como fonte viva de verdade para atributos disponíveis.

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

Monitorar a telemetria exportada

Use os Logs do Application Insights para consultar a atividade do agente e investigar a execução do agente ou da ferramenta. Toda a telemetria exportada aparece na dependencies tabela como abrangências:

• Cada turno do agente é um rastreamento, agrupado por um operation_Id compartilhado.
• O InvokeAgent span é a raiz do rastreamento; os spans ExecuteTool e OutputMessages ficam aninhados abaixo dele por meio de operation_ParentId.
• Agrupe por gen_ai.conversation.id para encadear várias interações da mesma conversa e divida esse ID em _ para incluir rastros de subagentes.

Lâminas de agentes (prévia)

Além dos Logs, o Application Insights oferece visualizações integradas de Agentes (prévia) que visualizam a telemetria GenAI exportada sem precisar escrever consultas Kusto. À medida que o Copilot Studio escreve seus intervalos na dependencies tabela, essas pás leem diretamente desses dados:

• Execuções do agente: Lista as invocações do agente geradas a partir dos spans InvokeAgent, com sua duração, êxito e a conversa à qual cada execução pertence. Algumas limitações se aplicam; saiba mais em Limitações e considerações conhecidas.
• Ferramentas: Agrega os ExecuteTool intervalos para mostrar quais ferramentas os agentes chamam, com que frequência e como eles atuam.
• Modelos: Resume o uso dos modelos entre execuções, destacando os modelos invocados e seus padrões de chamada.

Analise a telemetria de agentes com o Application Insights

Depois que você conecta seu ambiente ao Application Insights, ele registra os dados de telemetria do agente quando os usuários interagem com o agente, inclusive durante os testes dentro do Copilot Studio. Para visualizar os dados de telemetria registrados, acesse a seção Logs do seu recurso Application Insights no Azure. Aqui, você pode usar consultas Kusto para consultar e analisar seus dados. Saiba mais em Exemplos de consultas.

Consultas de exemplo

Os exemplos de consultas Kusto a seguir reconstituem as conversas dos agentes do Copilot Studio a partir da tabela dependencies no Application Insights. Como cada span compartilha um rastreamento operation_Id em cada turno, as consultas ordenam os spans da raiz para os filhos (o span InvokeAgent antes dos spans filhos) dentro de cada rastreamento.

Consulta 1: Retorne um rastreamento completo de um ID de conversa específico

Esta consulta retorna todos os spans de uma conversa específica conhecida, ordenados cronologicamente, com cada span raiz listado antes de seus spans filhos. Substitua o marcador ID da conversa pelo ID da conversa do seu agente. Você pode encontrá-lo digitando o seguinte comando enquanto testa seu agente personalizado: /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

Consulta 2: Devolver a última conversa de um agente específico

Essa consulta encontra a conversa mais recente para um agente nomeado dentro do intervalo de tempo especificado. Ele retorna todos os intervalos dessa conversa na mesma ordem cronológica, raíz primeiro. Substitua o nome do agente provisório pelo nome do seu agente.

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

Consulta 3: Expandir propriedades conhecidas do OpenTelemetry genAI para colunas

Essa consulta retorna o mesmo rastreio que a consulta 2, mas também analisa cada chave conhecida da convenção semântica do OpenTelemetry em sua própria coluna nomeada. O resultado é uma tabela plana e explicitamente definida, onde você pode ordenar, filtrar e escanear os campos de IA generativa, como nome da ferramenta, modelo, prompt do usuário, resposta do agente e ID de conversa diretamente. Substitua o nome do agente provisório pelo nome do seu agente.

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

Consulta 4: Expandir dinamicamente todas as propriedades do OpenTelemetry genAI

Esta consulta retorna as mesmas abrangências que a consulta 3, mas cada chave gen_ai.* é desempacotada dinamicamente de customDimensions em sua própria coluna com prefixo ga_. Como a projeção é dinâmica, qualquer novo gen_ai.* atributo que o SDK emite depois aparece automaticamente sem alterar a consulta. Substitua o nome do agente provisório pelo nome do seu agente.

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_')

Consulta 5: Devolver a conversa mais recente de um agente raiz com todos os seus filhos, incluindo subagentes

Esta consulta retorna a conversa mais recente de um agente específico. Retorna todos os spans dessa conversa e de todos os subagentes de primeiro nível que ela invocou. Quando um agente chama outro agente como uma ferramenta, o subagente herda o ID de conversa do pai com um _<subConversationId> sufixo. Toda a árvore é reconstruída com base na correspondência do ID de nível superior. Substitua o nome do agente provisório pelo nome do seu agente.

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

Limitações e considerações conhecidas

• O duration valor não está disponível para vestígios de agentes alimentados pelo chicote padrão.
• Atualmente, os erros na execução de agentes e ferramentas não são refletidos corretamente nos status de rastreamento.
• Com base nos requisitos de residência de dados, talvez você queira usar recursos dedicados de Application Insights para cada região do ambiente.
• Os spans de subagentes atualmente têm como pai o span InvokeAgent que invocou o agente, em vez do span InvokeAgent dentro do seu próprio trace.
• Os IDs de rastreamento e de span atualmente são emitidos como GUIDs (com prefixo quando necessário), em vez de usar o formato totalmente alinhado ao padrão OpenTelemetry, com ID de rastreamento de 32 caracteres hexadecimais e ID de span de 16 caracteres hexadecimais.
• Certifique-se de que a autenticação local esteja ativada no recurso alvo Application Insights.
• A exportação de telemetria não é transacional. Durante eventos de serviço transitório, pequenas quantidades de perda de dados podem ocorrer.
• Podem ocorrer inconsistências nos dados à medida que atualizações de ingestão relacionadas ao esquema são implementadas.
• Eventos relacionados a tópicos como TopicStart, TopicAction, e TopicEnd não são capturados com telemetria em nível ambiental.
• Para simplificar relatórios e solução de problemas, evite enviar telemetria tanto em nível de agente quanto em nível de ambiente para a mesma instância do Application Insights.
• A telemetria emitida para agentes criados na experiência de criação de agentes com tecnologia do harness do GitHub Copilot pode diferir da telemetria dos agentes criados na experiência de criação de agentes com tecnologia do harness padrão.

Informações relacionadas

• Visão geral da telemetria com Application Insights
• Telemetria em nível de agente com Application Insights
• Exportar dados para o Application Insights
• Aplicativo Azure Insights