使用 ClickStack 监控 EC2 主机日志

使用 ClickStack 监控 EC2 主机日志

简而言之

使用 OpenTelemetry Collector 在 ClickStack 中收集并可视化 EC2 系统日志，同时自动富集 EC2 元数据 (实例 ID、区域、AZ、实例类型) 。包含演示数据集和预置仪表板。

​

与现有 EC2 实例集成

本节介绍如何在 EC2 实例上安装 OpenTelemetry Collector，以收集系统日志并将其发送到 ClickStack，同时自动进行 EC2 元数据富集。这种分布式架构可用于生产环境，并且能够扩展到多个实例。

在同一台 EC2 实例上运行 ClickStack？

如果 ClickStack 与要监控日志的目标运行在同一台 EC2 实例上，可以采用类似于 通用主机日志指南 中的一体化方案。将 /var/log 挂载到 ClickStack 容器中，并在自定义配置中添加 resourcedetection 处理器，以自动采集 EC2 元数据。本指南重点介绍更常见、也更适合生产部署的分布式架构。

如果想在配置生产实例之前先测试 EC2 主机日志集成，可以在”演示数据集”部分使用我们预先配置好的环境和示例数据进行测试。

前置条件

• ClickStack 实例已在运行 (可以是本地部署、云端或本机环境)
• EC2 实例已在运行 (Ubuntu、Amazon Linux 或其他 Linux 发行版)
• EC2 实例到 ClickStack 的 OTLP 端点具备网络连通性 (HTTP 使用 4318 端口，gRPC 使用 4317 端口)
• 可访问 EC2 实例元数据服务 (默认启用)

1. ​

   验证是否可访问 EC2 元数据

   在 EC2 实例上，验证元数据服务是否可访问：

   # 获取元数据令牌 (IMDSv2)
   TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
   
   # 验证实例元数据
   curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
   curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region
   curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-type
   

   你应该会看到实例 ID、区域和实例类型。如果这些命令执行失败，请确认：

   • 实例元数据服务已启用
   • IMDSv2 没有被安全组 (Security Group) 或网络 ACL 拦截
   • 你是在 EC2 实例本机上运行这些命令

   在实例内部可通过 http://169.254.169.254 访问 EC2 元数据。OpenTelemetry 的 resourcedetection 处理器会使用此端点，自动为日志补充云环境上下文信息。

2. ​

   验证 syslog 文件是否存在

   确认您的 EC2 实例正在写入 syslog 文件：

   # Ubuntu 实例
   ls -la /var/log/syslog
   
   # Amazon Linux / RHEL 实例
   ls -la /var/log/messages
   
   # 查看最近的日志条目
   tail -20 /var/log/syslog
   # 或
   tail -20 /var/log/messages
   
3. ​

   安装 OpenTelemetry Collector

   在 EC2 实例上安装 OpenTelemetry Collector Contrib 发行版：

   # 下载最新版本
   wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz
   
   # 解压并安装
   tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
   sudo mv otelcol-contrib /usr/local/bin/
   
   # 验证安装
   otelcol-contrib --version
   
