Partilhar via

Eventos de telemetria para o Microsoft Dataverse

  • Artigo

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 solicitação. Estes enquadram-se em duas categorias:

    • Solicitação de API da Web: uma solicitação para o ponto final OData v4 que é comumente usada por clientes Interface Unificada e 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.
    • Solicitação de serviço da organização: uma solicitação para a API da organização ponto final usada por clientes SDK ou pelo cliente Web herdado.

  • Duração: O tempo que o servidor levou para responder à solicitação.

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

  • Dimensões personalizadas:

    • UserAgent: Application Insights preenche automaticamente o campo do agente do utente com o PC à medida que esses logs são enviados por push de um servidor em um 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)

      Application Insights CustomDimensions UserAgent.

  • Operation_Name: O nome legível da operação a ser exibida em modos de exibição, como o modo de exibição de transação de ponta a ponta.

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

Registos de execução de plug-in do Dataverse no Application Insights.

  • Nome/Destino: O nome de tipo totalmente qualificado para o plug-in que está a ser executado.
  • Duração: o tempo necessário para a execução do plug-in.
  • Dimensões personalizadas:
    • Profundidade: A profundidade atual da execução na pilha de chamadas.
    • EntityName: O nome da entidade que está a ser acionada pelo plug-in.
    • IsolationType: um valor que indica se o plug-in está a ser executado na área restrita:
      • 1: nenhuma
      • 2: sandbox
      • 3: externa
    • PluginName: O nome amigável do plug-in.
    • PluginType: O nome do tipo de plug-in que está 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.
    • Estágio: 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 do 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 entender o que está a acontecer no código do plug-in, você pode incluir a telemetria personalizada de dentro do plug-in usando o Microsoft. Interface Xrm.Sdk.PluginTelemetry.ILogger no seu código de plug-in para escrever dados de telemetria diretamente no seu Application Insights recurso. 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

SDK de consulta do Application Insights.

  • Tipo: O tipo de solicitação SDK acionada. Exemplos incluem Retrieve, RetrieveMultiple, FetchXmlToQueryExpression e WhoAmI.
  • Nome/Destino: Este é o nome da entidade que está a ser alvo da operação SDK.
  • Dimensões personalizadas:
    • ClientType: O tipo de cliente de onde a chamada está a vir. Alguns valores possíveis são Web, UCIClient e OutlookFull.
    • EntityId: O identificador exclusivo da entidade que está a ser usada.
    • EntityName: O nome da entidade que está a ser usada.

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.

Tabela de exceções 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 de exceção.
  • customDimensions:
    • clientType: O tipo de cliente de onde a chamada está a vir. 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 que está a ser usada.
    • pluginName: O nome do plug-in onde a exceção foi lançada.

Detalhes de atributos da tabela de exceções do Application Insights.

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"

Consulta de obtenção de SDK do Application Insights.

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

Gráfico de hora do desempenho de API do Application Insights.

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.

Detalhes da falha do Application Insights.

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

Desempenho de utilização de plug-ins.

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.

Transação de ponto a ponto.

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>