采集容器日志（Sidecar-CRD方式）--日志服务-火山引擎

文档中心

立即注册

导航

采集容器日志（Sidecar-CRD方式）

最近更新时间：2024.12.02 18:55:42首次发布时间：2023.10.13 14:01:11

通过 Sidecar 方式采集容器文本日志时，可以通过 LogCollector CRD 方式创建采集配置。本文档演示通过 Sidecar-CRD 方式创建日志采集配置的操作步骤。

背景信息

日志服务支持通过 Sidecar 方式采集容器日志，同时可通过 LogCollector CRD 方式创建采集配置。

LogCollector CRD 方式创建采集配置的操作简单便捷，但需要一定的工具学习成本，适用于熟悉 Kubernetes 和 CRD 的高阶用户。CRD 方式的采集原理请参考CRD 采集原理。
Sidecar 方式采集容器日志时，支持采集容器的文本日志，支持物理机部署 LogCollector 所支持的全部功能，支持单行、多行、分隔符、JSON 和完全正则等种采集模式。除各种采集配置默认附加的预留字段之外，日志服务还会对 LogCollector 采集到的容器日志添加以下预留字段，并默认为其创建索引。

容器文本日志的预留字段：

预留字段	说明
`__image_name__`	镜像名称。
`__container_name__`	容器名称。
`__container_ip__`	容器或 Pod 的 IP 地址。
`__pod_name__`	Pod 名称。
`__pod_uid__`	Pod 的唯一标识。
`__namespace__`	Pod 所属的 Namespace。

前提条件

已在 Kubernetes 集群中安装了 LogCollector。相关操作步骤请参考安装 LogCollector（Sidecar 方式）。
已在 Kubernetes 集群集群中安装了 LogCollector CRD。相关操作步骤请参考安装 LogCollector CRD。

限制说明

Sidecar 模式不支持采集业务容器的标准输出、标准错误。
通过 Sidecar 模式采集业务容器的文本日志时，需要从 LogCollector 容器和业务容器共享的日志目录中采集。需注意：
- 业务容器将日志写入共享目录中，LogCollector 周期性地扫描共享目录中的日志文件并采集日志。所以，控制台中配置的采集路径必须是 LogCollector 容器视角下的日志文件的路径。
- 推荐使用 emptyDir 挂载采集路径，挂载方式请参考 Sidecar 方式部署 LogCollector。
- 支持采集软链接，前提是 LogCollector 容器能够访问软链接指向业务容器的日志文件。
LogCollector 容器和业务容器所属于的 Pod 停止之后，LogCollector 容器将停止，进而停止采集业务容器的日志。如果此时 LogCollector 采集业务容器的日志出现延迟，则可能丢失停止采集之前的部分日志。
获取容器元数据信息，依赖于 LogCollector 容器中配置的环境变量。LogCollector 首先读取环境变量 LOG_COLLECTOR_ENV_TAGS，然后按照竖线（|）将其切割为多个环境变量键，最后读取这些环境变量键对应的值，并且在日志中携带键值对。所以，需要在 LogCollector 容器中设置所需要的容器元数据信息。需要注意的是，除了__namespace__、__node_ip__、__node_name__、__pod_ip__、__pod_name__ 五个容器元数据之外，其他元数据不能以双下划线（__）开头或结尾，否则采集时将被忽略。

创建 LogCollector 采集配置

LogCollector CRD 通过 yaml 文件的方式定义并下发 LogCollector 采集配置，创建并应用该文件后，日志服务会根据其配置自动创建一个新的 LogCollector CR，此 CR 对应一个 LogCollector 采集配置，并显示在日志服务控制台中。

说明

projectName、topicName 及 RuleName 均相同的多个 LogCollector CR 会被视为同一个采集配置，这些 CR 中仅最近一个被应用的 CR 指定的采集规则生效。请确保不存在 projectName、topicName 及 RuleName 均相同的 CR，以免最终生效的采集规则不符合预期。

创建 LogCollector 采集配置的操作步骤如下：

登录已经安装 LogCollector CRD 的 Kubernetes 集群。
创建一个 YAML 文件，用于指定采集配置。
请根据业务需求自行定义 YAML 文件名称，本文档以 access.yaml 为例。
```
vim access.yaml
```

编辑 YAML 文件，并在 YAML 文件中输入以下内容。

apiVersion: logging.vke.volcengine.com/v1alpha1 # 维持默认设置，无需修改。
kind: CollectRule                               # 维持默认设置，无需修改。
metadata:
  name: collectrule-sample                      # LogCollector CR 名称，在当前 Kubernetes 集群内唯一。
