使用 ClickStack 监控 Systemd 日志 - ClickHouse Documentation

简而言之使用 OpenTelemetry Collector 的 journald receiver 在 ClickStack 中采集并可视化 systemd journal 中的日志。包含演示数据集和预置仪表板。

与现有系统集成

运行启用了 journald receiver 的 OpenTelemetry Collector，收集系统日志，并通过 OTLP 将其发送到 ClickStack，以监控现有 Linux 系统的 journald 日志。如果您想先测试此集成，而不修改现有设置，请跳转到演示数据集部分。

前置条件

正在运行的 ClickStack 实例
使用 systemd 的 Linux 系统 (Ubuntu 16.04+、CentOS 7+、Debian 8+)
在受监控系统上安装了 Docker 或 Docker Compose

获取 ClickStack API key

OpenTelemetry Collector 会将数据发送到 ClickStack 的 OTLP 端点，而该端点需要进行身份验证。

在你的 ClickStack URL 中打开 HyperDX (例如 http://localhost:8080)
创建账户，或按需登录
进入 Team Settings → API Keys
复制你的 摄取 API key

将其设置为环境变量：

export CLICKSTACK_API_KEY=your-api-key-here

验证 systemd journal 是否正在运行

请确保你的系统使用的是 systemd，并且存在 journal 日志：

# 检查 systemd 版本
systemctl --version

# 查看最近的 journal 条目
journalctl -n 20

# 检查 journal 磁盘占用情况
journalctl --disk-usage

如果 journal 仅存储在内存中，请启用持久化存储：

sudo mkdir -p /var/log/journal
sudo systemd-tmpfiles --create --prefix /var/log/journal
sudo systemctl restart systemd-journald

创建 OpenTelemetry Collector 配置

为 OpenTelemetry Collector 创建配置文件：

cat > otel-config.yaml << 'EOF'
receivers:
  journald:
    directory: /var/log/journal
    priority: info
    units:
      - sshd
      - nginx
      - docker
      - containerd
      - systemd

processors:
  batch:
    timeout: 10s
    send_batch_size: 10000
  
  resource:
    attributes:
      - key: service.name
        value: systemd-logs
        action: insert
      - key: host.name
        from_attribute: _HOSTNAME
        action: upsert
  
  attributes:
    actions:
      - key: unit
        from_attribute: _SYSTEMD_UNIT
        action: upsert
      - key: priority
        from_attribute: PRIORITY
        action: upsert

exporters:
  otlphttp:
    endpoint: ${CLICKSTACK_ENDPOINT}
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [journald]
      processors: [resource, attributes, batch]
      exporters: [otlphttp]
EOF

使用 Docker Compose 部署

journald receiver 需要 journalctl binary 才能读取 journal 文件。官方 otel/opentelemetry-collector-contrib image 默认不包含 journalctl。对于容器化部署，你可以直接在宿主机上安装 collector，或者构建包含 systemd utilities 的自定义 image。详情请参阅故障排查部分。

以下示例展示了如何将 OTel collector 与 ClickStack 一起部署：

services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring
  
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.115.1
    depends_on:
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
      - CLICKSTACK_ENDPOINT=http://clickstack:4318
    volumes:
      - ./otel-config.yaml:/etc/otelcol/config.yaml:ro
      - /var/log/journal:/var/log/journal:ro
      - /run/log/journal:/run/log/journal:ro
      - /etc/machine-id:/etc/machine-id:ro
    command: ["--config=/etc/otelcol/config.yaml"]
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

启动服务：

docker compose up -d

在 HyperDX 中验证日志

配置完成后，登录 HyperDX 并确认日志已开始流入：

进入搜索视图
将 source 设置为 Logs
按 service.name:systemd-logs 进行过滤
你应该能看到结构化日志条目，其中包含 unit、priority、MESSAGE、_HOSTNAME 等字段

演示数据集

对于希望在配置生产系统之前先测试 systemd 日志集成的用户，我们提供了一个预先生成的 systemd 日志样本数据集，其中包含逼真的日志模式。

下载样本数据集

下载样本日志文件：

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/systemd/systemd-demo.log

创建演示 collector 配置

为演示创建配置文件：

cat > systemd-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/systemd-demo/systemd-demo.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%Y-%m-%dT%H:%M:%S%z'
      - type: add
        field: attributes.source
        value: "systemd-demo"

service:
  pipelines:
    logs/systemd-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

使用演示数据运行 ClickStack

使用演示日志启动 ClickStack：

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/systemd-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/systemd-demo.log:/tmp/systemd-demo/systemd-demo.log:ro" \
  clickhouse/clickstack-all-in-one:latest

该演示使用 filelog receiver 处理文本日志，而不是使用 journald，从而避免容器中需要 journalctl。

在 HyperDX 中验证日志

ClickStack 运行后：

打开 HyperDX 并登录你的账户
进入搜索视图，并将 source 设置为 Logs
将时间范围设置为 2025-11-14 00:00:00 - 2025-11-17 00:00:00

时区显示HyperDX 会按浏览器的本地时区显示时间戳。演示数据覆盖 2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC)。更宽的时间范围可确保无论你身在何处，都能看到这些演示日志。

