Telemetria ao nível do ambiente com Application Insights (pré-visualização)

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

Use o Aplicação Azure Insights para monitorizar os rastreios de agentes do Copilot Studio exportados a partir de um ambiente gerido. Depois de configurar a exportação, use o Azure Monitor e o Application Insights para validar execuções de agentes, monitorizar 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 ao nível do ambiente dos rastros do agente Copilot Studio para o Aplicação Azure Insights através do centro de administração do Power Platform.

Pré-requisitos

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

O que é exportado

Quando ativas a exportação, a telemetria de rastreamento do agente do Copilot Studio é escrita para o Application Insights num formato de observabilidade orientado para traços e alinhado com o OpenTelemetry, que suporta investigação, dashboards e alertas.

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

Como os spans formam um rastreio

A telemetria segue o modelo trace-and-span do OpenTelemetry, reconstruída a partir das colunas operation_Id e operation_ParentId:

• Cada turno do agente é o seu próprio rastreio, identificado por um operation_Id partilhado que permite ao Application Insights agrupar o turno e compô-lo na vista de transação ponto a ponto.
• O span InvokeAgent é a raiz do rastreio do seu turno. Os spans ExecuteTool e os spans OutputMessages ligados ficam aninhados por baixo dele, cada um contendo operation_ParentId = o id do span InvokeAgent.
• Uma conversação abrange vários turnos, cada um emitido como um rastreio separado. Agrupe ou filtre por gen_ai.conversation.id para voltar a encadear os turnos de uma mesma conversação.
• Os spans OutputMessages nem sempre emitem uma raiz InvokeAgent, o que significa que podem (por design) chegar sem um elemento principal correspondente e aparecer como um rastreio autónomo 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 guardar a configuração de exportação, execute uma conversa de teste com o agente e confirme que a telemetria chega ao Application Insights. A entrega de telemetria pode demorar até 24 horas em novas configurações. Valide isso:

• Os spans de agentes são apresentados na tabela dependencies.
• Os spans InvokeAgent, ExecuteTool e OutputMessages de cada turno partilham um operation_Id.

Campos do Application Insights

A tabela seguinte mostra os campos na dependencies tabela e quais os campos 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 JSON customDimensions. A tabela seguinte mostra as chaves comuns que aparecem em cada span:

Chaves específicas de eventos

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

Descubra o esquema atual

O esquema documentado neste artigo poderá evoluir ao longo do tempo. Em vez de confiar apenas nas tabelas mencionadas anteriormente, utilize as seguintes consultas para inspecionar o esquema mais recente disponível no seu próprio ambiente.

Listar colunas de tabela nativas

A consulta seguinte devolve o esquema ao nível da 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

Descobre chaves customDimensions (propriedades dinâmicas)

A consulta seguinte lista todas as chaves dentro do customDimensions JSON na dependencies tabela: o nome da propriedade, em que eventos do agente aparece (InvokeAgent, ExecuteTool, OutputMessages), e um valor de exemplo. Ao contrário do esquema de colunas nativo, estas propriedades são dinâmicas, pelo que esta consulta mantém-se precisa à medida que o SDK adiciona novas gen_ai.* ou outras chaves. Usa-o como fonte viva de verdade para os 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

Monitorizar telemetria exportada

Utilize os Logs do Application Insights para consultar a atividade do agente e investigar a execução de agentes ou ferramentas. Toda a telemetria exportada é registada na tabela dependencies como spans:

• Cada turno de agente é um rastreio, agrupado por um operation_Id partilhado.
• O span InvokeAgent é a raiz do rastreio; os spans ExecuteTool e OutputMessages ficam aninhados abaixo dele através de operation_ParentId.
• Agrupe por gen_ai.conversation.id para encadear vários turnos da mesma conversação e divida esse ID em _ para incluir rastreios de subagentes.

Painéis de agentes (pré-visualização)

Para além dos Logs, o Application Insights fornece vistas incorporadas de Agentes (pré-visualização) que visualizam a telemetria GenAI exportada sem escrever consultas Kusto. À medida que o Copilot Studio escreve os seus spans na tabela dependencies, estes painéis leem diretamente esses dados:

