Microsoft Dataverse 的遥测事件

数据流目前提供与 Dataverse API 传入调用、Dataverse 插件执行调用和 Dataverse SDK 调用有关的性能数据。 还提供插件和 Dataverse SDK 操作中的失败的数据。

Dataverse API 传入调用

这些是对 Dataverse API 进行的调用。 它们可以来自统一接口 (UCI)、旧版 Web 客户端、使用 SDK 的自定义客户端等。 它们可以在 Application Insights 的请求表中找到，其中包含以下字段。

• Name：请求的类型。 分为两类：

  • Web API Request：对统一接口和现代客户端常用的 OData v4终结点的请求。 这种请求将转换为两种通用的操作。 Web API 是一种“包装器”，用于启用 RESTful 编程模型，但是收到数据后，所有内容在服务器内都将变得相同。 如果请求来自 Web API，返回了响应时，该响应将转换为 JSON。
  • 组织服务请求：对 SDK 客户端或旧 Web 客户端使用的组织 API 终结点的请求。

• Duration：服务器响应请求所用时间量。

• Url：调用针对的 URL。

• CustomDimensions：

  • UserAgent：Application Insights 使用 PC 自动填充用户代理字段，因为正在从数据中心中的某个服务器推送这些日志。 Application Insights 不允许覆盖用户代理字段。 有时不能填充用户代理字段。 可以使用以下查询查看进行调用的用户代理：

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

    

• Operation_Name：要在视图（如端到端事务视图）中显示的操作的可读名称。

Dataverse 插件执行日志

dependency 表中包含为给定操作运行的自定义插件的这些日志。 下面是一个示例查询：

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

• Name/Target：正在执行的插件的全限定类型名称。
• Duration：执行插件所用时间量。
• CustomDimensions：
  • Depth：调用堆栈中执行的当前深度。
  • EntityName：插件正在处理的实体的名称。
  • IsolationType：一个值，用于指示插件是否正在沙盒中执行：
    • 1：无
    • 2：沙盒
    • 3：外部
  • PluginName：插件的易记名称。
  • PluginType：正在新的插件的类型名称。
  • PluginVersion：所发布插件的版本。 此处的目的是可以使用这些信息对版本更新进行故障排除。
  • Stage：映射到以下值：
    • PreValidation = 10
    • PreOperation = 20
    • PreOperationBeforeExternalPlugins = 15
    • PreOperationAfterExternalPlugins = 25
    • MainOperation = 30
    • PostOperationBeforeExternalPlugins = 35
    • PostOperationAfterExternalPlugins = 45
    • PostOperation = 40
    • PostOperationDeprecated = 50
  • StepName：SDK 消息处理步骤的名称。 这通常由插件注册工具使用关于 PluginName、PluginType 和操作的名称（例如，ErrorMessageTest.ThrowException: Creation of account）的信息生成。

插件代码中的遥测

如要了解插件代码内部发生的情况，可以通过使用插件代码中的 Microsoft.Xrm.Sdk.PluginTelemetry.ILogger 接口添加来自插件内的自定义遥测，以便将遥测数据直接写入您的 Application Insights 资源。 详细信息：使用 ILogger 将遥测写入 Application Insights 资源（预览）

Dataverse SDK 日志

这些是作为一对传入请求触发的 SDK 操作的日志。 它们记录在 Application Insights 中的依赖项表内，因为它们被作为要执行的请求的依赖项跟踪。 它们通过类型名称（以 SDK 开始）识别。 下面是一个示例查询：

dependencies
| where type startswith "SDK"
| take 10

• Type：触发的 SDK 请求的类型。 例如，Retrieve、RetrieveMultiple、FetchXmlToQueryExpression 和 WhoAmI。
• Name/Target：这是 SDK 操作正在针对的实体的名称。
• CustomDimensions：
  • ClientType：调用的来源客户端的类型。 值可能是 Web、UCIClient 和 OutlookFull。
  • EntityId：正在使用的实体的唯一标识符。
  • EntityName：正在使用的实体的名称。

异常

可以在 Application Insights 中查看插件和 SDK 操作的失败详细信息。 Application Insights 的 exceptions 表为失败面板提供支持。 这些失败详细信息与端到端视图中插件和 SDK 调用内的其余事件有关。 如果可以，将把所有可用值添加到列，如果没有精确匹配列，则添加到 customDimensions。

您将发现未填充 exceptions 表中的部分字段。 这是因为仅当使用 Application Insights SDK 从源发出日志时，才可以设置这些字段。 此功能收集平台遥测，然后按照 Application Insights 架构将其推送到 Application Insights 中。

exceptions
| take 10

此查询将返回 exception 表中的所有属性详细信息。

• problemId/type：异常的类型。
• outerMessage：异常消息。
• customDimensions：
  • clientType：调用的来源客户端的类型。 值可能是 Web、UCIClient 和 OutlookFull。
  • exceptionSource：引发异常的插件或点。
  • entityName：正在使用的实体的名称。
  • pluginName：引发异常的插件的名称。

如果用户报告错误，您可以使用用户 ID (Microsoft Entra ID) 了解 exception 表中的详细信息。

exceptions
| where user_Id == '12345678-68cd-4e73-908f-126342b36315'

dependency 中的 customDimensions 内提供实体 ID 和实体名称。

dependencies<br />
| where type == "SDK Retrieve"

常见问题 (FAQ)

下面是与 Dataverse 的遥测事件有关的一些常见问题。

如何确定是否是插件升级导致了性能退化？

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

插件名称中还应包含自定义插件的版本。

根据当天的时间或位置，API 在报告的问题之前的性能如何？ API 退化是逐渐的还是突发的？

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

在此图表中，可以看到 API 终结点一段时间的性能和正在进行的请求数量。

也可以根据此处特定 API 的性能在 Application Insights 内设置警报。

是否可以向下钻取特定时间或特定用户的错误或失败，以便考虑了解调用堆栈？

查看失败面板可以概览给定时间段的失败。 然后可以根据 API 调用或依赖项类型将范围缩小到特定失败，以便查看端到端视图。

是否可以创建自定义仪表板？

是的。 可以使用 Application Insights 创建自定义仪表板。

是否可以确定高峰使用期间的插件使用性能（响应时间）和失败率？

是的。 请查看以下示例查询以了解插件的性能。

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

此遥测是否有限制？

是的。 目前提供 Basic 429 错误详细信息。

是否可以了解执行路径？ 此插件进行的调用是否在导致插件性能下降？

是的。 您可以查看任何请求的所有消息和为任何请求执行的插件。

将记录所有消息和插件执行的持续时间。 如果任何插件的执行时间更久，可以识别该插件。 如果插件在回调 Dataverse，将记录该调用的持续时间。 将为将来的部署规划有关插件的更多信息。

将把插件进行的所有出站调用都记录为依赖项。

是否可以查看特定请求的遥测？

Dataverse 在所有请求的标头响应中返回 x-ms-service-requestId。 可使用这个 requestId 查询所有遥测。

union *
| where operation_ParentId contains <requestId>