【最佳实践】使用CloudLens排查iLogtail采集配置错误问题

目标读者

数字化系统开发运维（DevOps）工程师、稳定性工程师（SRE）、可观测平台运维人员等。

背景介绍

iLogtail 是阿里云日志服务（SLS）团队自研的可观测数据采集 Agent，拥有的轻量级、高性能、自动化配置等诸多生产级别特性，可以部署于物理机、虚拟机、Kubernetes 等多种环境中来采集遥测数据。目前 iLogtail 广泛应用于线上监控、问题分析/定位、运营分析、安全分析等多种场景，在实战中验证了其强大的性能和稳定性。

CloudLens for SLS是日志服务推出的一款应用，帮助用户监控和管理日志服务Project、Logstore等资产，提升用户对日志服务资产的管理效率、快速了解其消耗情况。

使用场景

文件日志采集是日志采集Agent最常见的数据采集场景，iLogtail目前支持主机上文件采集以及容器场景下的文件采集。但是文件采集在实战中会遇到各种各样的问题，基于此场景，CloudLens for SLS集成了针对iLogtail的状态监控，可以实时的反馈当前iLogtail Agent的运行状况。

问题描述

正确的采集配置是实现日志正常采集的重要基础，如果用户设定的采集配置中有任何错误，那么就会出现CATEGORY_CONFIG_ALARM错误。

问题发现

打开CloudLens for SLS，在左侧的报表中心下拉菜单中选择“采集监控”，然后在右侧的页面中选择相应的Project，点击“Logtail异常监控”选项卡，此时会展示该Project下的所有采集异常信息：

其中，名为“日志采集配置错误（CATEGORY_CONFIG_ALARM）”的表格展示了logtail的采集配置问题，它会详细地说明问题原因，以及一些帮助排查问题的信息（如logstore，ip等）。

具体场景与方案建议

出现CATEGORY_CONFIG_ALARM错误的原因有多种，这里介绍几种常见的错误场景以及可能的解决方法。

场景一：插件配置错误

错误信息

load plugin config error, invalid config: <错误的配置名称>. please check you config and logtail's plugin log.

影响范围

该采集配置将不会生效，即不会采集容器文件，但对其他采集配置没有影响。

错误原因

当前采集配置使用插件系统来采集或处理日志，但插件配置有问题。

解决方案

根据插件日志提供的信息对采集配置进行修正。

• 示例：采集容器标准输出，只采集"app":"stdout-test"标签的容器，若在控制台的插件配置框中配置如下：

{
    "inputs":
    {
          "type":"service_docker_stdout",
          "detail":{
              "Stdout":true,
              "Stderr":true,
              "IncludeLabel":{
                  "app":"stdout-test"
              },
          }
      }
}

则会产生CATEGORY_CONFIG_ALARM，原因是误将“IncludeK8sLabel”配置成了“IncludeLabel”，同时inputs的类型有误（应当为array）。修正后的配置为：

{
    "inputs":[
    {
          "type":"service_docker_stdout",
          "detail":{
              "Stdout":true,
              "Stderr":true,
              "IncludeK8sLabel":{
                  "app":"stdout-test"
              },
          }
      }
	]
}

场景二：容器模式错误

错误信息

config is docker_file mode, but logtail is not a purage container, the flag is ignored.

影响范围

该采集配置将不会生效，但对其他采集配置没有影响。

子场景一：K8s Sidecar

错误原因

通过K8s Sidecar的方式采集容器日志或正在采集主机日志，但在配置采集配置时，额外开启了“是否为Docker文件”选项。

解决方案

修改采集配置，关闭“是否为Docker文件”选项，如下所示：

子场景二：K8s Daemonset或纯Docker

错误原因

通过K8s Daemonset的方式采集容器日志或直接使用logtail容器采集Docker容器日志，则至少存在以下一种情况：

1. 当前环境中没有名为ALIYUN_LOGTAIL_USER_DEFINED_ID的环境变量

2. 从logtail进程中无法访问/logtail_host目录

解决方案

修改logtail的YAML文件，增加ALIYUN_LOGTAIL_USER_DEFINED_ID变量（如下所示），或/并确认从logtail进程中可以访问/logtail_host目录：

场景三：采集配置中Topic正则提取错误

错误信息

extract topic by regex fail, exception:<异常信息>, path:<文件路径>, regex:<配置的正则表达式>.

影响范围

该采集配置仍将生效，但其中涉及提取Topic的部分将失效，Topic将被设为空。

错误原因

当前配置的Topic生成方式为“文件路径正则”，实际文件路径不能匹配所配置的提取文件名的正则表达式。

解决方案

重新修改Topic提取的正则表达式。

• 示例：假定用户配置的Topic正则表达式为“/home/app/logs/(.*)”，而文件实际路径为“/home/app/log/example.log”，则此时正则表达式匹配失败，应该修改表达式为“/home/app/log/(.*)”。

场景四：脱敏配置错误

错误信息

The sensitive key XXX is invalid. <进一步信息>

影响范围

该采集配置仍将生效，但其中涉及脱敏配置的部分将失效。

错误原因

当前采集配置中的脱敏配置有误，一般为以下几种情况之一：

1. 没有key字段或type字段

2. type字段的值为除“const”和“md5”外的其它内容

3. 当type字段的值为“const”时，没有“const”字段

4. regex_begin和regex_content字段所组成的正则表达式有误

解决方法

根据错误定位的结果对sensitive_keys参数进行修改，相关字段的说明如下：

参数名称	数据类型	是否必填	示例值	描述
key	string	是	content	日志字段名称。
type	string	是	const	脱敏方式。可选值如下： const：将敏感内容替换成const字段取值内容。 md5：将敏感内容替换为其对应的MD5值。
regex_begin	string	是	'password':'	敏感内容前缀的正则表达式，用于查找敏感内容。使用RE2语法。更多信息，请参见RE2语法。
regex_content	string	是	[^']*	敏感内容的正则表达式，使用RE2语法。更多信息，请参见RE2语法。
all	boolean	是	true	是否替换该字段中所有的敏感内容。可选值如下： true（推荐）：替换。 false：只替换字段中匹配正则表达式的第一部分内容。
const	string	否	"********"	当type设置为const时，必须配置。

其它场景

错误信息

<配置名称> is invalid, reason: <错误原因>.

影响范围

根据错误信息的不同，影响范围由局部配置失效到采集配置整体失效不等，但不影响其它采集配置。

错误原因

当前采集配置非法。

解决方法

根据提示的错误原因进行相应的修改。

关于iLogtail

iLogtail作为阿里云SLS提供的可观测数据采集器，可以运行在服务器、容器、K8s、嵌入式等多种环境，支持采集数百种可观测数据（日志、监控、Trace、事件等），已经有千万级的安装量。目前，iLogtail已正式开源，欢迎使用及参与共建。

GitHub: https://github.com/alibaba/ilogtail

社区版文档：https://ilogtail.gitbook.io/ilogtail-docs/about/readme

企业版官网：https://help.aliyun.com/document_detail/65018.html