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 como extensões. Cada evento exportado (InvokeAgent, ExecuteTool e OutputMessages) é uma única linha de span (itemType = dependency).

Como extensões formam um rastreamento

A telemetria segue o modelo de rastreamento e extensão do OpenTelemetry, reconstruídos 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.
• A extensão InvokeAgent é a raiz do rastreamento da rodada. As extensões ExecuteTool e as extensões OutputMessages conectadas se aninham abaixo, cada uma transportando operation_ParentId = a extensão de InvokeAgentid.
• Uma conversa se estende por várias rodadas, cada uma sendo emitida como um rastreamento à parte. Agrupe ou filtre por gen_ai.conversation.id para thread dos turnos de uma conversa juntas.
• As extensões OutputMessages nem sempre emitem uma raiz InvokeAgent, o que significa que podem (por projeto) chegar sem um pai correspondente e aparecer como um rastreamento independente, rastreamento de nó único.

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:

• As extensões de agente aparecem na tabela dependencies.
• As extensões 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 rodada do agente é um rastreamento, agrupado por um operation_Id compartilhado.
• A extensão InvokeAgent é a raiz do rastreamento; as extensões ExecuteTool e OutputMessages são aninhadas abaixo dela por meio de operation_ParentId.
• Agrupe por gen_ai.conversation.id para encadear várias rodadas da mesma conversa e divida essa ID em _ para incluir rastreamentos de subagente.

Painéis de agentes (versão preliminar)

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 grava as extensões na tabela dependencies, esses painéis leem diretamente com base nesses 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 extensão compartilha um rastreamento operation_Id por rodada, as consultas ordenam as extensões da raiz inicial (a extensão InvokeAgent antes das extensões filho) dentro de cada rastreamento.

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

Esta consulta retorna todas as extensões de uma conversa conhecida, ordenadas cronologicamente, com cada extensão raiz listada antes das extensões filho. 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. Ela retorna todas as extensões dessa conversa na mesma ordem cronológica, ordem raiz principal. 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 do OpenTelemetry genAI conhecidas 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 extensões da consulta 3, mas cada chave gen_ai.* é desempacotada dinamicamente de customDimensions para a própria coluna prefixada 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_')

Limitações e considerações conhecidas

• Esse recurso não oferece suporte a cenários de configuração não autenticada ou de configuração de agente multilocatário. Portanto, o Application Insights não os registra.
• Esse recurso está atualmente disponível apenas em ambientes de nuvem pública da Microsoft.
• Para certos cenários de agentes conectados, a relação pai-filho entre os traços não é mapeada corretamente.
• O valor duration não está disponível para rastreamentos de agentes da plataforma de harness padrão.
• Certifique-se de ativar a propriedade de autenticação local no recurso de 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.
• Esse recurso não captura eventos relacionados ao tema, como TopicStart, TopicAction, e TopicEnd.
• Os IDs de trace e de span atualmente usam uma representação baseada em GUID em vez dos formatos hexadecimais padronizados pelo OpenTelemetry: ID de trace de 32 caracteres e ID de span de 16 caracteres.
• 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 pode variar entre agentes alimentados pelo chicote GitHub Copilot e agentes alimentados pelo chicote padrão.
• Garanta que sua configuração do Application Insights em nível ambiente atenda aos requisitos de residência de dados, privacidade e controle de acesso baseado em funções (RBAC).
• Grandes conteúdos de log, incluindo respostas de agentes e argumentos de ferramentas, podem ser truncados.

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