如何为 Azure Functions 配置监视

Azure Functions 与 Application Insights 集成，从而使你能够更好地监视函数应用。 Application Insights（Azure Monitor 的一项功能）是一种可扩展的应用程序性能管理 (APM) 服务，该服务收集函数应用生成的数据，包括应用写入日志的信息。 通常，在创建函数应用时会启用 Application Insights 集成。 如果应用未设置检测密钥，必须先启用 Application Insights 集成。

可以使用 Application Insights 而无需任何自定义配置。 但是，默认配置可能会产生大量数据。 如果使用的是 Visual Studio Azure 订阅，可能会达到 Application Insights 的数据上限。 有关 Application Insights 费用的详细信息，请参阅 Application Insights 计费。 有关详细信息，请参阅具有大量遥测数量的解决方案。

本文将介绍如何配置和自定义函数发送到 Application Insights 的数据。 可以在 host.json 文件中设置常见日志记录配置。 默认情况下，这些设置还控制代码发出的自定义日志。 但是，在某些情况下可以禁用此行为，以改为使用可让你更好地控制日志记录的选项。 有关详细信息，请参阅自定义应用程序日志。

自定义应用程序日志

默认情况下，写入的自定义应用程序日志将发送到 Functions 主机，然后 Functions 主机会通过“辅助角色”类别将其发送到 Application Insights。 使用某些语言堆栈，可以改为将日志直接发送到 Application Insights，让你能够完全控制写入日志的发出方式。 在本例中，日志记录管道将从 worker -> Functions host -> Application Insights 更改为 worker -> Application Insights。

下表汇总了可用于每个堆栈的配置选项：

将自定义应用程序日志配置为直接发送时，主机将不再发出它们，并且 host.json 不再控制其行为。 同样，每个堆栈公开的选项仅适用于自定义日志，并且它们不会更改本文中所述的其他运行时日志的行为。 在这种情况下，要控制所有日志的行为，可能需要同时更改这两种配置。

配置类别

对于每个日志，Azure Functions 记录器都包含一个类别。 类别指示运行时代码或函数代码的哪个部分编写日志。 版本 1.x 和更高版本中的类别有所不同。

与其他 .NET 框架相比，在 Functions 中分配类别名称的方式有所不同。 例如，在 ASP.NET 中使用 ILogger<T> 时，类别是泛型类型的名称。 C# 函数还使用 ILogger<T>，但运行时不将泛型类型名称设置为类别，而是根据源分配类别。 例如：

• 运行函数相关的条目会分配 Function.<FUNCTION_NAME> 类别。
• 在函数内由用户代码创建的条目（例如调用 logger.LogInformation()时）会分配 Function.<FUNCTION_NAME>.User 类别。

以下图表描述了运行时创建的日志的主要类别：

表列指示将日志写入 Application Insights 中的哪个表。

配置日志级别

为每个日志分配日志级别。 该值是表示相对重要性的整数：

host.json 文件配置确定函数应用发送到 Application Insights 的日志记录数量。

对于每个类别，均可以指示要发送的最小日志级别。 host.json 设置因 Functions 运行时版本而异。

下面的示例根据以下规则定义日志记录：

• 默认日志记录级别设置为 Warning，这可以防止针对非预期类别的过度日志记录。
• Host.Aggregator 和 Host.Results 设置为较低级别。 将事件日志设置为过高级别（尤其是高于 Information）可能会导致指标和性能数据丢失。
• 函数运行的日志记录设置为 Information。 如有必要，可以在本地开发中将此设置替代为 Debug 或 Trace。

{
  "logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "default": "Warning",
      "Host.Aggregator": "Trace",
      "Host.Results": "Information",
      "Function": "Information"
    }
  }
}

{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "Warning",
      "categoryLevels": {
        "Host.Results": "Information",
        "Host.Aggregator": "Trace",
        "Function": "Information"
      }
    }
  }
}