4. ​

   创建 collector 配置

   在 /etc/otelcol-contrib/config.yaml 处为 OpenTelemetry Collector 创建配置文件：

   sudo mkdir -p /etc/otelcol-contrib
   

   根据您的 Linux 发行版选择相应的配置：

   现代 Linux（Ubuntu 24.04+）

   sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
   receivers:
     filelog/syslog:
       include:
         - /var/log/syslog
         - /var/log/**/*.log
       start_at: end
       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_type: gotime
           layout: '2006-01-02T15:04:05.999999-07:00'
         
         - type: add
           field: attributes.source
           value: "ec2-host-logs"
   
   processors:
     resourcedetection:
       detectors: [ec2, system]
       timeout: 5s
       override: false
       ec2:
         tags:
           - ^Name
           - ^Environment
           - ^Team
     
     batch:
       timeout: 10s
       send_batch_size: 10000
   
   exporters:
     otlphttp:
       endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
       headers:
         authorization: "${env:CLICKSTACK_API_KEY}"
   
   service:
     pipelines:
       logs:
         receivers: [filelog/syslog]
         processors: [resourcedetection, batch]
         exporters: [otlphttp]
   EOF
   

   旧版 Linux（Amazon Linux 2、RHEL 和较旧版本的 Ubuntu）

   sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
   receivers:
     filelog/syslog:
       include:
         - /var/log/messages
         - /var/log/**/*.log
       start_at: end
       operators:
         - type: regex_parser
           regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?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: '%b %d %H:%M:%S'
         
         - type: add
           field: attributes.source
           value: "ec2-host-logs"
   
   processors:
     resourcedetection:
       detectors: [ec2, system]
       timeout: 5s
       override: false
       ec2:
         tags:
           - ^Name
           - ^Environment
           - ^Team
     
     batch:
       timeout: 10s
       send_batch_size: 10000
   
   exporters:
     otlphttp:
       endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
       headers:
         authorization: "${env:CLICKSTACK_API_KEY}"
   
   service:
     pipelines:
       logs:
         receivers: [filelog/syslog]
         processors: [resourcedetection, batch]
         exporters: [otlphttp]
   EOF
   

   
   

   在配置中替换以下内容：

   • YOUR_CLICKSTACK_HOST：ClickStack 所在主机的主机名或 IP 地址
   • 如需进行本地测试，你可以使用 SSH 隧道 (请参阅故障排查部分)

   此配置：

   • 从标准路径读取系统日志文件 (Ubuntu 为 /var/log/syslog，Amazon Linux/RHEL 为 /var/log/messages)
   • 解析 syslog 格式，提取结构化字段 (时间戳、主机名、单元/服务、PID、消息)
   • 使用 resourcedetection 处理器自动识别并添加 EC2 元数据
   • 如有，还可选择包含 EC2 标签 (Name、Environment、Team)
   • 通过 OTLP HTTP 向 ClickStack 发送日志

   EC2 元数据富集

   resourcedetection 处理器会自动为每条日志添加以下属性：

   • cloud.provider: “aws”
   • cloud.platform: “aws_ec2”
   • cloud.region: AWS 区域 (例如：“us-east-1”)
   • cloud.availability_zone: 可用区 (例如：“us-east-1a”)
   • cloud.account.id: AWS 账户 ID
   • host.id: EC2 实例 ID (例如：“i-1234567890abcdef0”)
   • host.type: 实例类型 (例如：“t3.medium”)
   • host.name: 实例的主机名
5. ​

   设置 ClickStack API 密钥

   将 ClickStack API 密钥导出为环境变量：

   export CLICKSTACK_API_KEY="your-api-key-here"
   

   为了让它在重启后持续生效，请将其添加到 shell 配置文件中：

   echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
   source ~/.bashrc
   
6. ​

   运行 Collector

   启动 OpenTelemetry Collector：

   CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml
   

   用于生产环境

   将 collector 配置为以 systemd 服务方式运行，以便在系统启动时自动启动，并在发生故障时自动重启。详情请参阅 OpenTelemetry Collector 文档。

7. ​

   在 HyperDX 中验证日志

   采集器运行后，登录 HyperDX，确认日志已连同 EC2 元数据一起流入：

   1. 进入搜索视图
   2. 将 source 设置为 Logs
   3. 使用 source:ec2-host-logs 进行过滤
   4. 点击一条日志记录将其展开
   5. 确认你能在资源属性中看到 EC2 元数据：
      • cloud.provider
      • cloud.region
      • host.id (实例 ID)
      • host.type (实例类型)
      • cloud.availability_zone

​

演示数据集

对于希望在配置生产实例前先测试 EC2 主机日志集成的用户，我们提供了一个包含模拟 EC2 元数据的演示数据集。

1. ​

   下载示例数据集

   下载示例日志文件：

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log
   

   该数据集包括：

   • 系统启动过程
   • SSH 登录活动 (成功和失败的尝试)
   • 安全事件 (暴力破解攻击及 fail2ban 的响应)
   • 计划维护 (cron 作业、anacron)
   • 服务重启 (rsyslog)
   • 内核消息和防火墙活动
   • 正常运行与重要事件交织出现
2. ​

   创建测试 collector 的配置

   创建一个名为 ec2-host-logs-demo.yaml 的文件，并添加以下配置：

   cat > ec2-host-logs-demo.yaml << 'EOF'
   receivers:
     filelog/journal:
       include:
         - /tmp/host-demo/journal.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: "ec2-demo"
   
   processors:
     # 为演示模拟 EC2 元数据（无需真实 EC2 实例）
     resource:
       attributes:
         - key: service.name
           value: "ec2-demo"
           action: insert
         - key: cloud.provider
           value: "aws"
           action: insert
         - key: cloud.platform
           value: "aws_ec2"
           action: insert
         - key: cloud.region
           value: "us-east-1"
           action: insert
         - key: cloud.availability_zone
           value: "us-east-1a"
           action: insert
         - key: host.id
           value: "i-0abc123def456789"
           action: insert
         - key: host.type
           value: "t3.medium"
           action: insert
         - key: host.name
           value: "prod-web-01"
           action: insert
   
   service:
     pipelines:
       logs/ec2-demo:
         receivers: [filelog/journal]
         processors:
           - resource
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   EOF
   

   出于演示目的，我们通过 resource 处理器手动添加 EC2 元数据。在生产环境中，如果使用真实的 EC2 实例，请改用 resourcedetection 处理器，它会自动查询 EC2 元数据 API。

