日志服务：如何排查容器日志采集异常

Docker/LoongCollector 部署后无心跳（AliUID 配置缺失）

在 Docker 模式下部署 LoongCollector/Logtail 后，如果机器组心跳状态持续异常（无法注册），通常是由于用户标识（AliUID）配置缺失。LoongCollector/Logtail 容器需要读取阿里云账号 ID 信息才能向 SLS 注册机器组，未挂载该文件时注册无法完成。

解决步骤：

1. 在宿主机上创建用户标识目录：

   mkdir -p /etc/ilogtail/users/

2. 在该目录下创建以阿里云账号 ID 命名的空文件（文件名即阿里云账号 ID）：

   touch /etc/ilogtail/users/{阿里云账号ID}

3. 启动 LoongCollector/Logtail 容器时，将该目录以只读方式挂载到容器内（在 docker run 命令中添加如下参数）：

   -v /etc/ilogtail/users:/etc/ilogtail/users:ro

4. 重启 LoongCollector/Logtail 容器。

验证：操作完成后，在 SLS 控制台进入对应机器组，查看心跳状态是否变为 OK。

Docker Swarm 集群多台服务器上报相同 IP 导致机器组识别异常

在 Docker Swarm 集群中，如果机器组中仅显示一台机器而非实际数量，通常是因为多台服务器的 Logtail 容器使用了相同的内部 IP，且配置了相同的 ALIYUN_LOGTAIL_USER_DEFINED_ID，导致 SLS 无法区分不同的服务器。

解决方法一：为每台服务器的 Logtail 容器设置唯一的 ALIYUN_LOGTAIL_USER_DEFINED_ID 环境变量，确保各服务器标识不重复，并与机器组配置中的自定义标识匹配：

-e ALIYUN_LOGTAIL_USER_DEFINED_ID={唯一标识，如 swarm-node-1}

解决方法二：设置 ALIYUN_LOGTAIL_WORKING_IP 环境变量，手动为每台服务器的 Logtail 容器指定唯一的工作 IP（例如宿主机公网 IP 或内网唯一 IP）：

-e ALIYUN_LOGTAIL_WORKING_IP={宿主机唯一IP地址}

SLS 容器元信息预览找不到 Pod 或采集不到 emptyDir 日志

在 SLS 控制台的容器元信息预览中找不到目标 Pod，或应用写入 emptyDir 的日志始终无法被采集，通常是由于 Logtail（DaemonSet 模式）无法访问容器内部的 emptyDir 临时存储。

原因：Logtail 以 DaemonSet 方式运行在宿主机上，emptyDir 是 K8s 的临时存储卷，仅存在于 Pod 内部，宿主机无法直接访问，因此 Logtail 无法读取其中的日志文件，也无法提取容器元数据。

解决方案一（推荐）：修改应用，将日志输出到标准输出（stdout/stderr）。在 SLS 控制台将采集路径配置为 K8s 标准日志路径：

