如何为 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 文件中配置日志记录。

注意

可以使用专门配置的应用程序设置来表示针对特定环境的 host.json 文件中的特定设置。 这使你可以有效地更改 host.json 设置,而不必在项目中重新发布 host.json 文件。 有关详细信息,请参阅替代 host.json 值

配置类别

对于每个日志,Azure Functions 记录器都包含一个类别。 类别指示运行时代码或函数代码的哪个部分编写日志。 版本 1.x 和更高版本中的类别有所不同。 以下图表描述了运行时创建的日志的主要类别:

类别 说明
Function.<YOUR_FUNCTION_NAME> 依赖项 系统会自动收集一些服务的依赖项数据。 对于成功运行,这些日志处于 Information 级别。 有关详细信息,请参阅依赖项。 异常记录在 Error 级别。 运行时还会创建 Warning 级别日志,例如将队列消息发送到病毒队列时。
Function.<YOUR_FUNCTION_NAME> customMetrics
customEvents
使用 C# 和 JavaScript SDK,可以收集自定义指标并记录自定义事件。 有关详细信息,请参阅自定义遥测数据
Function.<YOUR_FUNCTION_NAME> traces 包括针对特定函数运行的函数已启动和已完成日志。 对于成功运行,这些日志处于 Information 级别。 异常记录在 Error 级别。 运行时还会创建 Warning 级别日志,例如将队列消息发送到病毒队列时。
Function.<YOUR_FUNCTION_NAME>.User traces 用户生成的日志,可以是任何日志级别。 有关从函数写入日志的详细信息,请参阅写入日志
Host.Aggregator customMetrics 这些运行时生成的日志在一段可配置的时间内提供函数调用的计数和平均值。 默认时段为 30 秒或 1,000 个结果,以先满足的条件为准。 示例包括运行数、成功率和持续时间。 所有这些日志均在 Information 级别编写。 如果在 Warning 或更高级别进行筛选,则不会看到任何这些数据。
Host.Results requests 这些运行时生成的日志指示函数是成功还是失败。 所有这些日志均在 Information 级别编写。 如果在 Warning 或更高级别进行筛选,则不会看到任何这些数据。
Microsoft traces 反映主机调用的 .NET 运行时组件的完全限定的日志类别。
Worker traces 语言工作进程为非 .NET 语言生成的日志。 语言辅助角色日志也可以记录在 Microsoft.* 类别中,例如 Microsoft.Azure.WebJobs.Script.Workers.Rpc.RpcFunctionInvocationDispatcher。 这些日志在 Information 级别写入。

注意

对于 .NET 类库函数,这些类别假定你使用的是 ILogger 而不是 ILogger<T>。 有关详细信息,请参阅 Functions ILogger 文档

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

配置日志级别

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

LogLevel 代码 说明
跟踪 0 包含最详细消息的日志。 这些消息可能包含敏感应用程序数据。 这些消息默认情况下处于禁用状态,并且绝不应在生产环境中启用。
调试 1 在开发过程中用于交互式调查的日志。 这些日志应主要包含对调试有用的信息,并且没有长期价值。
信息 2 跟踪应用程序的常规流的日志。 这些日志应具有长期价值。
警告 3 突出显示应用程序流中的异常或意外事件,但不会导致应用程序执行停止的日志。
错误 4 当前执行流因失败而停止时突出显示的日志。 这些错误应指示当前活动中的故障,而不是应用程序范围内的故障。
严重 5 描述不可恢复的应用程序/系统崩溃或需要立即引起注意的灾难性故障的日志。
6 禁用指定类别的日志记录。

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

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

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

  • 对于 Host.ResultsFunction 的日志,仅记录 Error 或更高级别的事件。
  • 对于 Host.Aggregator 的日志,记录所有生成的指标 (Trace)。
  • 对于所有其他日志(包括用户日志),仅记录 Information 级别及更高级别的事件。
{
  "logging": {
    "fileLoggingMode": "always",
    "logLevel": {
      "default": "Information",
      "Host.Results": "Error",
      "Function": "Error",
      "Host.Aggregator": "Trace"
    }
  }
}

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

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

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

注意

Azure Functions 通过将遥测事件存储在 Application Insights 表中来与 Application Insights 集成。 将类别日志级别设置为除 Information 以外的任何值会阻止遥测数据流入这些表。 因此,你将无法在“Application Insights”或“函数监视器”选项卡中看到相关数据。

在上面的示例中:

  • 如果 Host.Results 设置为 Error 日志级别,则它只会收集 requests 表中与失败的函数执行对应的主机执行遥测事件,导致“Application Insights”和“函数监视器”选项卡中不会显示成功执行的主机执行详细信息。
  • 如果 Function 类别设置为 Error 日志级别,则会停止收集与所有函数的 dependenciescustomMetricscustomEvents 相关的函数遥测数据,导致你无法在 Application Insights 中查看任何此类数据。 它只会收集已记录的 Error 级别的 traces

