Telemetria em nível de agente com Application Insights

Este artigo explica como capturar dados de telemetria em nível de agente do Copilot Studio da plataforma da estrutura padrão para uso no Aplicativo Azure Insights.

Conectar seu agente do Copilot Studio ao Application Insights

Para conectar seu agente ao Application Insights, primeiro adicione sua chave de instrumentação à configuração do agente.

  1. Acesse a página Configurações de seu agente e selecione Avançado.

  2. Na seção Application Insights , insira a cadeia de conexão. Para saber como localizar seu cadeia de conexão, consulte a documentação Azure Monitor.

  3. Opcionalmente, você pode habilitar uma das seguintes configurações.

    • Habilitar o registro em log: se ativado, o sistema registra detalhes de mensagens e eventos de entrada e saída.

    • Detalhes da conversa de log: inclui ID do usuário, nome de usuário e texto da mensagem (para atividades de mensagem). Quando o rastreamento OpenTelemetry está habilitado, essa configuração também controla os argumentos de entrada da ferramenta e os resultados de saída da ferramenta capturados em intervalos.

    • Registrar propriedades de atividade confidenciais: se ativada, os logs incluirão os valores de determinadas propriedades que poderiam ser consideradas confidenciais em mensagens de entrada e saída e em eventos.

    • Eventos de execução de nó: registra um evento cada vez que um nó dentro de um tópico é executado.

Analisar telemetria de bot com o Application Insights

Depois que você conecta seu agente ao Application Insights, ele registra os dados de telemetria 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 consultas de exemplo.

Consultas de exemplo

Uma consulta pode ser tão simples quanto especificar uma única tabela, como customEvents, que mostra todos os eventos de telemetria personalizados registrados no Copilot Studio. Mas você também pode usar consultas Kusto para restringir ainda mais seus resultados, incluindo:

  • Adicionar um intervalo de tempo
  • Estendendo seus resultados usando dimensões personalizadas. Dimensões personalizadas são propriedades personalizadas que você registra junto com os campos predefinidos, como o carimbo de data/hora ou o nome do evento
  • Adicionando uma cláusula where para limitar os dados retornados com base em uma condição
  • Usando mais funções internas do Kusto para determinar quais informações são exibidas e como

A consulta de exemplo a seguir resulta em um gráfico de linhas que mostra quantos usuários distintos se comunicaram com seu bot por dia nos últimos 14 dias.

let queryStartDate = ago(14d);
let queryEndDate = now();
let groupByInterval = 1d;
customEvents
| where timestamp > queryStartDate
| where timestamp < queryEndDate
| summarize uc=dcount(user_Id) by bin(timestamp, groupByInterval)
| render timechart

Importante

Os dados dentro de alguns campos variam e são mais ou menos aplicáveis, dependendo do canal que está sendo usado. Por exemplo, você só obterá uma contagem correta de usuários exclusivos na consulta se os usuários forem autenticados e suas IDs de usuário forem consistentes entre conversas. Em cenários anônimos em que uma ID de usuário aleatória é gerada em cada conversa, o campo ID do usuário é menos útil.

Excluir a telemetria de conversas de teste em suas consultas

O bot registra a telemetria de todas as conversas, incluindo aquelas que ocorrem no Copilot Studio durante o teste. Se você quiser excluir a telemetria coletada durante o teste, estenda sua consulta usando a designMode dimensão personalizada que todos os eventos capturam e use uma cláusula where em sua consulta.

O exemplo a seguir mostra todos os eventos personalizados, excluindo aqueles capturados por meio da tela de teste.

customEvents
| extend isDesignMode = customDimensions['designMode']
| where isDesignMode == "False"

Dimensões Personalizadas

Grande parte dos dados de atividade específicos recebidos do Copilot Studio é armazenado no campo customDimensions. Você pode ver um campo de dimensão personalizada sendo usado em uma consulta para excluir a telemetria das conversas de teste.

Campo Description Valores de exemplo
tipo Tipo de atividade message, conversationUpdate, event, invoke
ID do canal Identificador do canal emulator, directline, msteams, webchat
fromId Identificador De <id>
fromName Nome de usuário do cliente John Bonham, Keith Moon, Steve Smith, Steve Gadd
localidade Localidade de origem do cliente en-us, zh-cn, en-GB, de-de, zh-CN
recipientId Identificador do destinatário <id>
recipientName Nome do destinatário John Bonham, Keith Moon, Steve Smith, Steve Gadd
enviar SMS Texto na mensagem find a coffee shop
designMode A conversa aconteceu dentro da tela de teste True / False

