你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

排查资源日志问题

项目
2025/01/24

本操作指南概述了 Azure Web PubSub 资源日志，并提供了有关使用该日志排查问题的提示。你可以使用日志识别问题、跟踪连接、跟踪消息、跟踪 HTTP 请求以及进行分析。

什么是资源类？

有三种类型的资源日志：

“连接性”日志提供有关 Azure Web PubSub 中心连接的详细信息。它们可能包括用户 ID 和连接 ID 等基本信息，或者连接和断开连接等事件信息。
消息传送日志将针对通过 Azure Web PubSub 服务发送和接收的中心消息提供跟踪信息，例如跟踪 ID 或消息类型。
HTTP 请求日志提供有关对 Azure Web PubSub 服务的 HTTP 请求的跟踪信息，例如 HTTP 方法或状态代码。通常，在 HTTP 请求到达或离开服务时，会对其进行记录。

使用实时跟踪工具捕获资源日志

Azure Web PubSub 服务中的实时跟踪工具可以实时收集资源日志，这有助于排查开发环境中的问题。实时跟踪工具可以捕获连接性日志、消息传送日志和 HTTP 请求日志。

使用实时跟踪工具时，应考虑以下因素：

实时跟踪工具捕获的实时资源日志将作为消息（出站流量）计费。
Azure Web PubSub 服务的免费层实例的每日限制为 20,000 条消息（出站流量）。使用实时跟踪有可能意外导致达到每日限制。
实时跟踪工具目前不支持 Microsoft Entra 身份验证。必须启用访问密钥才能使用实时跟踪。在“设置”下，选择“密钥”，然后启用“访问密钥”。

启动实时跟踪工具

启用访问密钥时，可以使用访问令牌对实时跟踪工具进行身份验证。否则，将使用 Microsoft Entra ID 对实时跟踪工具进行身份验证。你可以在 Azure 门户中转到 Azure SignalR 服务实例中的“密钥”窗格来了解是否已启用访问密钥。

在启用访问密钥的情况下打开实时跟踪

转到 Azure 门户，然后进入 SignalR 服务窗格。
在服务菜单中的“监视”下，选择“实时跟踪设置”。
选择“启用实时跟踪”。
选择“保存”按钮。这些更改需要一段时间才能生效。
更新完成后，选择“打开实时跟踪工具”。

在禁用访问密钥的情况下打开实时跟踪工具

向自己分配实时跟踪工具 API 权限

转到 Azure 门户，然后进入 SignalR 服务窗格。
选择“访问控制(IAM)”。
选择“+添加”，然后选择“角色分配”。
在“工作职能角色”选项卡，选择“SignalR 服务所有者”角色，然后选择“下一步”。
在“成员”页面上，单击“+选择成员”。
搜索并选择成员，然后单击“选择”。
选择“审阅 + 分配”，并等待出现完成通知。

启用实时跟踪工具

转到 Azure 门户，然后进入 SignalR 服务窗格。
在服务菜单中的“监视”下，选择“实时跟踪设置”。
选择“启用实时跟踪”。
选择“保存”按钮。这些更改需要一段时间才能生效。
更新完成后，选择“打开实时跟踪工具”。

实时跟踪工具将打开一个 Microsoft 登录窗口。如果未打开任何窗口，请在浏览器设置中允许弹出窗口。
等待状态栏上显示“准备就绪”。

捕获资源日志

实时跟踪工具有助于捕获资源日志以进行故障排除。

捕获：开始从 Azure Web PubSub 捕获实时资源日志。
清除：清除捕获的实时资源日志。
日志筛选器：使用一个特定关键字筛选捕获的实时资源日志。空格、逗号和分号等常见分隔符将视为关键字的一部分。
状态：显示实时跟踪工具与特定实例是已连接还是已断开连接。

屏幕截图显示了如何使用实时跟踪工具捕获资源日志。

实时跟踪工具捕获的实时资源日志包含用于进行故障排除的详细信息。