/logtail_host/var/log/pods/<namespace>_<pod-name>-<uid>/<container-name>/*.log

解决方案二：若必须使用文件日志，将应用的日志目录挂载方式从 emptyDir 改为 hostPath 或 PVC，确保日志持久化在宿主机可访问路径，然后将 SLS 采集路径调整为宿主机实际挂载路径，例如：

/logtail_host/var/log/your-app/*.log

Logtail 采集容器日志提示创建文件失败或权限错误

现象：Logtail 报错，提示需要在容器内创建特定的空文件，或出现权限拒绝（Permission denied）错误，导致无法正常采集日志。

解决步骤：

1. 根据报错提示，在容器内手动创建指定的空文件：

   touch <报错中指定的文件路径>

2. 设置该文件的权限为 -rw-r--r--（644）：

   chmod 644 <报错中指定的文件路径>

3. 重启容器。

替代方案：如果以上步骤后仍无法采集，建议将容器日志目录挂载到宿主机，通过宿主机路径进行采集，此方案更为稳定。

采集 K8s 标准输出日志报错 parse cri docker line error

现象：日志中出现 parse cri docker line error: invalid CRI log, timestamp not found 报错，导致 K8s 标准输出（stdout）日志无法正常采集。

原因：日志行解析失败，常见原因是多行日志配置中行首正则表达式配置不正确，Logtail 无法识别 CRI 日志行格式。

解决步骤：

1. 检查 Logtail 配置中的行首正则表达式，确认能正确匹配日志格式；如有必要，尝试关闭多行模式：

   • YAML 配置方式：在配置文件中注释或删除 multiline 相关配置段，然后重新 apply 配置。

   • 控制台方式：在 SLS 控制台的 Logtail 配置页面，关闭多行日志采集选项。

2. 确认 K8s Namespace Regex 格式正确。若需匹配多个命名空间，各命名空间之间需使用竖线（|）分隔，例如：namespace1|namespace2。

3. 修改 YAML 配置后，执行以下命令重新应用配置使其生效：

   kubectl apply -f <配置文件.yaml>

Logtail 配置 JSON 解析插件时出现红色叹号无法保存怎么办？

现象：在 Logtail 配置中添加 JSON 解析插件后，插件图标旁出现红色叹号警告，配置无法保存。

原因：红色叹号通常表示插件内部尚未完成配置，或配置在编辑过程中发生变化但未应用。

解决步骤：

1. 在 Logtail 配置编辑页面，删除系统默认添加的 JSON 解析插件。

2. 重新手动添加 JSON 解析插件，并在插件内完成所有必填字段的配置（如日志样例、解析规则）。

3. 配置完成后红色叹号会消失，此时即可正常保存 Logtail 配置。

说明：在 JSON 解析插件之后继续添加时间解析插件是标准用法，可用于从日志正文中提取时间字段作为日志时间。

多个 Logtail 配置匹配同一文件导致采集不到数据（MULTI CONFIG MATCH ALARM）怎么办？

现象：Logtail 运行日志中出现 MULTI CONFIG MATCH ALARM 告警，无法采集到目标文件的数据。

原因：默认情况下，一个日志文件只能匹配一个 Logtail 配置。当多个 Logtail 配置的文件路径同时匹配到同一文件时，仅其中一个配置会生效，其余配置无法采集到数据，并触发 MULTI CONFIG MATCH ALARM 告警。

解决步骤：

1. 删除多余的 Logtail 配置：在日志服务控制台检查绑定到对应机器组的所有 Logtail 配置，删除重复或不再使用的配置，使每个文件仅被一个配置匹配。

2. 按 pod-name 拆分匹配路径：如果确需对同一文件使用多个配置（例如按 pod-name 拆分采集），请参考官方文档修改相关配置，使每个 Logtail 配置通过更精确的路径或 Label 过滤只匹配自己的目标文件，避免路径重叠。

3. 修改完成后，观察 Logtail 运行日志，确认 MULTI CONFIG MATCH ALARM 告警消失且数据正常采集。

Logtail 采集容器日志报错 no such file or directory 如何处理？

现象：Logtail 运行日志中出现 no such file or directory 报错，目标容器日志无法采集。

原因：目标采集路径在节点上不存在，通常与 Kubernetes Pod 生命周期或日志轮转机制有关。

解决步骤：

1. 确认 Pod 是否仍存在：若 Pod 已被删除，对应的日志路径随之消失，属于正常现象，可忽略该报错。若 Pod 仍在运行，请登录对应节点检查实际日志路径是否存在。

2. 优先使用容器标准输出采集：在ACK 控制台创建采集配置时，建议选择容器标准输出类型，并通过容器 Label 或容器名称匹配目标容器，避免直接依赖容器内部文件路径。

3. 必须采集文件时的配置建议：使用通配符路径（例如 /logtail_host/var/log/pods/*/*.log），并开启 Logtail 配置中的自动发现新文件选项，使 Logtail 能在日志轮转或 Pod 重建后自动跟踪新路径。

4. 验证 Logtail 配置是否应用到对应机器组：确认该 Logtail 配置已绑定到包含目标 Pod 的机器组。

5. 查看 Logtail 自身运行日志：若大量报错集中于已销毁的 Pod，可忽略；若持续报错且 Pod 仍在运行，则需要修正采集路径或检查节点挂载。

Logtail 因 logfiletoobig 跳过文件导致采集中断如何解决？

现象：Logtail 运行日志中出现 logfiletoobig 告警，目标文件被跳过，日志采集中断。

原因：目标日志文件大小超过 Logtail 默认限制，Logtail 主动跳过该文件以保护稳定性。

解决步骤：

1. 调整 Logtail 采集配置：在 Logtail 配置或机器组全局参数中做如下调整：

   • 提高 MaxLogFileSize（例如设为 1GB），避免大文件被跳过。

   • 增大 MaxLogFileInodeCacheSize（例如设为 2000），提升对轮转文件的跟踪能力。

   • 确保 EnableContainerDiscovery 设置为 true，使 Logtail 能自动发现容器日志路径。

2. 触发重新扫描：在 ACK 集群中执行以下命令，删除 loongcollector-ds（或 logtail-ds）Pod，由 DaemonSet 自动重建并重新扫描所有容器日志路径：

   kubectl delete pod -n kube-system -l k8s-app=loongcollector-ds

3. 验证与替代方案：观察日志服务控制台的日志接收情况，并检查 Logtail Pod 内是否仍有残留错误。若上述方法无效，建议尝试接入K8s-标准输出-新版配置并打开容器元信息预览，使用标准输出路径代替文件路径采集。

登录Logtail容器