在这两种情况下,你将继续在“Application Insights”和“函数监视器”选项卡中收集错误和异常数据。有关详细信息,请参阅具有大量遥测数据的解决方案

配置聚合器

如前一部分中所述,运行时聚合一段时间内有关函数执行的数据。 默认时段为 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"
      }
    }
  }
}

可以从采样中排除某些类型的遥测。 在此示例中,采样中排除了类型为 RequestException 的数据。 这可确保记录所有函数执行(请求)和异常,而其他类型的遥测仍会受到采样的限制。

有关详细信息,请参阅 Application Insights 中的采样

配置缩放控制器日志

此功能为预览版。

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

若要启用此功能,可将名为 SCALE_CONTROLLER_LOGGING_ENABLED 的应用程序设置添加到函数应用设置中。 以下设置值必须采用 <DESTINATION>:<VERBOSITY> 格式:

属性 说明
<DESTINATION> 日志发送到的目标。 有效值为 AppInsightsBlob
使用 AppInsights 时,请确保在函数应用中启用 Application Insights
将目标设置为 Blob 时,将在名为 azure-functions-scale-controller 的 blob 容器中创建日志,该容器位于 AzureWebJobsStorage 应用程序设置中设置的默认存储帐户中。
<VERBOSITY> 指定日志记录级别。 支持的值为 NoneWarningVerbose
设置为 Verbose 时,缩放控制器将记录辅助角色计数每次更改的原因,以及有关将这些因素纳入决策的触发器的信息。 详细日志包含触发器警告和缩放控制器运行前后触发器使用的哈希。

提示

请记住,将“缩放控制器日志记录”保留为启用时,它会影响监视函数应用的潜在成本。 请考虑启用日志记录,直到收集到的数据足以了解缩放控制器的行为方式,然后将其禁用。

例如,以下 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 资源的检测密钥。 该密钥必须位于名为 APPINSIGHTS_INSTRUMENTATIONKEY 的应用设置中。

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

添加到现有函数应用

如果未使用函数应用创建 Application Insights 资源,请使用以下步骤创建资源。 然后,可以添加该资源中的检测密钥,作为函数应用中的应用程序设置

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

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

    从门户中启用 Application Insights 的屏幕截图。

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

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

    屏幕截图显示如何创建 Application Insights 资源。

  4. 选择“应用”。

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

  5. 在函数应用中,选择“设置”下的“配置”,然后选择“应用程序设置”。 如果看到名为 APPINSIGHTS_INSTRUMENTATIONKEY 的设置,则表明已为在 Azure 中运行的函数应用启用 Application Insights 集成。 如果出于某种原因,该设置不存在,请使用 Application Insights 检测密钥作为值来添加该设置。

注意

早期版本的 Functions 使用了内置监视功能,现不再建议使用该功能。 为此类函数应用启用 Application Insights 集成时,还必须禁用内置日志记录功能

禁用内置日志记录

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

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

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

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

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

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

  • 默认日志级别:使用 WarningError 作为所有遥测类别的默认值。 现在可以决定要将哪些类别设置为 Information 级别,以便可以适当监视和诊断函数。

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

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

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

    在函数的“概述”选项卡中显示的 Host.Aggregator 遥测的屏幕截图。

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

    customMetrics Application Insights 表中的 Host.Aggregator 遥测数据的屏幕截图。

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

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

    函数的“监视器”选项卡中的 Host.Results 遥测的屏幕截图。

    以下屏幕截图显示了 Application Insights“性能”仪表板中显示的 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"
      }
    }
  }
} 

使用此配置时:

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

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

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

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

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

    注意

    v1.x 不支持按函数配置。

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

    注意

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

提示

尝试不同的配置,确保满足日志记录、监视和警报相关的要求。 另请确保在出现意外错误或故障时可以获得详细诊断信息。

在运行时替代监视配置

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

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

Host.json 路径 应用设置
logging.logLevel.default AzureFunctionsJobHost__logging__logLevel__default
logging.logLevel.Host.Aggregator AzureFunctionsJobHost__logging__logLevel__Host__Aggregator
logging.logLevel.Function AzureFunctionsJobHost__logging__logLevel__Function
logging.logLevel.Function.Function1 AzureFunctionsJobHost__logging__logLevel__Function.Function1
logging.logLevel.Function.Function1.User AzureFunctionsJobHost__logging__logLevel__Function.Function1.User

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

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

注意

通过更改应用设置替代 host.json 会重启函数应用。

后续步骤

有关监视的详细信息,请参阅: