# 云原生日志采集插件
本章节主要介绍本地集群或附着集群云原生日志采集插件相关内容，[开启日志中心](https://support.huaweicloud.com/usermanual-ucs/ucs_01_0361.html)时会自动安装云原生日志采集插件，也可以参考本章节内容手动安装。华为云集群云原生日志采集插件相关内容请参见[云原生日志采集插件](https://support.huaweicloud.com/usermanual-cce/cce_10_0416.html)。
#### 插件简介
云原生日志采集插件（log-agent）是基于开源fluent-bit和opentelemetry构建的云原生日志采集插件，支持基于CRD的日志采集策略，可以根据您配置的策略规则，对集群中的容器标准输出日志、容器文件日志、节点日志及K8s事件日志进行采集与转发。安装云原生日志采集插件后，默认采集容器标准输出日志和集群内K8s事件。采集日志的详细使用方法请参见[收集数据面日志](https://support.huaweicloud.com/usermanual-ucs/ucs_01_0362.html)。
#### 日志采集可靠性说明
日志系统的核心功能在于记录业务组件的全生命周期状态数据（包括启动初始化、退出、运行时信息及异常事件等），主要服务于组件运行状态查看与故障根因分析等运维场景。
请注意标准输出流（stdout/stderr）及本地日志文件采用非持久化存储机制，其数据完整性受制于以下风险因素：
- 日志轮转压缩机制可能触发历史文件清除。
- Kubernetes Pod实例终止导致的临时存储卷回收。
- 节点存储空间限制触发的操作系统自动清理。
尽管云原生日志采集插件通过多级缓冲、优先级队列、断点续传等机制优化采集可靠性，但在以下场景仍存在日志采集丢失的可能：
- 业务日志吞吐量超过采集端处理能力。
- 业务Pod终止并立即被容器运行时回收。
- 日志采集器Pod运行异常。
以下是基于云原生日志管理的最佳实践建议，请您认真考虑并采纳：
- 请通过专用高可靠性通道记录并持久化关键业务数据（如金融交易）。
- 请勿在日志中进行记录客户信息、支付凭证、会话令牌等敏感数据。
 
#### 约束与限制
云原生日志采集插件有如下限制：
- 仅支持1.21及以上版本集群。
- 每个集群限制50条日志规则。
- 不采集.gz、.tar、.zip后缀类型的日志文件。
- 采集容器文件日志时，若节点存储模式为Device Mapper模式，路径配置必须为节点数据盘挂载路径。
- 若容器运行时为containerd模式，容器标准输出日志中的多行配置暂不生效。
- 每个集群限制单行日志采集速率不超过10000条/秒，多行日志不超过2000条/秒。
- 容器运行时间建议不小于1分钟，防止日志文件删除过快，无法及时采集。
 
#### 权限说明
云原生日志采集插件中的fluent-bit组件会根据用户的采集配置，读取各节点上容器标准输出、容器内文件日志以及节点日志并采集。
fluent-bit组件运行会使用到以下权限：
- CAP_DAC_OVERRIDE：忽略文件的 DAC 访问限制。
- CAP_FOWNER：忽略文件属主 ID 必须和进程用户 ID 相匹配的限制。
- DAC_READ_SEARCH：忽略文件读及目录搜索的 DAC 访问限制。
- SYS_PTRACE：允许跟踪任何进程。
 
 #### 本地集群或附着集群安装云原生日志插件前置授权
由于云原生日志插件需要访问LTS和AOM两个云服务，访问云服务需要对云原生日志插件进行鉴权，本地集群或附着集群云原生日志插件使用工作负载 Identity方式允许集群中的工作负载模拟IAM用户来访问云服务。
工作负载 Identity方式是将集群的公钥配置到IAM身份提供商中，并添加 ServiceAccount 与 IAM 账号映射规则。工作负载部署时挂载ServiceAccount对应的Token，使用此Token访问云服务，IAM 使用该公钥验证Token，从而无需直接使用 IAM 账号的 AK/SK 等信息，降低安全风险。
1. 获取本地集群或附着集群私钥签发的jwks，该公钥用于验证集群签发的 ServiceAccount Token。
   
   1. 使用kubectl连接本地集群或附着集群。
   
   2. 执行如下命令获取公钥。 **kubectl get --raw /openid/v1/jwks**
      返回结果为一个 json 字符串，是当前集群的签名公钥，用于访问身份供应商。
      ```
      {
          "keys": [
              {
                  "kty": "RSA",
                  "e": "AQAB",
                  "use": "sig",
                  "kid": "Ew29q....",
                  "alg": "RS256",
                  "n": "peJdm...."
              }
          ]
      }
      ```
      
   
   
   
   
2. 在 IAM 配置身份供应商，标志当前集群在 IAM 侧的身份。 
   1. 登录IAM控制台，查询本地集群或附着集群所在项目的ID，创建身份供应商，协议选择OpenID Connect。指定插件需要配置指定的身份供应商名称，具体请参见[表1]。用户组的权限配置具体操作请参见[用户组策略内容](https://support.huaweicloud.com/usermanual-iam/iam_01_0018.html)。
       表1log-agent身份供应商配置 
      | 插件名称      | 身份提供商名称                     | 客户端 ID               | namespace  | ServiceAccountName       | 用户组需要开通的最小权限                                       |
      |:---|:---|:---|:---|:---|:---|
      | log-agent | ucs-cluster-identity-{项目ID} | ucs-cluster-identity | monitoring | log-agent-serviceaccount | aom:alarm:\* lts:\*:\* |
         
      图1修改身份提供商信息   
      ![](https://support.huaweicloud.com/usermanual-ucs/zh-cn_image_0000002052396477.png "点击放大") 
   
   2. 单击"确定"，然后修改身份提供商信息，需要修改的信息如[表2]所示。随后创建身份转换规则，单击"创建规则"进行创建。
      图2修改身份提供商信息   
      ![](https://support.huaweicloud.com/usermanual-ucs/zh-cn_image_0000001918337014.png "点击放大")
       表2身份提供商配置参数说明 
      | 参数     | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
      |:---|:---|
      | 访问方式   | 选择"编程访问"。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
      | 配置信息   | - 身份供应商 URL：https://kubernetes.default.svc.cluster.local。  - 客户端 ID：指定插件需要配置指定的客户端ID，请参见[表1]。  - 签名公钥：本地集群或附着集群的 jwks，获取方法请参见[1]。涉及多个集群时，请用逗号分隔每个集群的keys数组内容。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
      | 身份转换规则 | 身份转换规则的作用将集群内的ServiceAccount和IAM用户组做映射。 - 属性：sub  - 条件：any_one_of  - 值： 值的格式为：system:serviceaccount:*Namespace* :*ServiceAccountName* 其中*Namespace* 请修改为需要创建ServiceAccount的命名空间，*ServiceAccountName*请修改为需要创建的ServiceAccount名称。 例如：值为system:serviceaccount:monitoring:log-agent-serviceaccount，表明在monitoring命名空间下创建一个名为log-agent的ServiceAccount，并映射到对应用户组，后续使用该 ServiceAccount获取的IAM Token就拥有了对应用户组的权限。 说明： 本地集群或附着集群中的相关插件需要配置指定的 ServiceAccountName 和用户组权限才能正常工作，请参见 [表1]。    |
         
      图3创建身份转换规则   
      ![](https://support.huaweicloud.com/usermanual-ucs/zh-cn_image_0000001921836504.png "点击放大") 
   
   3. 单击"确定"。
   
   
   
   
 
#### 本地集群或附着集群安装云原生日志采集插件
1. 登录[UCS控制台](https://console.huaweicloud.com/ucs/?#/aether/dashboard)，选择容器舰队，单击集群名称进入集群，在左侧导航栏中选择"插件中心"，在右侧找到**云原生日志采集插件**，单击"安装"。
2. 在安装插件页面，设置"规格配置"。 
   表3插件规格配置 
   | 参数   | 参数说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
   |:---|:---|
   | 插件规格 | 该插件可配置"小规格"、"大规格"或"自定义"规格。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
   | 实例数  | 选择上方插件规格后，显示插件中的实例数。 选择"自定义"规格时，您可根据需求调整插件实例数。                                                                                                                                                                                                                                                                                                                                                                                                                                        |
   | 容器   | log-agent插件包含以下容器，您可根据需求自定义调整规格： - fluent-bit：日志收集器，以DaemonSet形式安装在每个节点。  - cop-logs：负责采集侧配置文件生成及更新的组件。  - log-operator：负责解析及更新日志规则的组件。  - otel-collector：负责集中式日志转发的组件，将fluent-bit收集的日志转发到LTS。   |
      
   
   
3. 设置插件支持的"参数配置"。 
   Kubernetes事件上报AOM：采集Kubernetes事件并上报到应用运维管理 AOM，可在AOM配置事件告警规则。
   
   
4. 设置插件实例日志上报的"网络配置"。 
   - 公网接入：通过公网Internet接入，要求集群能够访问公网，具有弹性灵活、成本低、易接入的优势。公网接入要求集群能够访问公网，请确保集群已符合此条件，否则会接入失败。
   
   - 云专线/VPN接入：通过云专线（DC）或虚拟专用网络（VPN）服务将云下网络与云上虚拟私有云（VPC）连通，并利用VPC终端节点通过内网与容器智能分析建立连接，具有高速、低时延、安全的优势。详情见[本地集群或附着集群使用云专线/VPN上报日志](https://support.huaweicloud.com/usermanual-ucs/ucs_01_0367.html)。
   
   
   
   
5. 完成以上配置后，单击"安装"。
 
#### 组件说明
表4log-agent组件 
| 容器组件           | 说明                                | 资源类型       |
|:---|:---|:---|
| fluent-bit     | 轻量级的日志收集器和转发器，部署在每个节点上采集日志。       | DaemonSet  |
| cop-logs       | 负责生成采集文件的软链接，和fluent-bit运行在同一Pod。 | DaemonSet  |
| log-operator   | 负责生成内部的配置文件。                      | Deployment |
| otel-collector | 负责收集来自不同应用程序和服务的日志数据，集中后上报至LTS。   | Deployment |
   
#### 版本记录
表5云原生日志采集插件版本记录 
| 插件版本  | 支持的集群版本                                                                                                                                                                                                                                                                                                                                                                                                                                                | 更新特性          |
|:---|:---|:---|
| 1.4.1 | v1.21 v1.22 v1.23 v1.24 v1.25 v1.26 v1.27 v1.28 v1.29 v1.30 v1.31 v1.32 v1.33 | 第一次发布，支持本地集群。 |
   
#### 自定义事件上报AOM
log-agent插件会将所有Warning级别事件以及部分Normal级别事件上报到AOM。您也可以根据需求自行设置需要上报的事件，具体方法如下：
1. 在集群上执行以下命令，编辑当前的事件采集配置。 **kubectl edit logconfig -n kube-system default-event-aom**
   
2. 根据需要修改事件采集配置。
   ```
   apiVersion: logging.openvessel.io/v1
   kind: LogConfig
   metadata:
     annotations:
       helm.sh/resource-policy: keep
     name: default-event-aom
     namespace: kube-system
   spec:
     inputDetail:    #采集端配置
       type: event    #采集端类型，请勿修改
       event:
         normalEvents:    #Normal级别事件采集配置
           enable: true    #是否开启Normal级别事件采集
           includeNames:    #需要采集的事件名，不指定则采集所有事件
           - NotTriggerScaleUp
           excludeNames:    #不采集的事件名，不指定则采集所有事件
           - NotTriggerScaleUp
         warningEvents:    #Warning级别事件采集配置
           enable: true    #是否开启Warning级别事件采集
           includeNames:    #需要采集的事件名，不指定则采集所有事件
           - NotTriggerScaleUp
           excludeNames:    #不采集的事件名，不指定则采集所有事件
           - NotTriggerScaleUp
     outputDetail:
       type: AOM    #输出端类型，请勿修改
       AOM:
         events:
         - name: DeleteNodeWithNoServer    #事件名，必选
           nameCn: 废弃节点清理    #事件对应的中文名，不填则上报的事件直接显示英文
           resourceType: Namespace    #事件对应的资源类型
           severity: Major    #事件上报到AOM后的事件级别，默认Major。可选值：Critical：紧急；Major：重要；Minor：次要；Info：提示
   ```
   
 
#### log-agent事件说明
在log-agent插件的安装和运行阶段，log-operator组件会上报事件，您可以根据这些事件来判断安装是否成功，并确定故障原因。具体如[表6]所示：
 表6log-agent事件说明 
| 事件名称                          | 说明                               |
|:---|:---|
| InitLTSFailed                 | 初始化LTS日志组日志流失败                   |
| WatchAKSKFailed               | 监听AKSK失败                         |
| WatchAKSKSuccessful           | 监听AKSK成功                         |
| RequestLTSFailed              | 请求LTS接口失败                        |
| InitLTSSuccessful             | 初始化LTS日志组日志流成功                   |
| CreateWebhookConfigFailed     | 创建MutatingWebhookConfiguration失败 |
| CreateWebhookConfigSuccessful | 创建MutatingWebhookConfiguration成功 |
| StartServerSuccessful         | 开启监听成功                           |
| StartServerFailed             | 开启监听失败                           |
| StartManagerFailed            | 开启CRD监听失败                        |
| InjectAnnotationFailed        | annotation注入失败                   |
| InjectAnnotationSuccessful    | annotation注入成功                   |
| UpdateLogConfigFailed         | 更新logconfig信息失败                  |
| GetConfigListFailed           | 获取CR列表失败                         |
| GenerateConfigFailed          | 生成fluent-bit、otel配置失败            |
   
#### log-agent指标说明
log-agent插件的log-operator、fluent-bit和otel-collector组件提供了一系列指标，您可以使用AOM或Prometheus来监控这些指标，以便及时了解log-agent插件的运行情况，具体操作可参考[使用AOM监控自定义指标](https://support.huaweicloud.com/usermanual-cce/cce_10_0201.html)或[使用Prometheus监控自定义指标](https://support.huaweicloud.com/usermanual-cce/cce_10_0373.html)。详细的指标如下所述：
- log-operator组件（仅华为云集群） 端口：8443；地址：/metrics；协议：https
  表7指标 
  | 指标名                                        | 说明          | 类型        |
  |:---|:---|:---|
  | log_operator_aksk_latest_update_times      | AK/SK最后更新时间 | Gauge     |
  | log_operator_aksk_update_total             | AK/SK更新次数   | Counter   |
  | log_operator_send_request_total            | 发送请求数       | Counter   |
  | log_operator_webhook_listen_status         | Webhook监听状态 | Gauge     |
  | log_operator_http_request_duration_seconds | HTTP请求时延    | Histogram |
  | log_operator_http_request_total            | HTTP请求数     | Counter   |
  | log_operator_webhook_request_total         | Webhook请求数  | Counter   |
     
  
- fluent-bit组件 端口：2020；地址：/api/v1/metrics/prometheus；协议：http
  表8指标 
  | 指标名                                    | 说明                                          | 类型      |
  |:---|:---|:---|
  | fluentbit_filter_add_records_total     | 用于记录在过滤器中添加的记录总数                            | Counter |
  | fluentbit_filter_drop_records_total    | 用于记录被过滤掉的日志记录数量                             | Counter |
  | fluentbit_input_bytes_total            | 用于衡量Fluent Bit在处理日志数据时输入的总字节数               | Counter |
  | fluentbit_input_files_closed_total     | 用于记录关闭的文件总数                                 | Counter |
  | fluentbit_input_files_opened_total     | 用于监控Fluent Bit的文件输入插件（input plugin）打开的文件数量  | Counter |
  | fluentbit_input_files_rotated_total    | 用于记录Fluent Bit输入插件已经轮转的文件总数                 | Counter |
  | fluentbit_input_records_total          | 用于衡量 Fluent Bit 在输入插件中处理的记录数                | Counter |
  | fluentbit_output_dropped_records_total | 用于记录输出插件丢弃的记录数量                             | Counter |
  | fluentbit_output_errors_total          | 用于监控 Fluent Bit 的输出错误数量                     | Counter |
  | fluentbit_output_proc_bytes_total      | 用于监控 Fluent Bit 的输出插件（output plugin）处理的总字节数 | Counter |
  | fluentbit_output_proc_records_total    | 用于监控 Fluent Bit 的输出插件处理的记录数                 | Counter |
  | fluentbit_output_retried_records_total | 用于衡量 Fluent Bit 在输出数据时重试的次数                 | Counter |
  | fluentbit_output_retries_total         | 用于衡量 Fluent Bit 在发送数据到输出插件时发生重试的次数          | Counter |
  | fluentbit_uptime                       | Fluent Bit 运行的时间，通常以秒为单位                    | Counter |
  | fluentbit_build_info                   | 用于显示Fluent Bit的版本和构建信息                      | Gauge   |
     
  
- otel-collector组件 端口：8888；地址：/metrics；协议：http
  表9指标 
  | 指标名                                            | 说明                                                                        | 类型      |
  |:---|:---|:---|
  | otelcol_exporter_enqueue_failed_log_records    | 用于衡量OpenTelemetry Collector在将日志记录发送到下游系统时，由于某些原因无法成功发送的日志记录数量             | Counter |
  | otelcol_exporter_enqueue_failed_metric_points  | 用于衡量在将指标数据发送到后端时，由于某些原因导致无法成功发送的指标数据点的数量                                  | Counter |
  | otelcol_exporter_enqueue_failed_spans          | 用于衡量otelcol exporter在将span发送到后端时失败的次数                                     | Counter |
  | otelcol_exporter_send_failed_log_records       | 用于衡量日志记录发送失败的数量                                                           | Counter |
  | otelcol_exporter_sent_log_records              | 用于衡量OpenTelemetry Collector（otelcol）发送的日志记录数量                             | Counter |
  | otelcol_process_cpu_seconds                    | 用于度量进程CPU使用时间的指标，它表示进程在特定时间段内使用的CPU时间，单位为秒                                | Counter |
  | otelcol_process_memory_rss                     | 是OpenTelemetry中用于监控进程内存使用情况的一个指标。其中，rss代表Resident Set Size，即进程当前占用的物理内存大小 | Gauge   |
  | otelcol_process_runtime_heap_alloc_bytes       | 用于监控进程运行时堆内存分配的指标。它表示进程在运行时分配的堆内存的总字节数。                                   | Gauge   |
  | otelcol_process_runtime_total_alloc_bytes      | 用于衡量进程在运行时分配的总字节数                                                         | Counter |
  | otelcol_process_runtime_total_sys_memory_bytes | 用于衡量进程在运行时使用的系统内存总量，单位为字节。                                                | Gauge   |
  | otelcol_process_uptime                         | 指OpenTelemetry收集器进程的运行时间，以秒为单位。                                           | Counter |
  | otelcol_receiver_accepted_log_records          | 用于衡量OpenTelemetry收集器接收并成功处理的日志记录数量                                        | Counter |
  | otelcol_receiver_refused_log_records           | 用于衡量接收器（receiver）拒绝接收的日志记录数量                                              | Counter |