• 普通Docker

  1. 在宿主机上执行如下命令，查询Logtail容器。

     docker ps | grep logtail

     系统将返回如下类似结果。

     223****6e        registry.cn-hangzhou.aliyuncs.com/log-service/logtail                             "/usr/local/ilogta..."   8 days ago          Up 8 days                               logtail-iba

  2. 执行如下命令，在Logtail容器内启动bash shell。

     docker exec -it 223****6e  bash

     其中，223****6e为容器ID，请根据实际值替换。

• Kubernetes

  1. 执行如下命令，查询Logtail的Pod。

     kubectl get po -n kube-system | grep logtail

     系统将返回如下类似结果。

     logtail-ds-****d                                             1/1       Running    0          8d
     logtail-ds-****8                                             1/1       Running    0          8d

  2. 执行如下命令，登录Pod。

     kubectl exec -it -n kube-system logtail-ds-****d -- bash

     其中，logtail-ds-****d为Pod ID，请根据实际值替换。

查看Logtail的运行日志

Logtail日志存储在Logtail容器中的/usr/local/ilogtail/目录中，文件名为ilogtail.LOG和logtail_plugin.LOG。

1. 登录Logtail容器。具体操作，登录Logtail容器。

2. 打开/usr/local/ilogtail/目录。

   cd /usr/local/ilogtail

3. 查看ilogtail.LOG和logtail_plugin.LOG文件。

   cat ilogtail.LOG
   cat logtail_plugin.LOG

查看Logtail的版本号、IP地址、启动时间

1. 在宿主机执行如下命令，查看Logtail的版本号、IP地址、启动时间。

   相关信息存储在Logtail容器的/usr/local/ilogtail/app_info.json文件中。

   kubectl exec logtail-ds-****k -n kube-system cat /usr/local/ilogtail/app_info.json

   系统将返回如下类似结果。

   {
      "UUID" : "",
      "hostname" : "logtail-****k",
      "instance_id" : "0EB****_172.20.4.2_1517810940",
      "ip" : "172.20.4.2",
      "logtail_version" : "0.16.2",
      "os" : "Linux; 3.10.0-693.2.2.el7.x86_64; #1 SMP Tue Sep 12 22:26:13 UTC 2017; x86_64",
      "update_time" : "2018-02-05 06:09:01"
   }

ACK 集群中 Pod 日志采集异常的排查信息获取

在 ACK 集群中遇到 Pod 日志采集异常时，可以通过以下方法获取排查所需的基础信息，并在寻求技术支持时一并提供，以加快问题定位。

获取 Logtail/LoongCollector 的 IP 地址：

1. 执行以下命令，查找目标节点上的 LoongCollector/Logtail Pod 名称：

   kubectl get pods -n kube-system | grep loongcollector

2. 执行以下命令，获取 IP 地址及其他基础信息（<pod-name> 替换为上一步获取的实际 Pod 名称）：

   kubectl exec <pod-name> -n kube-system cat /usr/local/ilogtail/app_info.json

向技术支持提供有效排查信息：寻求帮助时，请提供以下信息：

• Project 名称

• Logtail 采集配置名称

• 目标 Pod 名称

• 容器名称（Container Name）

执行 docker pull 拉取 LoongCollector/Logtail 镜像是否会影响本机其他服务？

结论：仅执行 docker pull 命令拉取 LoongCollector 或 Logtail 镜像，不会对本机上正在运行的其他服务产生任何影响。docker pull 只是将镜像层下载到本地镜像仓库，不会启动容器，也不会占用 CPU 或额外内存。

注意事项：

• 后续执行 docker run 启动容器时，请确保宿主机有充足的 CPU 与内存资源，避免新容器与现有业务争抢资源。

• 检查容器端口映射是否与宿主机上已有服务的端口冲突，避免影响现有业务。

• 如需长期在 Kubernetes 环境中运行日志采集组件，建议通过ACK 控制台的组件管理安装 LoongCollector（DaemonSet 模式），由集群统一调度资源。

日志服务控制台 ACK 集群日志接入页面缺少 K8s-标准输出-新版 选项怎么办？

现象：在日志服务控制台的 ACK 集群日志接入页面中，找不到K8s-标准输出-新版入口。

原因：该入口可能由于后端功能临时下线修复而暂时不可用。

替代方案：

1. 临时使用旧版接入方式：在控制台选择旧版K8s-标准输出入口完成接入。注意旧版已停止维护，仅建议作为临时过渡方案。

2. 使用 CRD 替代控制台入口（推荐）：直接在集群内使用 kubectl 创建 AliyunPipelineConfig CRD 来配置新版标准输出采集，无需依赖控制台入口。请参考本文档容器标准输出-新版章节中的 YAML 示例，将其中参数替换为您的实际 Project、LogStore 与集群信息后执行：

   kubectl apply -f aliyun-pipeline-config.yaml

   该方式与通过控制台创建的配置等价，且便于以 GitOps 方式管理采集配置。