System Logger 镜像文档

镜像概述与主要用途

System Logger 是 K8ssandra 项目的核心组件之一。K8ssandra 是一套云原生解决方案集合，旨在简化 Apache Cassandra 在 Kubernetes 环境中的部署与运维，包含 Apache Cassandra 数据库引擎、反熵修复服务、可观测性集成及基于 Kubernetes API 的备份/恢复能力。

System Logger 作为日志辅助工具，主要用途是为 Kubernetes 上的 Apache Cassandra 集群提供日志收集、解析与转发功能，支撑 K8ssandra 的可观测性体系，帮助用户集中管理集群日志，实现问题排查与状态监控。

核心功能与特性

核心功能

• Cassandra 日志集中采集：针对 Apache Cassandra 节点的系统日志、业务日志及调试日志进行统一收集。
• Kubernetes 环境适配：与 Kubernetes 容器运行时深度集成，支持动态扩缩容场景下的日志跟踪。
• 可观测性集成：作为 K8ssandra 可观测性钩子的关键组件，为日志监控、告警分析提供数据输入。

主要特性

• 轻量级设计：资源占用低，不影响 Cassandra 集群核心性能。
• 结构化日志处理：支持 Cassandra 特定日志格式解析，输出结构化日志数据。
• 原生 Kubernetes 配置：通过 Kubernetes API 对象（如 ConfigMap、Secret）实现配置管理。

使用场景与适用范围

典型使用场景

• Cassandra 集群日志管理：在 Kubernetes 环境中部署的 Apache Cassandra 集群，需统一收集多节点日志时。
• 集群运行状态监控：通过日志分析识别节点异常（如连接故障、性能瓶颈、数据一致性问题）。
• 故障排查与调试：开发或运维人员需通过日志定位 Cassandra 集群运行问题时。

适用范围

• 环境要求：Kubernetes 集群（兼容 K8ssandra 支持的版本）。
• 用户群体：Cassandra 集群运维工程师、DevOps 人员、需监控集群状态的开发团队。
• 集群规模：适用于从测试环境小型集群到生产环境大规模集群的日志管理需求。

使用方法与配置说明

Docker 运行示例

System Logger 通常作为 K8ssandra 部署的一部分运行，以下为基础 Docker 运行示例（需结合实际集群配置调整）：

docker run --name system-logger \
  --network=k8ssandra-network \  # 接入 K8ssandra/Cassandra 集群网络
  -v /var/log/cassandra:/var/log/cassandra:ro \  # 挂载 Cassandra 日志目录（只读）
  -e CASSANDRA_CLUSTER_NAME=my-cluster \  # 目标 Cassandra 集群名称
  -e LOG_LEVEL=info \  # 日志级别
  k8ssandra/system-logger:latest  # 具体镜像标签需匹配 K8ssandra 版本

Docker Compose 配置示例

非生产环境测试部署可参考以下 docker-compose 配置（需与 Cassandra 容器共享日志卷）：

version: '3.8'
services:
  system-logger:
    image: k8ssandra/system-logger:latest
    container_name: system-logger
    networks:
      - k8ssandra-net
    volumes:
      - cassandra-logs:/var/log/cassandra:ro  # 共享 Cassandra 日志卷
    environment:
      - CASSANDRA_CLUSTER_NAME=test-cluster
      - LOG_DESTINATION=stdout  # 日志输出目标（如 stdout 或外部系统）
      - LOG_PATHS=/var/log/cassandra/*.log  # 日志文件路径

networks:
  k8ssandra-net:
    driver: bridge

volumes:
  cassandra-logs:  # 需与 Cassandra 服务共享此卷

配置参数与环境变量

System Logger 主要通过环境变量配置，以下为常用配置项（详细参数请参考 K8ssandra 官方文档）：

注意事项

1. 权限要求：容器需具备读取 Cassandra 日志目录的权限，建议通过 ro（只读）模式挂载日志卷。
2. 版本兼容性：需使用与 K8ssandra 部署版本匹配的 System Logger 镜像，版本不匹配可能导致功能异常。
3. 生产环境部署：生产环境中建议通过 K8ssandra Operator 或 Helm Chart 部署，以利用 Kubernetes 原生调度与自愈能力。