名称	说明
时间	日志事件时间
日志级别	日志事件级别（`Trace`、`Debug`、`Informational`、`Warning` 或 `Error`）
事件名称	事件的操作名称
消息	事件的详细消息
Exception	Azure Web PubSub 服务的运行时异常
中心	用户定义的中心名称
连接 ID	连接的标识
用户 ID	用户标识
IP	客户端 IP 地址
路由模板	API 的路由模板
HTTP 方法	HTTP 方法（`POST`、`GET`、`PUT` 或 `DELETE`）
URL	统一资源定位符
跟踪 ID	调用的唯一标识符
状态代码	HTTP 响应代码
Duration	接收请求与处理请求之间的持续时间
标头	客户端和服务器通过 HTTP 请求或响应传递的其他信息

使用 Azure Monitor 捕获资源日志

启用资源日志

目前，Azure Web PubSub 支持与 Azure 存储集成。

转到 Azure 门户。
在 Azure Web PubSub 服务实例的“诊断设置”页面上，选择“+ 添加诊断设置”。
在“诊断设置名称”中，输入设置名称。
在“类别详细信息”中，选择所需的任何日志类别。
在“目标详细信息”中，选择“存档到存储帐户”。
单击“保存”以保存诊断设置。

备注

存储帐户应与 Azure Web PubSub 服务位于同一区域。

存档到 Azure 存储帐户

日志存储在“诊断设置”窗格内配置的存储帐户中。系统会自动创建一个名为 insights-logs-<CATEGORY_NAME> 的容器来存储资源日志。日志存储在该容器中的 resourceId=/SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/XXXX/PROVIDERS/MICROSOFT.SIGNALRSERVICE/SIGNALR/XXX/y=YYYY/m=MM/d=DD/h=HH/m=00/PT1H.json 文件内。其路径由 resource ID 和 Date Time 组成。日志文件按 hour 拆分。分钟值始终为 m=00。

所有日志均以 JavaScript 对象表示法 (JSON) 格式存储。每个条目均包含字符串字段，这些字段采用以下部分所述的格式。

存档日志中的 JSON 字符串包含以下表中列出的元素。

Format

名称	描述
`time`	日志事件时间
`level`	日志事件级别
`resourceId`	Azure SignalR 服务实例的资源 ID
`location`	Azure SignalR 服务实例的位置
`category`	日志事件的类别
`operationName`	事件的操作名称
`callerIpAddress`	服务器/客户端的 IP 地址
`properties`	与此日志事件相关的详细属性（请参阅下表）

属性表

名称	描述
`collection`	日志事件（`Connection`、`Authorization` 或 `Throttling`）的集合
`connectionId`	连接的标识
`userId`	用户的标识
`message`	日志事件的详细消息
`hub`	用户定义的中心名称
`routeTemplate`	API 的路由模板
`httpMethod`	HTTP 方法（`POST`、`GET`、`PUT` 或 `DELETE`）
`url`	统一资源定位符
`traceId`	调用的唯一标识符
`statusCode`	HTTP 响应代码
`duration`	接收请求与处理请求之间的持续时间
`headers`	客户端和服务器通过 HTTP 请求或响应传递的其他信息

以下代码是存档日志中的 JSON 字符串的示例：

{
  "properties": {
    "message": "Connection started",
    "collection": "Connection",
    "connectionId": "LW61bMG2VQLIMYIVBMmyXgb3c418200",
    "userId": null
  },
  "operationName": "ConnectionStarted",
  "category": "ConnectivityLogs",
  "level": "Informational",
  "callerIpAddress": "167.220.255.79",
  "resourceId": "/SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/MYGROUP/PROVIDERS/MICROSOFT.SIGNALRSERVICE/WEBPUBSUB/MYWEBPUBSUB",
  "time": "2021-09-17T05:25:05Z",
  "location": "westus"
}

存档到 Azure 日志分析

将日志发送到 Log Analytics 工作区：