Veja os resultados do monitoramento (prévia)

Importante

Este artigo contém a documentação da versão preliminar do Microsoft Copilot Studio e está sujeito a alterações.

As funcionalidades de pré-visualização não se destinam à utilização de produção e podem ter funcionalidades restritas. Esses recursos estão disponíveis antes de um lançamento oficial para que você possa obter acesso antecipado e fornecer comentários.

Se você estiver criando um agente pronto para produção, confira a visão geral do Microsoft Copilot Studio.

A exibição do dashboard Copilot Studio usa sinais do Azure Monitor Application Insights. Ele consulta o Application Insights por meio de pastas de trabalho Azure e cria visualizações.

Essas exibições trazem as principais métricas, como total de conversas, latência, exceções, uso de ferramentas e análise de tópicos, em uma única exibição. A exibição única fornece às equipes transparência para que elas possam acompanhar a integridade e a qualidade operacionais, entender tendências e avaliar continuamente para melhorar a aplicação.

Para acessar e usar o modo de exibição de monitoramento interno no Application Insights, siga estas etapas:

  1. Acesse seu recurso do Application Insights.
  2. Selecione a guia Monitoramento no painel de navegação esquerdo.
  3. Na guia Monitoramento , selecione Pastas de Trabalho. Abra o Painel Copilot Studio na galeria de pastas de trabalho.

Captura de tela da galeria de pastas de trabalho do Application Insights.

Captura de tela da pasta de trabalho do Copilot Studio.

Personalizar e compartilhar seu painel

O Application Insights é uma ferramenta poderosa para o APM (monitoramento de desempenho de aplicativos) que fornece insights sobre a integridade e o desempenho de seus aplicativos.

O painel é aberto como uma pasta de trabalho editável em que você pode personalizar a pasta de trabalho e salvá-la de acordo com suas necessidades.

  1. Selecione Editar na barra de comandos.

    Captura de tela ao editar o workbook do Application Insights.

  2. Modifique os elementos conforme necessário para seu caso de uso. Selecione os três pontos (...) para que um elemento possa editar, adicionar, mover ou redimensionar, clonar ou removê-lo. Por exemplo, você pode adicionar um bloco que usa KQL para rastrear um atributo personalizado que você está coletando e que a visualização integrada não mostra.

    Captura de tela da modificação de um elemento no Workbook do Application Insights.

  3. Selecione Salvar para salvar suas alterações mais recentes e criar exibições diferentes conforme necessário.

    Captura de tela de gravação da pasta de trabalho do Application Insights.

  4. Selecione o ícone Compartilhar na barra de comandos para compartilhar com sua equipe.

    Note

    Quando você compartilha a pasta de trabalho com os membros da equipe, eles devem ter, pelo menos, a função de Leitor para o recurso do Application Insights conectado para exibir as informações.

    Captura de tela do compartilhamento do caderno do Application Insights.

Desativar a telemetria Application Insights em nível de agente

Para evitar que os criadores habilitem a telemetria do Application Insights no nível do agente, bloqueie o conector Application Insights no Copilot Studio por meio de uma política de dados no centro de administração do Power Platform.

Antes de começar, verifique se você tem:

  • Função de administrador da Power Platform ou de administrador do Dynamics 365 no nível do locatário no Microsoft Entra ID.
  • Acesso ao ambiente alvo onde os agentes do Copilot Studio são implantados.

Para desabilitar a telemetria Application Insights em nível de agente, siga estes passos:

  1. No centro de administração do Power Platform, selecione Segurança no painel esquerdo, selecione Dados e privacidade, e então selecione Política de dados.
  2. Crie uma nova política de dados ou edite uma política existente.
  3. Selecione os ambientes aos quais a política deve ser aplicada e selecione Adicionar à política.
  4. Na etapa Conectores (nova política) ou Conectores Pré-construídos (política existente), pesquise por Application Insights no Copilot Studio e selecione-o.
  5. Selecione Block para mover Application Insights do Copilot Studio para o grupo de conectores Blocked.
  6. Conclua as etapas restantes da configuração da política e publique a política.

Note

O conector pode aparecer na lista de conectores integrados da Microsoft como Application Insights in Copilot Studio.

Quando a política de dados é aplicada, o conector Application Insights no Copilot Studio é bloqueado nos ambientes de destino. Usuários e criadores não podem usar esse conector em ambientes regidos pela política.

  • Last updated on