• Execuções do agente: Lista as invocações do agente criadas a partir dos segmentos InvokeAgent, com a respetiva duração, êxito e a conversa à qual cada execução pertence. Aplicam-se algumas limitações; Saiba mais em Limitações e considerações conhecidas.
• Ferramentas: Agrega os ExecuteTool intervalos para mostrar quais as ferramentas que os agentes utilizam, com que frequência e qual o seu desempenho.
• Modelos: Resume a utilização dos modelos ao longo das execuções, destacando os modelos invocados e os seus padrões de chamada.

Analise a telemetria dos agentes com o Application Insights

Depois de ligar o seu ambiente ao Application Insights, ele regista os dados de telemetria do agente quando os utilizadores interagem com o agente, incluindo durante os testes dentro do Copilot Studio. Para visualizar os dados de telemetria registados, aceda à secção Logs do seu recurso Application Insights no Azure. Aqui, pode usar consultas Kusto para consultar e analisar os seus dados. Saiba mais em Exemplos de consultas.

Exemplos de consultas

Os exemplos seguintes de consultas Kusto reconstituem as conversas de agente do Copilot Studio a partir da tabela dependencies no Application Insights. Como cada span partilha um operation_Id de rastreio por turno, as consultas ordenam os spans começando pela raiz (o span InvokeAgent antes dos respetivos spans de elementos subordinados) dentro de cada rastreio.

Consulta 1: Devolver um rastreio completo para um ID de conversação específico

Esta consulta devolve todos os spans de uma conversação conhecida, ordenados cronologicamente, com cada span raiz listado antes dos seus spans de elementos subordinados. Substitua o marcador de posição ID da conversa pelo ID da conversa do seu agente. Pode encontrá-lo introduzindo o seguinte comando enquanto testa o 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

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

Esta consulta encontra a conversa mais recente de um agente nomeado dentro da janela de tempo especificada. Devolve todos os spans dessa conversação na mesma ordem cronológica, começando pela raiz. 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 as propriedades genAI conhecidas do OpenTelemetry em colunas

Esta consulta devolve o mesmo rasto que a consulta 2, mas também processa cada chave conhecida da convenção semântica do OpenTelemetry numa coluna com nome próprio. O resultado é uma tabela plana e explicitamente definida onde pode ordenar, filtrar e analisar diretamente os campos de IA generativa, como nome da ferramenta, modelo, prompt do utilizador, resposta do agente e ID de conversa. 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 de genAI do OpenTelemetry

Esta consulta devolve os mesmos intervalos que a consulta 3, mas cada chave gen_ai.* é descompactada dinamicamente de customDimensions para a sua própria coluna com o prefixo ga_. Como a projeção é dinâmica, qualquer novo gen_ai.* atributo que o SDK emita posteriormente 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

• Esta funcionalidade não suporta cenários de agentes não autenticados ou de configuração de agente multi-inquilino. Por isso, o Application Insights não os regista.
• Esta funcionalidade está atualmente disponível apenas em ambientes de cloud pública da Microsoft.
• Para certos cenários de agentes conectados, a relação pai-filho entre rastreios não está corretamente mapeada.
• O valor duration não está disponível para rastreios de agentes com tecnologia da plataforma standard.
• Certifique-se de ativar a propriedade de autenticação local no recurso de Insights de Aplicação de destino.
• A exportação de telemetria não é transacional. Durante eventos de serviço transitório, podem ocorrer pequenas quantidades de perda de dados.
• Podem ocorrer inconsistências nos dados à medida que as atualizações de ingestão relacionadas com o esquema são implementadas.
• Esta funcionalidade não capta eventos relacionados com temas, como TopicStart, TopicAction, e TopicEnd.
• Atualmente, os IDs de trace e de span utilizam uma representação baseada em GUID, em vez dos formatos hexadecimais padrão do OpenTelemetry: ID de trace com 32 caracteres e ID de span com 16 caracteres.
• Para simplificar a reporte e a resolução de problemas, evite enviar telemetria tanto ao nível do agente como ao nível do 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.
• Assegure que a sua configuração de Application Insights ao nível do ambiente cumpre os requisitos de residência de dados, privacidade e controlo de acesso baseado em funções (RBAC).
• Grandes conteúdos de registo, incluindo respostas de agentes e argumentos de ferramentas, podem ser truncados.

Informações relacionadas

• Descrição geral da telemetria com Application Insights
• Telemetria ao nível do agente com Application Insights
• Exportar dados para o Application Insights
• Aplicação Azure Insights