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

如何排查资源日志相关的问题

项目
08/28/2023

本操作指南概述了 Azure Web PubSub 资源日志，以及一些使用日志故障排除某些问题的提示。日志可用于识别问题、连接跟踪、消息跟踪和 HTTP 请求跟踪及分析。

什么是资源类？

有三种类型的资源日志：连接、消息传送和 HTTP 请求。

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

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

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

注意

以下注意事项适用于使用实时跟踪工具：

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

启动实时跟踪工具

注意

在启用访问密钥时，你将使用访问令牌对实时跟踪工具进行身份验证。否则，将使用 Microsoft Entra ID 对实时跟踪工具进行身份验证。可以在 Azure 门户中 SignalR 服务的“密钥”页检查是否启用访问密钥。

启用访问密钥的步骤

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

禁用访问密钥的步骤

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

转到 Azure 门户和 SignalR 服务页面。
选择“访问控制 (IAM)”。
在新页面中，单击“+添加”，然后单击“角色分配”。
在新页中，将焦点放在“作业函数角色”选项卡上，选择“SignalR 服务所有者”橘色，然后单击“下一步”。
在“成员”页中，单击“+选择成员”。
在新面板中，搜索并选择成员，然后单击“选择”。
单击“查看 + 分配”，并等待完成通知。

访问实时跟踪工具

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

实时跟踪工具将弹出一个 Microsoft 登录窗口。如果没有弹出窗口，请进行检查，并在浏览器中允许弹出窗口。
等待状态栏中显示“就绪”。

捕获资源日志

实时跟踪工具提供了帮助捕获资源日志以进行故障排除的功能。

捕获：开始从 Azure Web PubSub 捕获实时资源日志。
清除：清除捕获的实时资源日志。
日志筛选器：使用实时跟踪工具，可以通过一个特定的关键字来筛选已捕获的实时资源日志。通用分隔符（如空格、逗号、分号等）可视为关键词的一部分。
状态：“状态”显示实时跟踪工具与特定实例是已连接还是已断开连接。

屏幕截图：使用实时跟踪工具捕获资源日志。

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

名称	说明
时间	日志事件时间
日志级别	日志事件级别可以是 [跟踪/调试/信息/警告/错误]
事件名称	事件的操作名称
Message	事件的详细消息
异常	Azure Web PubSub 服务的运行时异常
集线器	用户定义的中心名称
连接 ID	连接的标识
用户 ID	用户标识
IP	客户端 IP 地址
路由模板	API 的路由模板
HTTP 方法	HTTP 方法 (POST/GET/PUT/DELETE)
URL	统一资源定位符
跟踪 ID	调用的唯一标识符
状态代码	HTTP 响应代码
持续时间	接收请求和处理请求之间的持续时间
标头	客户端和服务器传递的且包含 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 字符串包含下表列出的元素：

格式

名称	说明
time	日志事件时间
level	日志事件级别
ResourceId	Azure SignalR 服务的资源 ID
location	Azure SignalR 服务的位置
category	日志事件的类别
operationName	事件的操作名称
callerIpAddress	服务器/客户端的 IP 地址
properties	与此日志事件相关的详细属性。有关更多详细信息，请参阅下面的属性表

属性表

名称	说明
collection	日志事件的集合。允许的值为：`Connection`、`Authorization` 和 `Throttling`
connectionId	连接的标识
userId	用户的标识
message	日志事件的详细消息
中心	用户定义的中心名称
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 中选择 Logs。
输入 WebPubSubConnectivityWebPubSubMessaging 或 WebPubSubHttpRequest，然后选择查询日志的时间范围。若要进行高级查询，请参阅开始使用 Azure Monitor 中的 Log Analytics。

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

在目标 Log Analytics 中选择 Logs。
选择 Queries 以打开查询资源管理器。
选择 Resource type 以对资源类型中的示例查询进行分组。
选择 Run 以运行脚本。

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

名称	说明
TimeGenerated	日志事件时间
集合	日志事件的集合。允许的值为：`Connection`、`Authorization` 和 `Throttling`
OperationName	事件的操作名称
位置	Azure SignalR 服务的位置
Level	日志事件级别
CallerIpAddress	服务器/客户端的 IP 地址
Message	日志事件的详细消息
UserId	用户的标识
ConnectionId	连接的标识
ConnectionType	连接的类型。允许的值为：`Server` \| `Client`。 `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 服务定价。

通过

如何排查资源日志相关的问题

什么是资源类？

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