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

如何配置适用于 Azure Cosmos DB 的 Azure Functions 触发器的日志记录和连接

  • 项目

适用范围： NoSQL

本文介绍使用适用于 Azure Cosmos DB 的 Azure Functions 触发器时可设置的高级配置选项。

启用触发器特定日志

适用于 Azure Cosmos DB 的 Azure Functions 触发器在内部使用更改源处理器库，该库会生成一组运行状况日志，而这些日志又可用于监视内部操作以进行故障排除。

运行状况日志描述了在负载均衡、初始化或处理方案期间尝试执行操作时，适用于 Azure Cosmos DB 的 Azure Functions 触发器的行为。

启用日志记录

若要在使用适用于 Azure Cosmos DB 的 Azure Functions 触发器时启用日志记录，请在 Azure Functions 项目或 Azure Functions 应用中找到 host.json 文件，并配置所需的日志记录级别。 按以下示例所示为 Host.Triggers.CosmosDB 启用跟踪：

{
  "version": "2.0",
  "logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "Host.Triggers.CosmosDB": "Warning"
    }
  }
}

使用更新的配置部署 Azure Functions 后，将在跟踪中看到适用于 Azure Cosmos DB 的 Azure Functions 触发器日志。 可以在类别 Host.Triggers.CosmosDB 下查看所配置的日志记录提供程序中的日志。

发出哪种类型的日志？

启用后，将发出四个级别的日志事件：

  • 错误：

    • 更改源处理上存在影响正确触发器功能的未知或严重错误时。

  • 警告：

    • 当函数用户代码出现未经处理的异常 - 函数代码中存在缺口且函数在应对错误时不具备复原能力或序列化错误（对于 C# 函数，原始 JSON 无法反序列化为所选的 C# 类型）
    • 出现暂时性连接问题时，阻止触发器与 Azure Cosmos DB 帐户交互。 触发器将重试这些暂时性连接错误，但如果这些错误的存在时间延长，则可能会出现网络问题。 可以启用调试级别跟踪，从基础 Azure Cosmos DB SDK 获取诊断信息。

  • 信息:

    • 将租约带到另一个实例时（在初始化期间和函数缩放时），可将租约重新平衡到另一个实例。 如果你自定义了获取或过期间隔，则它还可能指示这些值可能不合适（过期间隔低于续订间隔）。

  • 调试：

    • 实例获取租约时 - 当前实例将开始处理租约的更改源。
    • 实例释放租约时 - 当前实例将停止处理租约的更改源。
    • 将新更改从触发器传递到函数代码时 - 在函数代码可能存在错误以及不确定是否收到更改时，帮助调试这种情况。
    • 对于警告和错误跟踪，请添加从基础 Azure Cosmos DB SDK 获取的诊断信息以进行故障排除。

还可以参考源代码，查看完整详细信息。

查询日志

在 Azure Application Insights Analytics 中运行以下查询，以查询适用于 Azure Cosmos DB 的 Azure Functions 触发器生成的日志：

traces
| where customDimensions.Category == "Host.Triggers.CosmosDB"

配置连接策略

有两种连接模式 - Direct（直接）模式和 Gateway（网关）模式。 若要详细了解这些连接模式，请参阅连接模式一文。 默认情况下，网关用于在适用于 Azure Cosmos DB 的 Azure Functions 触发器中建立所有连接。 但是，对于性能驱动的方案，它可能不是最佳选项。

更改连接模式和协议

有两个密钥配置设置可用于配置客户端连接策略 – 连接模式和连接协议。 可以更改适用于 Azure Cosmos DB 的 Azure Functions 触发器和所有 Azure Cosmos DB 绑定使用的默认连接模式与协议。 若要更改默认设置，需要在 Azure Functions 项目或 Azure Functions 应用中找到 host.json 文件，并添加以下附加设置：

{
  "cosmosDB": {
    "connectionMode": "Direct",
    "protocol": "Tcp"
  }
}

其中，connectionMode 必须包含所需的连接模式（Direct 或 Gateway），protocol 必须包含所需的连接协议（Tcp 用于 Direct 模式，Https 用于 Gateway 模式）。

如果 Azure Functions 项目正在使用 Azure Functions V1 运行时（配置名称略有不同），则应使用 documentDB 而不是 cosmosDB：

{
  "documentDB": {
    "connectionMode": "Direct",
    "protocol": "Tcp"
  }
}

自定义用户代理

适用于 Azure Cosmos DB 的 Azure Functions 触发器执行对服务的请求，这些请求将反映在监视中。 可以通过更改host.json额外设置中的 userAgentSuffix 来自定义用户代理，该代理用于 Azure Function 的请求：

{
  "cosmosDB": {
    "userAgentSuffix": "MyUniqueIdentifier"
  }
}

注意

在消耗计划中托管函数应用时，每个实例可以维护的套接字连接数量都有限制。 使用 Direct/TCP 模式时，根据设计会创建更多的连接，这可能会达到消耗计划限制，在这种情况下，可使用 Gateway 模式或者改为在高级计划或专用（应用服务）计划中托管函数应用。

后续步骤