spec:
  projectName: project-name-sample              # 日志项目名称，若不存在则自动创建。
  topicName: topic-name-sample                  # 日志主题名称，若不存在则自动创建。
  lifeCycle: 30                                 # (可选)日志存储时长，仅在新建日志主题时生效。
  shardCount: 2                                 # (可选)日志分区数量，仅在新建日志主题时生效。
  hostGroupNames:                               # 采集配置绑定的机器组列表。
    - host-group-name-sample1                   # 机器组名称1
    - host-group-name-sample2                   # 机器组名称2
  rule:                                         # LogCollector 采集配置的详细定义，可参考本文档配置示例部分。
    RuleName: test
    Paths:
      - "/data/nginx/log/*/*/*.log"
    ......

其中，metadata 和 spec 部分的参数需要根据业务需求自行制定，参数说明如下：

参数	数据类型	是否必填	说明
name	String	是	LogCollector CR 名称，在当前 Kubernetes 集群内唯一。推荐设置为 rule 参数中指定的 RuleName，便于标识。
projectName	String	是	日志项目名称。如果指定的日志项目不存在，则自动创建日志项目。
topicName	String	是	日志主题名称。如果指定的日志主题不存在，自动创建日志主题。
hostGroupNames	Array of String	是	采集配置绑定的机器组名称列表。如果指定的机器组不存在，则自动创建机器标识类型的机器组，且对应的机器标识为机器组名称。
rule	Object	是	LogCollector 采集配置的详细定义，支持配置的参数及参数的详细说明请参考 CreateRule。其中，无需配置 TopicID，采集配置绑定的日志主题以 topicName 参数为准。常见场景下的 rule 配置请参考本文档配置示例部分。如果指定的采集配置名称（RuleName）不存在，日志服务会自动创建此采集配置；如果指定的采集配置已存在，则表示更新采集配置。指定的采集配置将自动绑定指定的机器组。
lifeCycle	Integer	否	创建日志主题时，指定日志在该日志主题中的存储时长，超过存储时长的过期日志会被自动清除。单位为天，默认为 30 天。取值范围为 1～3650，指定为 3650 天表示永久存储。
shardCount	Integer	否	创建日志主题时，指定日志分区的数量，取值范围为 1～10，默认创建 1 个分区。每个分区提供的写入能力为 5MiB/s、500 次/s，读取能力为 20 MiB/s、100 次/s。请在创建日志主题时合理规划分区，创建后暂不支持修改分区数量。
autoSplit	Boolean	否	创建日志主题时，指定是否开启分区的自动分裂功能。默认开启。 true：当写入的数据量连续 5 分钟超过已有分区服务能力时，日志服务会根据数据量自动分裂分区以满足业务需求，但分裂后的分区数量不可超出最大分裂数。最近 15 分钟内分裂出来的新分区不会自动分裂。 false（默认）：不开启分区的自动分裂。
maxSplitShard	Integer	否	创建日志主题时，指定分区的最大分裂数，即分区分裂后，所有分区的最大数量。取值范围为 1~50，默认为 50。
topic	Object	否	创建日志主题时，对日志主题的详细定义，支持配置的参数及参数的详细说明请参考 CreateTopic。其中，无需配置 TopicID 和 ProjectId，日志主题所属的日志项目以 projectName 参数为准。如果通过 topicName 参数指定的日志主题名称不存在，日志服务会自动创建此日志主题；如果指定的日志主题名称已存在，则不会更新此日志主题。说明如果指定 `lifeCycle/shardCount/autoSplit/maxSplitShard`，并且同时指定 `Ttl/ShardCount/AutoSplit/MaxSplitShard`，那么以 `lifeCycle/shardCount/autoSplit/maxSplitShard` 的配置为准。
index	Object	否	创建日志主题时，对索引配置的详细定义，支持配置的参数及参数的详细说明请参考 CreateIndex。其中，无需配置 TopicID，索引所属的日志主题以 topicName 参数为准。如果指定的日志主题的索引配置不存在，日志服务会自动创建此索引配置；如果指定的日志主题的索引配置已存在，则不会更新此索引配置。

执行以下命令，使 access.yaml 文件配置生效。
其中，access.yaml为文件名，请根据实际情况替换。
```
kubectl apply -f access.yaml
```

相关操作

修改采集配置

如果需要调整采集配置，推荐通过修改 LogCollector CR 的方式进行修改。成功操作后，日志服务会自动更新对应的 LogCollector CR，并刷新控制台显示的 LogCollector 采集配置。

说明

如果通过控制台直接调整采集配置，可能造成 LogCollector CR 与控制台采集配置信息不同步的问题。
不支持修改采集配置对应的 projectName、topicName 及 RuleName，一旦修改，日志服务会创建一个新的采集配置，并为其指定新的配置名称、日志项目或日志主题。

推荐的操作方式如下，此处以 YAML 文件名 access.yaml 为例。

