使用 ConfigMap 筛选容器日志收集

2025-10-11

Kubernetes 群集会生成 Azure Monitor 收集的大量数据。由于为引入和保留此数据付费，因此可以筛选出不需要的数据以显著降低监视成本。

ConfigMap 是一种 Kubernetes 机制，可用于存储非机密数据，例如配置文件或环境变量。容器见解会在每个群集上查找 ConfigMap，其中包含定义它应收集的数据的特定设置。

小窍门

在实现本文中所述的任何筛选选项之前，请确保选择符合要求的日志收集配置文件。使用本文中的信息进一步优化群集的数据收集设置。

先决条件

支持从容器工作负荷收集 stdout、stderr 和环境变量的最低代理版本为 ciprod06142019 或以上。

配置和部署 ConfigMap

按照以下过程配置 ConfigMap 配置文件并将其部署到群集：

如果你还没有用于容器见解的 ConfigMap，请下载模板 ConfigMap YAML 文件，并在编辑器中打开它。
使用你的自定义编辑 ConfigMap YAML 文件。该模板包含所有有效设置及其说明。若要启用设置，请移除注释字符 (#) 并设置其值。
运行以下 kubectl 命令创建 ConfigMap：
```
kubectl config set-context <cluster-name>
kubectl apply -f <configmap_yaml_file.yaml>

# Example: 
kubectl config set-context my-cluster
kubectl apply -f container-azm-ms-agentconfig.yaml
```
配置更改可能需要几分钟才能完成，然后才会生效。然后，群集中的所有 Azure Monitor 代理 Pod 都将重启。所有 Azure Monitor 代理 Pod 的重启是轮流式的，因此它们不会一次性全部重启。重启完成后，你将收到类似于以下结果的消息：
```
configmap "container-azm-ms-agentconfig" created`.
```

验证配置

若要验证配置是否已成功应用于群集，请使用以下命令查看代理 Pod 的日志。

kubectl logs ama-logs-fdf58 -n kube-system -c ama-logs

如果 Azure Monitor 代理 Pod 存在配置错误，输出中会显示类似于以下的错误：

***************Start Config Processing******************** 
config::unsupported/missing config schema version - 'v21' , using defaults

使用以下选项对配置更改进行更多的故障排除：

使用代理 Pod 中的相同 kubectl logs 命令。

查看实时日志，查找类似以下的错误：

config::error::Exception while parsing config map for log collection/env variable settings: \nparse error on value \"$\" ($end), using defaults, please check config map for errors

对于配置错误，数据每小时都会发送到你的 Log Analytics 工作区中的 KubeMonAgentEvents 表，并包含错误严重性。如果没有错误，表中的条目将包含严重性为“信息”的数据，这些数据不会报告错误。 Tags 列包含有关发生错误的 Pod 和容器 ID 的详细信息、第一次发生错误的 Pod 和容器 ID、最后一次发生错误的 Pod 和容器 ID 以及最后一小时内的错误计数。

验证架构版本

Azure Monitor 代理 Pod 上以 Pod 注释（架构-版本）的形式提供了支持的配置架构版本。可以使用以下 kubectl 命令查看它们。

kubectl describe pod ama-logs-fdf58 -n=kube-system.

容器日志是由 Kubernetes 群集中的容器生成的 stderr 和 stdout 日志。这些日志存储在 Log Analytics 工作区的ContainerLogV2 表中。默认情况下，收集所有容器日志，但可以从特定命名空间中筛选出日志或完全禁用容器日志收集。

使用ConfigMap，可以单独为群集配置 stderr 和 stdout 日志的收集，以便选择启用一个日志而不是另一个日志。以下示例显示了用于收集 stdout 和 stderr 的 ConfigMap 设置，不包括kube-system和gatekeeper-system命名空间。

[log_collection_settings]
    [log_collection_settings.stdout]
        enabled = true
        exclude_namespaces = ["kube-system","gatekeeper-system"]

    [log_collection_settings.stderr]
        enabled = true
        exclude_namespaces = ["kube-system","gatekeeper-system"]

    [log_collection_settings.enrich_container_logs]
        enabled = true

注意

还可以使用群集的数据收集规则 (DCR) 配置命名空间筛选，但这不适用于发送到 ContainerLogV2 的数据。只能使用 ConfigMap 筛选此数据。

平台日志筛选（系统 Kubernetes 命名空间）

默认情况下，系统命名空间中的容器日志从集合中排除，以最大程度地降低 Log Analytics 成本。但是，在特定的故障排除场景中，系统容器的容器日志可能至关重要。此功能仅限于以下系统命名空间：kube-system、gatekeeper-system、calico-system、 azure-arc、kube-public和kube-node-lease。

通过设置使用collect_system_pod_logs启用平台日志。还必须确保系统命名空间不在exclude_namespaces设置中。

以下示例演示了用于收集coredns命名空间中kube-system容器的 stdout 和 stderr 日志的 ConfigMap 设置。

[log_collection_settings]
    [log_collection_settings.stdout]
        enabled = true
        exclude_namespaces = ["gatekeeper-system"]
        collect_system_pod_logs = ["kube-system:coredns"]

    [log_collection_settings.stderr]
        enabled = true
        exclude_namespaces = ["kube-system","gatekeeper-system"]
        collect_system_pod_logs = ["kube-system:coredns"]

基于注释的工作负载筛选

基于注释的筛选使你能够通过注释 Pod 来排除某些 Pod 和容器的日志收集。这可以显著降低日志引入成本，并允许专注于相关信息，而无需筛选干扰。

通过以下设置使用ConfigMap启用基于注释的筛选。

[log_collection_settings.filter_using_annotations]
   enabled = true

还必须在工作负载 Pod 规范上添加所需的注释。下表突出显示了不同的可能的 Pod 批注。

注释	说明
`fluentbit.io/exclude: "true"`	排除 Pod 中所有容器上的 stdout 和 stderr 流
`fluentbit.io/exclude_stdout: "true"`	仅排除 Pod 中所有容器上的 stdout 流
`fluentbit.io/exclude_stderr: "true"`	仅排除 Pod 中所有容器上的 stderr 流
`fluentbit.io/exclude_container1: "true"`	仅针对 Pod 中的 container1 排除 stdout 和 stderr 流
`fluentbit.io/exclude_stdout_container1: "true"`	仅针对 pod 中 container1 排除 stdout

注意

这些注释是基于 fluent bit 的。如果将你自己的基于 fluent-bit 的日志收集解决方案与 Kubernetes 插件筛选器和基于注释的排除结合使用，它将停止从 Container Insights 和你的解决方案收集日志。

下面是 Pod 规范中fluentbit.io/exclude: "true"注释的示例：

apiVersion: v1 
kind: Pod 
metadata: 
 name: apache-logs 
 labels: 
  app: apache-logs 
 annotations: 
  fluentbit.io/exclude: "true" 
spec: 
 containers: 
 - name: apache 
  image: edsiper/apache_logs

筛选环境变量

通过以下设置使用ConfigMap，跨群集中的所有 Pod 和节点启用环境变量集合。

[log_collection_settings.env_var]
    enabled = true

如果环境变量集合已全局启用，则可对特定容器禁用它，方法是将环境变量 AZMON_COLLECT_ENV 设置为 False，可以在 Dockerfile 设置中这样做，也可以在 Pod 的配置文件（位于 env: 部分下）中这样做。如果环境变量集合已全局启用，则无法为特定容器启用集合。唯一可在容器级别应用的替代是在已全局启用集合的情况下禁用集合。

ConfigMap 设置

下表描述了可以使用 ConfigMap 配置的用于控制数据收集的设置。

设置	数据类型	价值	说明
`schema-version`	字符串（区分大小写）	v1	在分析此 ConfigMap 时由代理使用。当前支持的架构版本为 v1。不支持修改此值，在评估 ConfigMap 时对此修改会被拒绝。
`config-version`	String		允许在源代码管理系统/存储库中跟踪此配置文件的版本。允许的最大字符数为 10，所有其他字符将会截掉。
[log_collection_settings]
`[stdout]` `enabled`	布尔	是假	控制是否启用 stdout 容器日志收集。如果设置为 `true` 且未在 stdout 日志收集中排除任何命名空间，则会从群集的所有 pod 和节点中的所有容器收集 stdout 日志。如果未在 ConfigMap 中指定，默认值为 `true`。
`[stdout]` `exclude_namespaces`	String	逗号分隔的数组	不收集其 stdout 日志的 Kubernetes 命名空间数组。仅当 `enabled` 设置为 `true` 时，此设置才会生效。如果未在 ConfigMap 中指定，默认值为 `["kube-system","gatekeeper-system"]`。
`[stderr]` `enabled`	布尔	是假	控制是否启用 stderr 容器日志收集。如果设置为 `true` 且未在 stderr 日志收集中排除任何命名空间，则会从群集的所有 pod 和节点中的所有容器收集 stderr 日志。如果未在 ConfigMap 中指定，默认值为 `true`。
`[stderr]` `exclude_namespaces`	String	逗号分隔的数组	不收集其 stderr 日志的 Kubernetes 命名空间数组。仅当 `enabled` 设置为 `true` 时，此设置才会生效。如果未在 ConfigMap 中指定，默认值为 `["kube-system","gatekeeper-system"]`。
`[env_var]` `enabled`	布尔	是假	控制群集中所有 Pod 和节点的环境变量收集。如果未在 ConfigMap 中指定，默认值为 `true`。
`[enrich_container_logs]` `enabled`	布尔	是假	控制容器日志扩充，以填充写入群集中所有容器日志的 `Name` 表的每条日志记录的 `Image` 和属性值。如果未在 ConfigMap 中指定，默认值为 `false`。
`[collect_all_kube_events]` `enabled`	布尔	是假	控制是否收集所有类型的 Kube 事件。默认情况下，不收集 Normal 类型的 Kube 事件。当此设置为 `true` 时，不再筛选 Normal 事件，并将收集所有事件。如果未在 ConfigMap 中指定，默认值为 `false`。
`[schema]` `containerlog_schema_version`	字符串（区分大小写）	v2 v1	设置日志引入格式。如果为 `v2`，则使用 ContainerLogV2 表。如果为 `v1`，则使用 ContainerLog 表（此表已弃用）。对于使用 Azure CLI 2.54.0 或更高版本启用容器见解的群集，默认设置为 `v2`。有关详细信息，请参阅容器见解日志架构。
`[enable_multiline_logs]` `enabled`	布尔	是假	控制是否启用多行容器日志。有关详细信息，请参阅容器见解中的多行日志记录。如果未在 ConfigMap 中指定，默认值为 `false`。这要求 `schema` 设置为 `v2`。
`[metadata_collection]` `enabled`	布尔	是假	控制是否在 `KubernetesMetadata` 表的 `ContainerLogV2` 列中收集元数据。
`[metadata_collection]` `include_fields`	String	逗号分隔的数组	要包含的元数据字段的列表。如果未使用该设置，则会收集所有字段。有效值为 `["podLabels","podAnnotations","podUid","image","imageID","imageRepo","imageTag"]`
`[log_collection_settings.multi_tenancy]` `enabled`	布尔	是假	管控多租户功能的启用状态。有关详细信息，请参阅多租户托管日志记录。如果未在 ConfigMap 中指定，默认值为 `false`。
[指标收集设置]
`[collect_kube_system_pv_metrics]` `enabled`	布尔	是假	允许在 kube 系统命名空间中收集永久性卷 (PV) 使用指标。默认情况下，不会在 kube 系统命名空间中收集具有永久性卷声明的永久性卷的使用指标。当此设置设为 `true` 时，将收集所有命名空间的 PV 使用指标。如果未在 ConfigMap 中指定，默认值为 `false`。
[agent_settings]
`[proxy_config]` `ignore_proxy_settings`	布尔	是假	为 `true` 时，忽略代理设置。对于 AKS 和已启用 Arc 的 Kubernetes 环境，如果群集配置有正向代理，则会自动应用代理设置并将其用于代理。对于某些配置（例如使用 AMPLS + 代理），可能需要忽略代理配置。如果未在 ConfigMap 中指定，默认值为 `false`。
[agent_settings.fbit_config]
`enable_internal_metrics`	布尔	是假	控制是否启用内部指标集合。如果未在 ConfigMap 中指定，默认值为 `false`。

对可视化效果和警报的影响

如果有任何使用容器见解数据的自定义警报或工作簿，则修改数据收集设置可能会导致这些体验降级。。如果你要排除命名空间或降低数据收集频率，请查看使用此数据的现有警报、仪表板和工作簿。

若要扫描引用这些表的警报，请运行以下 Azure Resource Graph 查询：

resources
| where type in~ ('microsoft.insights/scheduledqueryrules') and ['kind'] !in~ ('LogToMetric')
| extend severity = strcat("Sev", properties["severity"])
| extend enabled = tobool(properties["enabled"])
| where enabled in~ ('true')
| where tolower(properties["targetResourceTypes"]) matches regex 'microsoft.operationalinsights/workspaces($|/.*)?' or tolower(properties["targetResourceType"]) matches regex 'microsoft.operationalinsights/workspaces($|/.*)?' or tolower(properties["scopes"]) matches regex 'providers/microsoft.operationalinsights/workspaces($|/.*)?'
| where properties contains "Perf" or properties  contains "InsightsMetrics" or properties  contains "ContainerInventory" or properties  contains "ContainerNodeInventory" or properties  contains "KubeNodeInventory" or properties  contains"KubePodInventory" or properties  contains "KubePVInventory" or properties  contains "KubeServices" or properties  contains "KubeEvents" 
| project id,name,type,properties,enabled,severity,subscriptionId
| order by tolower(name) asc

后续步骤

请参阅容器见解中的数据转换，以向 DCR 添加转换，以便根据详细条件进一步筛选数据。

通过