如果 host.json 包含以相同字符串开头的多个日志，则首先匹配定义更多的日志。 考虑以下示例，该示例在运行时中记录 Error 级别上除 Host.Aggregator 之外的所有内容：

{
  "logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "default": "Information",
      "Host": "Error",
      "Function": "Error",
      "Host.Aggregator": "Information"
    }
  }
}

{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "Information",
      "categoryLevels": {
        "Host": "Error",
        "Function": "Error",
        "Host.Aggregator": "Information"
      }
    }
  }
}

可以使用日志级别设置 None 来阻止为某个类别写入任何日志。

配置聚合器

如前一部分中所述，运行时聚合一段时间内有关函数执行的数据。 默认时段为 30 秒或 1,000 次运行，以先满足的条件为准。 可以在 host.json 文件中配置此设置。 例如：

{
    "aggregator": {
      "batchSize": 1000,
      "flushTimeout": "00:00:30"
    }
}

配置采样

Application Insights 具有采样功能，可以防止在峰值负载时为已完成的执行生成过多的遥测数据。 当传入执行的速率超过指定的阈值时，Application Insights 开始随机忽略某些传入执行。 每秒执行的最大次数的默认设置为 20（版本 1.x 中为 5）。 可以在 host.json 中配置采样。 下面是一个示例：

{
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond" : 20,
        "excludedTypes": "Request;Exception"
      }
    }
  }
}

{
  "applicationInsights": {
    "sampling": {
      "isEnabled": true,
      "maxTelemetryItemsPerSecond" : 5
    }
  }
}

如果你的项目使用 Application Insights SDK 依赖项进行手动遥测跟踪，则当采样配置与函数应用中的采样配置不同时，你可能会遇到奇怪的行为。 在这种情况下，请使用与函数应用相同的采样配置。 有关详细信息，请参阅 Application Insights 中的采样。

启用 SQL 查询集合

Application Insights 自动收集有关 HTTP 请求、数据库调用和多个绑定的依赖项的数据。 有关详细信息，请参阅依赖项。 对于 SQL 调用，始终收集并存储服务器和数据库的名称，但默认情况下不会收集 SQL 查询文本。 可通过在 host.json 文件中（至少）使用以下设置，从而使用 dependencyTrackingOptions.enableSqlCommandTextInstrumentation 来启用 SQL 查询文本记录：

"logging": {
    "applicationInsights": {
        "enableDependencyTracking": true,    
        "dependencyTrackingOptions": {
            "enableSqlCommandTextInstrumentation": true
        }
    }
}

有关详细信息，请参阅使用高级 SQL 跟踪获取完整的 SQL 查询。

配置缩放控制器日志

此功能为预览版。

可以让 Azure Functions 缩放控制器将日志发出到 Application Insights 或 Blob 存储，以便更好地了解缩放控制器为函数应用做出的决策。

若要启用此功能，请将名为 SCALE_CONTROLLER_LOGGING_ENABLED 的应用程序设置添加到函数应用设置中。 以下设置值必须采用 <DESTINATION>:<VERBOSITY> 格式。 有关详细信息，请参阅下表：

例如，以下 Azure CLI 命令会启用从缩放控制器到 Application Insights 的详细日志记录：

az functionapp config appsettings set --name <FUNCTION_APP_NAME> \
--resource-group <RESOURCE_GROUP_NAME> \
--settings SCALE_CONTROLLER_LOGGING_ENABLED=AppInsights:Verbose

在此示例中，请将 <FUNCTION_APP_NAME> 和 <RESOURCE_GROUP_NAME> 分别替换为函数应用名称和资源组名称。

以下 Azure CLI 命令通过将详细程度设置为 None 来禁用日志记录：

az functionapp config appsettings set --name <FUNCTION_APP_NAME> \
--resource-group <RESOURCE_GROUP_NAME> \
--settings SCALE_CONTROLLER_LOGGING_ENABLED=AppInsights:None

还可以通过使用以下 Azure CLI 命令删除 SCALE_CONTROLLER_LOGGING_ENABLED 设置来禁用日志记录：

az functionapp config appsettings delete --name <FUNCTION_APP_NAME> \
--resource-group <RESOURCE_GROUP_NAME> \
--setting-names SCALE_CONTROLLER_LOGGING_ENABLED

启用缩放控制器日志记录后，便可以查询缩放控制器日志。

启用 Application Insights 集成

若要使函数应用将数据发送到 Application Insights，它只需使用以下应用程序设置之一连接到 Application Insights 资源：

在 Azure 门户中创建函数应用时，请在命令行中使用 Azure Functions Core Tools 或 Visual Studio Code，默认情况下会启用 Application Insights 集成。 Application Insights 资源的名称与函数应用的相同，并且在同一区域或最接近的区域中创建。

要求 Microsoft Entra 身份验证

可以使用 APPLICATIONINSIGHTS_AUTHENTICATION_STRING 设置通过 Microsoft Entra 身份验证启用与 Application Insights 的连接。 这样可在所有 Application Insights 管道（包括 Profiler 和 Snapshot Debugger）以及 Functions 主机和特定于语言的代理中创建一致的身份验证体验。

该值包含 Authorization=AAD（针对系统分配的托管标识），或 ClientId=<YOUR_CLIENT_ID>;Authorization=AAD（针对用户分配的托管标识）。 托管标识必须已可供函数应用使用，其分配到的角色等效于监视指标发布服务器。

仍需要 APPLICATIONINSIGHTS_CONNECTION_STRING 设置。

添加到现有函数应用

如果未使用函数应用创建 Application Insights 资源，请使用以下步骤创建资源。 然后，可以添加该资源中的连接字符串，作为函数应用中的应用程序设置。

1. 在 Azure 门户中，搜索并选择“函数应用”，然后选择你的函数应用。

2. 选择窗口顶部的“未配置 Application Insights”横幅。 如果看不到此横幅，则应用可能已启用 Application Insights。

   

3. 展开“更改资源”，使用下表中指定的设置创建 Application Insights 资源：

   设置	建议值	描述
   新资源名称	唯一的应用名称	使用与函数应用相同的名称是最方便的，该名称在订阅中必须独一无二。
   位置	中国北部 2	尽可能使用函数应用所在的同一区域，或与该区域接近的区域。

   

4. 选择“应用”。

   Application Insights 资源在与函数应用相同的资源组和订阅中创建。 创建资源后，关闭“Application Insights”窗口。

5. 在函数应用中，展开“设置”，然后选择“环境变量”。 在“应用设置”选项卡中，如果看到名为 APPLICATIONINSIGHTS_CONNECTION_STRING 的设置，则表明已为在 Azure 中运行的函数应用启用 Application Insights 集成。 如果该设置不存在，请使用 Application Insights 连接字符串作为值来添加它。

禁用内置日志记录

早期版本的 Functions 使用了内置监视功能，现不再建议使用该功能。 启用 Application Insights 时，请禁用使用 Azure 存储的内置日志记录。 内置日志记录对于使用轻工作负载测试非常有用，但不适合在高负载生产环境中使用。 对于生产监视，建议使用 Application Insights。 如果在生产环境中使用内置日志记录，日志记录可能因 Azure 存储限制而不完整。

若要禁用内置日志记录，请删除 AzureWebJobsDashboard 应用设置。 有关如何在 Azure 门户中删除应用设置的详细信息，请参阅如何管理函数应用的“应用程序设置”部分。 在删除应用设置之前，请确保同一函数应用中没有任何现有的函数将此设置用于 Azure 存储触发器或绑定。

具有大量遥测数据的解决方案

函数应用是可能导致生成大量遥测数据的解决方案（例如 IoT 解决方案、快速事件驱动的解决方案、高负载金融系统和集成系统）的重要组成部分。 在这种情况下，应考虑采用额外的配置来降低成本，同时保持可观测性。

可以在实时仪表板、警报、详细诊断等中使用生成的遥测数据。 根据生成的遥测数据的使用方式，需要定义一种策略来减少生成的数据量。 此策略使你可以适当监视、操作和诊断生产环境中的函数应用。 请考虑以下选项：

• 使用采样：如前所述，抽样有助于大幅减少引入的遥测事件量，同时保持统计上正确的分析。 即使使用采样，也仍有可能得到大量遥测数据。 检查自适应采样提供的选项。 例如，将 maxTelemetryItemsPerSecond 设置为一个可以根据监视需求平衡生成的数据量的值。 请记住，遥测采样是按照每个执行函数应用的主机应用的。

• 默认日志级别：使用 Warning 或 Error 作为所有遥测类别的默认值。 稍后，可以决定要将哪些类别设置为 Information 级别，以便可以适当监视和诊断函数。

• 优化函数遥测：如果将默认日志级别设置为 Error 或 Warning，将不会收集每个函数的详细信息（依赖项、自定义指标、自定义事件和跟踪）。 对于那些对生产监视非常关键的函数，请为 Function.<YOUR_FUNCTION_NAME> 类别定义一个显式条目并将其设置为 Information，以便可以收集详细信息。 若要避免在 Information 级别收集用户生成的日志，请将 Function.<YOUR_FUNCTION_NAME>.User 类别设置为 Error 或 Warning 日志级别。

• Host.Aggregator 类别：如配置类别中所述，此类别提供函数调用的聚合信息。 此类别的信息将收集到 Application Insights customMetrics 表中，并显示在 Azure 门户上的函数“概述”选项卡中。 根据聚合器的配置方式，请考虑到收集的遥测数据中可能存在延迟（由 flushTimeout 设置确定）。 如果将此类别设置为不同于 Information 的其他值，则会停止在 customMetrics 表中收集数据，并且不会在函数“概述”选项卡中显示指标。

  以下屏幕截图显示了函数“概述”选项卡中显示的 遥测数据：Host.Aggregator

  

  以下屏幕截图显示了 Application Insights customMetrics 表中的 Host.Aggregator 遥测数据：

  

• Host.Results 类别：如配置类别中所述，此类别提供运行时生成的日志，用于指示函数调用的成功或失败结果。 此类别的信息将收集到 Application Insights requests 表中，并显示在函数“监视”选项卡和不同的 Application Insights 仪表板（“性能”、“失败”等）中。 如果将此类别设置为除 Information 以外的值，则只会收集在定义的日志级别（或更高级别）生成的遥测数据。 例如，将其设置为 error 只会跟踪失败的执行的请求数据。

  以下屏幕截图显示了函数“监视”选项卡中显示的 Host.Results 遥测数据：

  

  以下屏幕截图显示了 Application Insights“性能”仪表板中显示的 Host.Results 遥测数据：

  

• Host.Aggregator 与 Host.Results：这两个类别都提供有关函数执行的有用见解。 如果需要，可以从其中一个类别中删除详细信息，以便可以使用另一个类别进行监视和警报。 下面是一个示例：

{
  "version": "2.0",  
  "logging": {
    "logLevel": {
      "default": "Warning",
      "Function": "Error",
      "Host.Aggregator": "Error",
      "Host.Results": "Information", 
      "Function.Function1": "Information",
      "Function.Function1.User": "Error"
    },
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond": 1,
        "excludedTypes": "Exception"
      }
    }
  }
} 

{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "Warning",
      "categoryLevels": {
        "Function": "Error",
        "Host.Aggregator": "Error",
        "Host.Results": "Information",
        "Host.Executor": "Warning"
      }
    }
  },
  "applicationInsights": {
    "sampling": {
      "isEnabled": true,
      "maxTelemetryItemsPerSecond" : 5
    }
  }
}