仪表盘与可视化

为帮助你快速开始使用 ClickStack 监控 systemd 日志，我们提供了 systemd journal 数据的核心可视化内容。

仪表盘配置

导入预置仪表盘

打开 HyperDX 并进入仪表盘页面
点击右上角省略号菜单中的 导入仪表盘

上传 systemd-logs-dashboard.json 文件，然后点击 完成导入

查看仪表盘

该仪表盘包含以下可视化内容：

日志量随时间变化趋势
按日志数量排名靠前的 systemd 单元
SSH 身份验证事件
服务故障
错误率

对于演示数据集，请将时间范围设置为 2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC) (可根据你的本地时区调整) 。

故障排查

HyperDX 中没有显示日志

检查日志是否已写入 ClickHouse：

docker exec clickstack clickhouse-client --query "
SELECT COUNT(*) as log_count
FROM otel_logs
WHERE ServiceName = 'systemd-logs'
"

如果没有结果，请查看 collector 日志：

docker logs otel-collector | grep -i "error\|journald" | tail -20

找不到 journalctl 错误

如果你看到 exec: "journalctl": executable file not found in $PATH： otel/opentelemetry-collector-contrib 镜像不包含 journalctl。你可以选择：

在主机上安装 collector：

wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.115.0/otelcol-contrib_0.115.0_linux_amd64.tar.gz
tar -xzf otelcol-contrib_0.115.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/
otelcol-contrib --config=otel-config.yaml

使用文本导出方式 (如演示所示) ，让 filelog receiver 读取 journald 导出的内容

后续步骤

为关键系统事件设置告警 (如服务故障、身份验证失败、OOM kill)
针对特定用例创建更多仪表盘 (如 SSH 安全监控、服务健康)
按特定 systemd 单元进行过滤，以减少噪声，并将重点放在重要服务上

投入生产环境

本指南使用独立的 OpenTelemetry Collector 读取 systemd 日志，并将其发送到 ClickStack 的 OTLP 端点，这是推荐的生产环境部署模式。对于包含多台主机的生产环境，请考虑：

在 Kubernetes 中将 collector 部署为 DaemonSet 守护进程集
在每台主机上将 collector 作为 systemd 服务运行
使用 OpenTelemetry Operator 进行自动化部署

有关生产环境的部署模式，请参阅使用 OpenTelemetry 摄取数据。

​与现有系统集成

前置条件

​获取 ClickStack API key

​验证 systemd journal 是否正在运行

​创建 OpenTelemetry Collector 配置

​使用 Docker Compose 部署

​在 HyperDX 中验证日志

​演示数据集

​下载样本数据集

​创建演示 collector 配置

​使用演示数据运行 ClickStack

​在 HyperDX 中验证日志

​仪表盘与可视化

​ 仪表盘配置

​导入预置仪表盘

​查看仪表盘

​故障排查

​HyperDX 中没有显示日志

​找不到 journalctl 错误

​后续步骤

​投入生产环境

与现有系统集成

获取 ClickStack API key

验证 systemd journal 是否正在运行

创建 OpenTelemetry Collector 配置

使用 Docker Compose 部署

在 HyperDX 中验证日志

演示数据集

下载样本数据集

创建演示 collector 配置

使用演示数据运行 ClickStack

在 HyperDX 中验证日志

仪表盘与可视化

仪表盘配置

导入预置仪表盘

查看仪表盘

故障排查

HyperDX 中没有显示日志

找不到 journalctl 错误

后续步骤

投入生产环境