Eventos de telemetria para o Microsoft Dataverse

O fluxo de dados fornece atualmente dados de desempenho relacionados com chamadas de entrada à API do Dataverse, chamadas de execução de plug-ins do Dataverse e chamadas SDK do Dataverse. Também fornece dados para falhas nas operações de plug-in e SDK Dataverse.

Chamada de entrada de API do Dataverse

São chamadas feitas para a API do Dataverse. Podem ser da Interface Unificada (UCI), do cliente Web legado, clientes personalizados que usam o SDK, e assim por diante. Podem ser encontradas na tabela de pedidos do Application Insights, que tem os seguintes campos.

• Nome: o tipo de pedido. Estes enquadram-se em duas categorias:

  • Pedido da API Web: um pedido ao ponto final OData v4 que é normalmente utilizado pela Interface Unificada e clientes modernos. Este pedido é transformado numa operação comum a ambos. A API Web é um "invólucro" para ativar o modelo de programação RESTful, mas depois de os dados serem recebidos, tudo se torna o mesmo dentro do servidor. Quando a resposta é obtida, é convertida para JSON se o pedido veio da API Web.
  • Pedido de Serviço da Organização: um pedido ao Ponto Final de API da Organização utilizado por clientes SDK ou pelo cliente Web antigo.

• Duração: o tempo que o servidor demorou a responder ao pedido.

• URL: o URL para o qual a chamada foi feita.

• CustomDimensions:

  • UserAgent: o Application Insights preenche automaticamente o campo de agente do utilizador com PC, uma vez que estes registos estão a ser empurrados de um servidor num datacenter. O Application Insights não permite que o campo do agente do utilizador seja substituído. Às vezes, o campo de agente do utilizador não está disponível para preencher. O agente do utilizador a partir do qual a chamada foi feita pode ser visto utilizando a seguinte consulta:

    requests
    | summarize count() by tostring(customDimensions.userAgent)
    

    

• Operation_Name: o nome legível da operação a apresentar em vistas, tais como a vista de transações de ponto a ponto.

Registos de execução de plug-in do Dataverse

Estes registos para plug-ins personalizados em execução para uma determinada operação encontram-se na tabela de dependência. Segue-se uma consulta de exemplo:

dependencies
| where type == "Plugin"
| take 100

• Nome/Destino: o nome de tipo totalmente qualificado para o plug-in a ser executado.
• Duração: o tempo que o plug-in demorou a ser executado.
• CustomDimensions:
  • Profundidade: a profundidade atual da execução na pilha de chamadas.
  • EntityName: o nome da entidade a ser trabalhada pelo plug-in.
  • IsolationType: um valor que indica se o plug-in está a ser executado no sandbox:
    • 1: nenhuma
    • 2: sandbox
    • 3: externa
  • PluginName: o nome amigável de utilizador do plug-in.
  • PluginType: o nome do tipo de plug-in a ser executado.
  • PluginVersion: a versão do plug-in publicado. A intenção aqui é poder usar esta informação para resolver as atualizações da versão.
  • Fase: mapeia para os seguintes valores:
    • PreValidation = 10
    • PreOperation = 20
    • PreOperationBeforeExternalPlugins = 15
    • PreOperationAfterExternalPlugins = 25
    • MainOperation = 30
    • PostOperationBeforeExternalPlugins = 35
    • PostOperationAfterExternalPlugins = 45
    • PostOperation = 40
    • PostOperationDeprecated = 50
  • StepName: o nome do passo de Processamento de Mensagens SDK. Isto é geralmente gerado pela ferramenta Registo de Plug-ins utilizando informações sobre o PluginName, PluginType e o nome da operação, por exemplo, ErrorMessageTest.ThrowException: Criação de conta.

Telemetria dentro do seu código de plug-in

Para compreender o que está a acontecer dentro do seu código de plug-in, pode incluir telemetria personalizada a partir do seu plug-in utilizando o Microsoft.Xrm.Sdk.PluginTelemetry.ILogger Interface no seu código de plug-in para escrever dados telemétricos diretamente para o seu recurso do Application Insights. Mais informações: Escrever Telemetria para o seu recurso do Application Insights utilizando o ILogger (Pré-visualização)

Registos SDK do Dataverse

Estes são registos para operações SDK acionadas como parte de um pedido de entrada. Estes são registados na tabela de dependência no Application Insights porque são monitorizados como dependências para o pedido de execução. São identificados pelo tipo de nome, a começar por SDK. Segue-se uma consulta de exemplo:

dependencies
| where type startswith "SDK"
| take 10

