版本：v25.09

日志扩展组件开发指南

特性介绍

日志系统作为可插拔扩展组件，独立部署运行在openFuyao平台中，为平台和用户提供了强大的日志筛选、搜索、查询以及告警等功能。

约束与限制

无。

环境准备

详细安装步骤请参见《安装指导》。

使用场景

使用场景概述

开发者需要在openFuyao集群管理面中自行安装日志扩展组件，在安装扩展组件时需要进行若干项的设置从而能够让日志系统更完美的适配自身业务场景。可以配置的选项有：

配置被采集日志从创建到现在时长限制与日志存储更新时间策略。
配置日志的采集源配置。
配置日志告警的自定义告警触发规则。

系统架构

日志系统业务层分为UI层，后端层，组件层。

UI层：用户可以在console-website上进行日志操作。

后端层：logging-operator以微服务的形式部署提供一些核心能力，包括日志筛选、搜索、查询、配置以及告警等功能。

组件层：组件层为日志系统提供关键的日志采集、存储和处理能力，并支持与后端层进行集成，使用户能够高效地执行日志操作。

图 1 日志扩展组件系统架构

接口说明

主要的接口说明如下表所示。

表 1 主要接口说明

接口	描述
PATCH /rest/logging/v1/update-config	添加新采集工作和修改已有的采集工作。
GET /rest/logging/v1/configmap	列举出当前日志采集组件全部工作流的采集源路径。

开发步骤

openFuyao平台

安装。

1.1 登录openFuyao平台，默认进入“总览”界面。在左侧导航栏选择“应用市场 > 应用列表”，进入“应用列表”界面。

1.2 在搜索框中输入“logging-package”，找到logging-package应用卡片。

1.3 单击“logging-package”的应用卡片，进入该应用的详情页。在详情页中单击右上角的“部署”。

1.4 在部署界面的“安装信息”模块中输入“应用名称”、“版本信息”和“命名空间”。其中命名空间指定在default即可。

图 2 安装信息

1.5 在“参数配置”模块中，Values.yaml的预览界面中可以看到具体的每一个用户可配字段的配置。

图 3 yaml配置

1.6 单击“确认”，即可成功部署该组件。

独立部署

安装

1.1 获取logging-package Helm包。

wget https://harbor.openfuyao.com/chartrepo/openfuyao-catalog/charts/logging-package-0.13.0.tgz

1.2 在参数配置的“values.yaml”中输入要部署的values信息。

1.3 使用Helm部署。

tar -zxf logging-package-0.13.0.tgz
helm install logging -n default ./logging-package

1.4 验证安装成功与访问。

确认logging package已经成功部署。

kubectl get pods -n default
kubectl get pods -n openfuyao-system
kubectl get pods -n loki

确认服务已经暴露。

kubectl get svc -n default | grep logging

访问logging-website界面。

http://<Node_IP>:<logging.service.nodePort>

配置被采集日志从创建到现在时长限制与日志存储更新时间策略。
- reject_old_samples_max_age: 该字段指日志采集器支持的日志最大时间跨度为168小时（默认配置），即从日志创建到当前事件的最长时长。当选择默认配置时，代表一个容器的日志创建超过7天之后，该日志就不会被采集组件采集到。
- retention_deletes_enabled: 该字段指是否开启日志自动删除老数据的功能，默认配置的false。当选择默认配置时，代表被采集到的日志会永久保存，并不会进行自动删除旧日志的策略。
- retention_period: 该字段指只有当retention_deletes_enabled开启的状态下才会生效，改配置定义了被采集日志在存储中储存超过一定时间单位后会被清除掉。
```
loki-stack:
  loki:
    config:
      limits_config:
        reject_old_samples_max_age: 168h
      table_manager:
        retention_deletes_enabled: false
        retention_period: 0s
```

配置日志的采集源配置。

该项配置定义了日志采集源的详细配置，明确了采集器工作的根目录路径。用户在配置时需要同时配置defaultVolumes和defaultVolumeMounts，要确定这两个值中的path和mountpath一致，填写的采集源路径是一个可读路径，如果路径不可读则会使该配置不生效。

说明：
采集源配置生效后，不可更改。

需要配置的内容如下:

loki-stack:
  namespace: loki
  promtail:
    defaultVolumes:
      - name: containers
        hostPath:
          path: /var/lib/docker/containers
      - name: pods
        hostPath:
          path: /var/log/pods
      - name: random
        hostPath:
          path: /var/log/random

    defaultVolumeMounts:
      - name: containers
        mountPath: /var/lib/docker/containers
        readOnly: true
      - name: pods
        mountPath: /var/log/pods
        readOnly: true
      - name: random
        mountPath: /var/log/random
        readOnly: true

如下介绍一个案例，该案例展示了添加一个新的名为new_example采集源的信息，删除了已有的采集源random:

loki-stack:
  namespace: loki
  promtail:
    defaultVolumes:
      - name: containers
        hostPath:
          path: /var/lib/docker/containers
      - name: pods
        hostPath:
          path: /var/log/pods
      - name: new_example
        hostPath:
          path: /var/tem/my-application

    defaultVolumeMounts:
      - name: containers
        mountPath: /var/lib/docker/containers
        readOnly: true
      - name: pods
        mountPath: /var/log/pods
        readOnly: true
      - name: new_example
        mountPath: /var/tem/my-application
        readOnly: true

配置日志告警的自定义告警触发规则。