使用此配置时：

• 所有函数和遥测类别的默认值都将设置为 Warning（包括 Microsoft 和 Worker 类别）。 因此，默认情况下，将会收集运行时和自定义日志记录生成的所有错误和警告。

• Function 类别的日志级别会设置为 Error，因此默认情况下，对于所有函数，只收集异常和错误日志。 系统会跳过依赖项、用户生成的指标和用户生成的事件。

• 对于 Host.Aggregator 类别，由于它设置为 Error 日志级别，因此不会在 customMetrics Application Insights 表中收集函数调用的聚合信息，也不会在函数概述仪表板中显示有关执行计数（总计、成功数、失败数）的信息。

• 对于 Host.Results 类别，所有主机执行信息将收集到 requests Application Insights 表中。 所有调用结果将显示在函数“监视”仪表板和 Application Insights 仪表板中。

• 对于名为 Function1 的函数，我们已将日志级别设置为 Information。 因此对于此具体函数，将收集所有遥测数据（依赖项、自定义指标和自定义事件）。 对于同一个函数，我们会将 Function1.User 类别（用户生成的跟踪）设置为 Error，因此只会收集自定义错误日志。

  注意

  Functions 运行时的 v1.x 不支持按函数配置。

• 采样配置为每秒为每种类型发送一个遥测项（不包括异常）。 对于运行此函数应用的每个服务器主机，都会执行这种抽样。 因此，如果我们有四个实例，则此配置将每秒为每种类型发出四个遥测项以及可能发生的所有异常。

  注意

  诸如请求速率和异常率等指标计数将进行调整以补偿采样率，以便它们在指标资源管理器中能够显示大约正确的值。

在运行时替代监视配置

最后，在某些情况下，你可能需要快速更改生产环境中某个类别的日志记录行为，并且不希望仅仅为了在 host.json 文件中做出某项更改而要进行完整部署。 对于此类情况，可以替代 host.json 值。

若要在应用设置级别配置这些值（并避免仅仅为了进行 host.json 更改而要重新部署），应该通过创建等效的值作为应用程序设置来替代特定的 host.json 值。 当运行时查找 AzureFunctionsJobHost__path__to__setting 格式的应用程序设置时，它将替代 JSON 中位于 path.to.setting 的等效 host.json 设置。 当表示为应用程序设置时，用于指示 JSON 层次结构的点 (__) 将替换为双下划线 (.)。 例如，可以使用以下应用设置来配置与 host.json 中相同的各个函数日志级别。

可以直接在 Azure 门户的“函数应用配置”边栏选项卡上替代设置，也可以使用 Azure CLI 或 PowerShell 脚本来替代设置。

az functionapp config appsettings set --name MyFunctionApp --resource-group MyResourceGroup --settings "AzureFunctionsJobHost__logging__logLevel__Host__Aggregator=Information"

Update-AzFunctionAppSetting -Name MyAppName -ResourceGroupName MyResourceGroupName -AppSetting @{"AzureFunctionsJobHost__logging__logLevel__Host__Aggregator" = "Information"}

使用运行状况检查监视函数应用

可以使用运行状况检查功能监视高级（弹性高级）和专用（应用服务）计划中的函数应用。 运行状况检查不是消耗计划的选项。 若要了解如何对其进行配置，请参阅使用运行状况检查监视应用服务实例。 函数应用应具有 HTTP 触发器函数，该函数在运行状况检查的 Path 参数上配置的同一终结点上以 200 的 HTTP 状态代码进行响应。 还可以让该函数执行额外的检查，从而确保依赖的服务可访问且正常工作。

相关内容

有关监视的详细信息，请参阅：

• 监视 Azure Functions
• 在 Application Insights 中分析 Azure Functions 遥测数据
• Application Insights 概述