3. ​

   使用演示配置运行 ClickStack

   使用演示日志和配置运行 ClickStack：

   docker run --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)/ec2-host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
     docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest
   
4. ​

   在 HyperDX 中验证日志

   collector 运行后：

   1. 打开 HyperDX 并登录账户 (你可能需要先创建账户)
   2. 进入搜索视图，并将 source 设置为 Logs
   3. 将时间范围设置为 2025-11-10 00:00:00 - 2025-11-13 00:00:00
   4. 按 source:ec2-demo 过滤
   5. 展开一条日志，在资源属性中查看 EC2 元数据

   时区显示

   HyperDX 会按你浏览器的本地时区显示时间戳。演示数据覆盖 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC)。较大的时间范围可确保无论你位于何处，都能看到演示日志。看到日志后，你可以将范围缩小到 24 小时，以获得更清晰的可视化效果。

   你应会看到包含模拟 EC2 上下文的日志，包括：

   • 实例 ID: i-0abc123def456789
   • 区域: us-east-1
   • 可用区: us-east-1a
   • 实例类型: t3.medium

​

仪表盘和可视化

为了帮助你开始使用 ClickStack 监控 EC2 主机日志，我们提供了包含云上下文信息的关键可视化。

1. ​

   仪表盘配置

2. ​

   导入预置仪表盘

   1. 打开 HyperDX，进入“仪表盘”部分
   2. 点击右上角省略号菜单下的 Import Dashboard

   3. 上传 host-logs-dashboard.json 文件，然后点击 Finish Import
3. ​

   查看仪表盘

   仪表盘创建后，其中的所有可视化都已预先配置好：

   你可以按 EC2 上下文筛选仪表盘中的可视化：

   • cloud.region:us-east-1 - 显示特定区域的日志
   • host.type:t3.medium - 按实例类型过滤
   • host.id:i-0abc123def456 - 显示特定实例的日志

   对于演示数据集，请将时间范围设置为 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) (请根据你的本地时区进行调整) 。导入的仪表盘默认不会指定时间范围。

​

故障排查

​

日志中未显示 EC2 元数据

验证是否可以访问 EC2 元数据服务：

# 获取元数据令牌
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# 测试元数据端点
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

如果失败，请确认：

• 实例元数据服务已启用
• IMDSv2 未被安全组 (Security Group) 拦截
• 采集器运行在 EC2 实例本机上

检查采集器日志中是否有元数据相关错误：

# 如果作为 systemd 服务运行
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# 如果在前台运行，请检查 stdout

​

HyperDX 中未出现日志

确认 syslog 文件存在且正在写入：

ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog

检查采集器是否能读取日志文件：

cat /var/log/syslog | head -20

验证与 ClickStack 的网络连通性：

# 测试 OTLP 端点
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# 应收到响应（即使返回错误，也说明端点可达）

检查采集器日志中是否有报错：

# 如果在前台运行
# 在标准输出中查找错误信息

# 如果作为 systemd 服务运行
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

​

日志解析有误

请确认 syslog 格式：

对于 Ubuntu 24.04+：

# 应显示 ISO8601 格式：2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

对于 Amazon Linux 2 / Ubuntu 20.04：

# 应显示传统格式：Nov 17 14:16:16
tail -5 /var/log/messages

如果你的格式不一致，请根据所用的发行版，使用创建采集器配置部分中相应的配置选项卡。

​

Collector 无法作为 systemd 服务启动

检查服务状态：

sudo systemctl status otelcol-contrib

查看详细日志：

sudo journalctl -u otelcol-contrib -n 50

常见问题：

• 环境变量中的 API 密钥设置不正确
• 配置文件存在语法错误
• 读取日志文件时存在权限问题

​

后续步骤

• 为关键系统事件 (服务故障、身份验证失败、磁盘告警) 设置告警
• 按 EC2 元数据属性 (区域、实例类型、实例 ID) 进行过滤，以监控特定资源
• 将 EC2 主机日志与应用日志关联起来，以便进行更全面的故障排查
• 为安全监控 (SSH 尝试、sudo 使用情况、防火墙拦截) 创建自定义仪表盘

​

生产环境部署

本指南将 OpenTelemetry Collector 直接安装到 EC2 实例上，这是进行主机级监控时推荐的生产环境部署方式。若要在大量实例之间统一管理采集器，可考虑使用配置管理工具 (Ansible、Chef、Puppet) ；在 Kubernetes 环境中，则可使用 OpenTelemetry Operator。有关生产环境配置，请参阅发送 OpenTelemetry 数据。