配置日志告警规则时，要按照案例中的格式配置即可生效。如果配置格式不正确则无法被组件正常感知，在日志配置界面中将无法看到未生效的告警规则。如需创建新的告警规则，需要完整地配置alerting_groups的一个子项，创建告警详情时请遵循下列的缩进结构，具体配置项包括:

name: 告警规则的名称。
rules: 具体告警规则详情。
- alerts: 规则名称，与name保持一致。
- expr: 告警规则表达式，如果无效则该配置不生效。告警规则表达式配置规范请参见告警规则表达式官方配置说明。
- for: 告警持续时间。
- labels: 告警规则的标签，以key:value的形式出现在该项中。
- annotations: 告警规则的注解，以key:value的形式出现，value需要以字符串的形式出现。

loki-stack:
  loki:
    alerting_groups:
      - name: GenericHighErrorRate
        rules:
          - alert: GenericHighErrorRate
            expr: |
              sum by (job, instance) (rate({job=~".+"} |= "error" [5m])) > 0
            for: 5m
            labels:
              severity: critical
              loki: logging/k8s.io
            annotations:
              summary: "High error rate detected in {{ $labels.job }} instance {{ $labels.instance }}"
              description: "Job {{ $labels.job }} on instance {{ $labels.instance }} has a high rate of error logs."

      - name: GenericExceptionDetected
        rules:
          - alert: GenericExceptionDetected
            expr: |
              sum by (job, instance) (rate({job=~".+"} |= "Exception" [5m])) > 0
            for: 5m
            labels:
              severity: warning
              loki: logging/k8s.io
            annotations:
              summary: "Exception detected in {{ $labels.job }} instance {{ $labels.instance }}"
              description: "Job {{ $labels.job }} on instance {{ $labels.instance }} has logs containing 'Exception'."

      - name: GenericLogVolumeSpike
        rules:
          - alert: GenericLogVolumeSpike
            expr: |
              sum by (job, instance) (rate({job=~".+"}[5m])) > 1
            for: 5m
            labels:
              severity: warning
              loki: logging/k8s.io
            annotations:
              summary: "Log volume spike detected in {{ $labels.job }} instance {{ $labels.instance }}"
              description: "Job {{ $labels.job }} on instance {{ $labels.instance }} has a spike in log volume."

      - name: GenericErrorRateThresholdExceeded
        rules:
       - alert: GenericErrorRateThresholdExceeded
         expr: |
           (sum by (job, instance) (rate({job=~".+"} |= "error" [5m])) / sum by (job, instance) (rate({job=~".+"}[5m]))) > 0.05
            for: 5m
            labels:
              severity: critical
              loki: logging/k8s.io
            annotations:
              summary: "High error rate threshold exceeded in {{ $labels.job }} instance {{ $labels.instance }}"
              description: "Job {{ $labels.job }} on instance {{ $labels.instance }} has an error rate exceeding the threshold."
      - name: GenericServiceUnavailable
        rules:
          - alert: GenericServiceUnavailable
            expr: |
              sum by (job, instance) (rate({job=~".+"} |= "service unavailable" [5m])) > 0
            for: 5m
            labels:
              severity: critical
              loki: logging/k8s.io
            annotations:
              summary: "Service unavailable detected in {{ $labels.job }} instance {{ $labels.instance }}"
              description: "Job {{ $labels.job }} on instance {{ $labels.instance }} has logs indicating 'service unavailable'."
      - name: GenericApplicationStartupFailure
        rules:
          - alert: GenericApplicationStartupFailure
            expr: |
              sum by (job, instance) (rate({job=~".+"} |= "startup failure" [5m])) > 0
            for: 5m
            labels:
              severity: critical
              loki: logging/k8s.io
            annotations:
              summary: "Application startup failure detected in {{ $labels.job }} instance {{ $labels.instance }}"
              description: "Job {{ $labels.job }} on instance {{ $labels.instance }} has logs indicating 'startup failure'."

如何配置你的应用。

5.1 Kubernetes原生应用。

Kubernetes的原生应用在打印日志时，对于containerd的容器运行时环境，会把日志打印到默认路径下：/var/log/pods/{namespace}_{pod_name}_{pod_id}/{container_name}/0.log。这种情况用户无需对日志打印的设置有任何修改。日志采集系统会自动捕捉到这个路径下的日志，并保存到日志存储组件中。

5.2 用户自定义应用。

用户自定义的应用会在其容器内部打印日志，并有一个日志打印的详细路径。用户需要将该容器内路径映射到宿主机内的hostPath中，这个hostPath就代表着用户自定的应用打印日志的位置。将这个hostPath按照步骤3“配置日志的采集源配置”中配置，实现对该路径进行采集。安装部署完成后，在采集工作的配置中详细配置该路径下的文件名和应用任务名称即可。
```
 volumeMounts:
 - name: log-volume
   mountPath: /var/log
 volumes:
 - name: log-volume
  hostPath:
    path: /var/log/xxxx/xxxx
```

调测验证

当配置的采集任务名称和采集源路径与当前日志采集系统的工作流中列出的采集路径匹配时，表明该配置已成功生效。查看当前日志采集组件全部工作流的采集源路径的接口如下表。

表 2 调测接口说明

接口	描述
GET /rest/logging/v1/configmap	列举出当前日志采集组件全部工作流的采集源路径。

特性介绍​

约束与限制​

环境准备​

使用场景​

使用场景概述​

系统架构​

接口说明​

开发步骤​

openFuyao平台​

独立部署​

调测验证​