在“诊断设置”页面的“目标详细信息”下，选择“发送到 Log Analytics 工作区”。
对于“订阅”，请选择要使用的订阅。
对于日志的目标位置，请选择 “Log Analytics 工作区”。

若要查看资源日志，请执行以下步骤：

在目标 Log Analytics 工作区中选择“日志”。
若要查询日志，请输入 WebPubSubConnectivity、WebPubSubMessaging 或 WebPubSubHttpRequest，然后选择时间范围。若要进行高级查询，请参阅开始使用 Azure Monitor 中的 Log Analytics。

若要对 SignalR 服务使用示例查询，请执行以下步骤：

在目标 Log Analytics 工作区中选择“日志”。
选择“查询”以打开查询资源管理器。
选择“资源类型”以按资源类型对示例查询进行分组。
选择“运行”以运行脚本。

存档日志列包含下表列出的元素。

名称	描述
`TimeGenerated`	日志事件时间
`Collection`	日志事件（`Connection`、`Authorization` 和 `Throttling`）的集合
`OperationName`	事件的操作名称
`Location`	Azure SignalR 服务实例的位置
`Level`	日志事件级别
`CallerIpAddress`	服务器/客户端的 IP 地址
`Message`	日志事件的详细消息
`UserId`	用户的标识
`ConnectionId`	连接的标识
`ConnectionType`	连接类型（`Server`，即来自服务器端的连接；`Client`，即来自客户端的连接）
`TransportType`	连接的传输类型（`Websockets`、`ServerSentEvents` 和 `LongPolling`）

使用资源日志进行故障排除

如果发现连接数意外增加或减少，可以使用资源日志来排查问题。可能的问题包括意外的连接数量变化、连接数量达到上限和授权失败。

意外断开连接事件

如果连接断开，资源日志将在 operationName 中使用 ConnectionAborted 或 ConnectionEnded 记录此断开连接事件。

ConnectionAborted 和 ConnectionEnded 之间的区别在于，ConnectionEnded 是客户端或服务器端触发的预期内的断开连接，而 ConnectionAborted 通常是指连接意外断开的事件，并且将在 message中提供断开连接的原因。

下表列出了意外断开连接的原因。

Reason	说明
连接计数达到限制	连接计数达到当前定价层的上限。请考虑纵向扩展服务单元。
服务重新加载并重新连接	正在重新加载 Azure Web PubSub 服务。你需要实现自己的重新连接机制，或手动重新连接到 Azure Web PubSub 服务。
内部服务器的暂时性错误	Azure Web PubSub 服务中发生暂时性错误。系统应该会自动恢复。

连接意外增加

当客户端连接数量意外增加时，应执行以下步骤。首先，筛选掉多余的连接，并将唯一的测试用户 ID 添加到测试客户端连接。然后，检查资源日志。如果发现多个客户端连接具有同一测试用户 ID 或 IP，可能表示客户端创建了超过预期数目的连接。检查客户端代码以找到额外连接的源。

授权失败

如果系统针对客户端请求返回了“401 未授权”，请检查资源日志。如果发现 Failed to validate audience. Expected Audiences: <valid audience>. Actual Audiences: <actual audience>，则表示访问令牌中的所有受众均无效。请尝试使用日志中建议的有效受众。

限制

如果发现无法在客户端与 Azure Web PubSub 服务之间建立连接，请检查资源日志。如果在资源日志中看到 Connection count reaches limit，则表示与 Azure Web PubSub 服务建立的连接过多，达到了连接数量的上限。请考虑纵向扩展 Azure Web PubSub 服务实例。

如果在 Message count reaches limit 资源日志中看到且正在使用免费层，则表示已用光了消息的配额。若要发送更多消息，请考虑将 Azure Web PubSub 服务实例更改为标准层。有关详细信息，请参阅 Azure Web PubSub 定价。

未来属于你

通过

排查资源日志问题

什么是资源类？

使用实时跟踪工具捕获资源日志