• Tipo: o tipo de conteúdo do pedido SDK acionado. Exemplos incluem Retrieve, RetrieveMultiple, FetchXmlToQueryExpression e WhoAmI.
• Nome/Destino: este é o nome da entidade visada pela operação SDK.
• CustomDimensions:
  • ClientType: o tipo de cliente de onde vem a chamada. Alguns valores possíveis são Web, UCIClient e OutlookFull.
  • EntityId: o identificador exclusivo da entidade que está a ser utilizada.
  • EntityName: o nome da entidade a ser utilizado.

Exceções

Verá detalhes de falhas nas operações de plug-in e SDK no Application Insights. A tabela de exceções no Application Insights alimenta o painel Falhas. Estes detalhes de falha correlacionam-se com o resto dos eventos no plug-in e chamadas SDK na vista de ponto a ponto. Toda as informações disponíveis são adicionada às colunas quando possível e a customDimensions quando não há correspondência de colunas exata.

Vai notar que alguns dos campos na tabela de exceções não são preenchidos. Isto porque estes campos só podem ser definidos se a SDK do Application Insights for utilizada para emitir registos da origem. Esta funcionalidade recolhe telemetria da plataforma e, em seguida, empurra-a para o Application Insights, de acordo com o esquema do Application Insights.

exceptions
| take 10

Esta consulta obterá todos os detalhes do atributo da tabela de exceções.

• problemId/type: o tipo de exceção.
• outerMessage: a mensagem da exceção.
• customDimensions:
  • clientType: o tipo de cliente de onde vem a chamada. Alguns valores possíveis são Web, UCIClient e OutlookFull.
  • exceptionSource: o plug-in ou ponto onde a exceção foi lançada.
  • entityName: o nome da entidade a ser utilizado.
  • pluginName: o nome do plug-in onde foi lançada a exceção.

Se um utilizador reportar um erro, pode utilizar o ID de utilizador (ID do Microsoft Entra) para compreender os detalhes da tabela de exceções.

exceptions
| where user_Id == '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'

O ID da entidade e o nome da entidade estão disponíveis em customDimensions na tabela de dependência.

dependencies
| where type == "SDK Retrieve"

Perguntas Frequentes (FAQs)

Seguem-se algumas perguntas frequentes relacionadas com eventos de telemetria para o Dataverse.

Como posso determinar se a minha atualização de versão de plug-in causou uma degradação de desempenho?

dependencies
| where ['type'] == "Plugin"
| where name startswith "[InsertYourPluginName]"
| summarize avg(duration) by name

O nome plug-in também deve conter a versão para plug-ins personalizados.

Como é que a API se apresentava antes de um problema reportado, com base na hora do dia ou no local? A degradação da API foi gradual ou repentina?

requests
| where url == "https://<URLHere>"
| summarize avg(duration), count() by bin(timestamp, 1h)
| render timechart 

Neste gráfico, podemos ver o desempenho do ponto final da API ao longo de um período de tempo contra o número de pedidos que estão a ser feitos.

Também pode configurar um alerta com base no desempenho de uma determinada API aqui dentro do Application Insights.

Posso desagregar erros ou falhas em momentos específicos ou para utilizadores específicos para permitir a compreensão da pilha de chamadas?

Ver o painel Falhas fornece uma descrição geral das falhas num determinado período de tempo. Em seguida, pode reduzir a uma falha específica baseada na chamada à API ou tipo de dependência para ver a vista de ponto a ponto.

Posso criar dashboards personalizados?

Sim. Pode criar dashboards personalizados com o Application Insights.

Posso determinar o desempenho do utilização de plug-ins (tempo de resposta) e as taxas de falhas durante o pico de utilização?

Sim. Consulte a seguinte consulta de exemplo para entender como os seus plug-ins funcionam.

dependencies
| where ['type'] == "Plugin"
| where name == "[Plugin name here]"
| summarize avg(duration) by bin(timestamp, 1h)
| render timechart

Esta telemetria vai ter limitação?

Sim. Os detalhes de erro 429 básico são fornecidos atualmente.

Posso entender os caminhos de execução? As chamadas efetuadas pelo plug-in estão a abrandar o plug-in?

Sim. Pode ver todas as mensagens e plug-ins que são executados para qualquer pedido.

A duração de toda a mensagem e execução de plug-ins é registada. Se algum plug-in estiver a demorar mais tempo, pode identificar o plug-in. Se o plug-in estiver a fazer uma chamada de retorno para o Dataverse, a duração dessa chamada é registada. Estão previstas mais informações sobre os plug-ins para futuras implementações.

Qualquer chamada de saída feita pelo plug-in será automaticamente registada como uma dependência.

Posso ver a telemetria para um pedido específico?

O Dataverse obtém x-ms-service-requestId na resposta do cabeçalho a todos os pedidos. Utilizando este requestId, pode consultar toda a telemetria.

union *
| where operation_ParentId contains <requestId>