登录已经安装 LogCollector CRD 的 Kubernetes 集群。
执行以下命令编辑指定 YAML 文件，修改采集配置。
```
vim access.yaml
```
执行以下命令应用文件，使新的配置生效。
```
kubectl apply -f access.yaml
```

删除采集配置

如果需要删除 LogCollector 采集配置，执行以下命令删除对应的 LogCollector CR 资源即可。其中，logcollector_cr_name 为 LogCollector CR 的名称，例如 collectrule-sample，请根据实际情况替换。

kubectl delete collectrule logcollector_cr_name

查看采集配置信息

成功创建并应用 LogCollector 采集配置后，通过控制台或 CRD 方式查看采集配置的详细信息。

控制台方式：在日志服务控制台中根据日志项目和采集配置名称查看对应的采集配置，操作方式请参考查看采集配置信息。
CRD 方式：查看 Kubernetes 集群的 LogCollector CR 列表，并根据 CR 名称查看指定 CR 的信息。操作步骤如下：
1. 登录到 Kubernetes 集群。
2. 执行以下命令，查看当前 Kubernetes 集群的 LogCollector CR 列表，并在列表中获取希望查看的 CR 名称。
```
kubectl get collectrule
```
  回显信息示例如下：
3. 执行以下命令，在回显信息的 spec 字段中查看指定 LogCollector CR 的详细定义。其中，logcollector_cr_name 为 LogCollector CR 的名称，例如 collectrule-sample，请根据实际情况替换。
```
kubectl get collectrule logcollector_cr_name -o yaml
```

查看 LogCollector CR 状态

通过 CRD 方式创建 LogCollector 采集配置后，如果控制台中未出现对应的采集配置，或修改 CR 后采集配置未同步更新，表示创建或修改采集配置创建失败，您可以在 Kubernetes 集群中查看 LogCollector CR 状态及描述，由此判断失败的原因。
执行以下命令查看指定查看 LogCollector CR 状态。其中，logcollector_cr_name 为 LogCollector CR 的名称，例如 collectrule1，请根据实际情况替换。

kubectl get collectrule logcollector_cr_name -o yaml

执行结果中的 status 字段表示 LogCollector CR 状态。其中：

字段		说明
projectId		日志项目 ID。
topicId		日志主题 ID。
hostGroupIds		机器组 ID 列表。
ruleId		采集规则 ID。
status	code	LogCollector CR 操作状态码。 200：已成功创建或修改 LogCollector 采集配置。非 200：创建或修改 LogCollector 采集配置失败。
status	message	在 code 为 200 以外的其他值时，此字段返回具体的报错内容。您可以根据 message 字段排查具体问题。

回显信息示例：

已成功创建或修改 LogCollector 采集配置：
创建或修改 LogCollector 采集配置失败：

配置示例

常见场景的采集配置示例如下。其中，metadata 和 spec 部分的参数说明请参考创建 LogCollector 采集配置。

分隔符模式采集容器文本日志

采集业务容器的 /var/logs/app 目录下的 access.log 文件中的日志，并且以分隔符采集模式来进行采集。
LogCollector 采集配置示例如下：

apiVersion: logging.vke.volcengine.com/v1alpha1
kind: CollectRule
metadata:
  name: collectrule-sample
spec:
  projectName: project-name-sample
  topicName: topic-name-sample
  lifeCycle: 30
  shardCount: 2
  hostGroupNames:
    - host-group-name-sample1
    - host-group-name-sample2
  rule:
    RuleName: test
    LogType: delimiter_log
    LogSample: 2022-01-01 error "this is a error message"
    Paths:
      - /var/logs/app/access.log
    ExtractRule:
      Delimiter: ' '
      Quote: '"'
      Keys:
        - time
        - level
        - message
      UnMatchUpLoadSwitch: true
      UnMatchLogKey: LogParseFailed

JSON 模式采集容器文本日志

采集业务容器的 /var/logs/app 目录下的 access.log 文件中的日志，并且以 JSON 模式进行采集。
LogCollector 采集配置示例如下：

apiVersion: logging.vke.volcengine.com/v1alpha1
kind: CollectRule
metadata:
  name: collectrule-sample
spec:
  projectName: project-name-sample
  topicName: topic-name-sample
  lifeCycle: 30
  shardCount: 2
  hostGroupNames:
    - host-group-name-sample1
    - host-group-name-sample2
  rule:
    RuleName: test
    LogType: json_log
    Paths:
      - /var/logs/app/access.log
    ExtractRule:
      UnMatchUpLoadSwitch: true
      UnMatchLogKey: LogParseFailed

后续步骤

创建采集配置之后，LogCollector 会根据指定规则开始监听容器内日志文件并采集日志，日志数据将保存在指定的日志主题中。
日志索引默认为关闭状态，您需要为日志主题开启索引功能，并配置索引，才能在控制台中对采集到的日志数据进行查询分析。