简而言之使用 OTel filelog 接收器在 ClickStack 中采集并可视化 Nginx 访问日志 (JSON 格式) 。包含演示数据集和预构建仪表盘。
前置条件
- 正在运行的 ClickStack 实例
- 已安装 Nginx
- 具有修改 Nginx 配置文件的权限
配置 Nginx 日志格式
首先，将 Nginx 配置为以 JSON 格式输出日志，以便更轻松地进行解析。将以下日志格式定义添加到你的 nginx.conf 中：nginx.conf 文件通常位于：
- Linux (apt/yum)：
/etc/nginx/nginx.conf
- macOS (Homebrew)：
/usr/local/etc/nginx/nginx.conf 或 /opt/homebrew/etc/nginx/nginx.conf
- Docker：配置通常以卷的形式挂载
将以下日志格式定义添加到 http 块中：http {
log_format json_combined escape=json
'{'
'"time_local":"$time_local",'
'"remote_addr":"$remote_addr",'
'"request_method":"$request_method",'
'"request_uri":"$request_uri",'
'"status":$status,'
'"body_bytes_sent":$body_bytes_sent,'
'"request_time":$request_time,'
'"upstream_response_time":"$upstream_response_time",'
'"http_referer":"$http_referer",'
'"http_user_agent":"$http_user_agent"'
'}';
access_log /var/log/nginx/access.log json_combined;
error_log /var/log/nginx/error.log warn;
}
创建自定义 OTel collector 配置
ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry Collector 配置。自定义配置会与 HyperDX 通过 OpAMP 管理的基础配置合并。创建一个名为 nginx-monitoring.yaml 的文件，内容如下：receivers:
filelog:
include:
- /var/log/nginx/access.log
- /var/log/nginx/error.log
start_at: end
operators:
- type: json_parser
parse_from: body
parse_to: attributes
- type: time_parser
parse_from: attributes.time_local
layout: '%d/%b/%Y:%H:%M:%S %z'
- type: add
field: attributes.source
value: "nginx"
service:
pipelines:
logs/nginx:
receivers: [filelog]
processors:
- memory_limiter
- transform
- batch
exporters:
- clickhouse
- 从 Nginx 的标准位置读取日志
- 解析 JSON 日志记录
- 提取并保留原始日志时间戳
- 添加
source: Nginx 属性，以便在 HyperDX 中进行过滤
- 通过专用管道将日志发送到 ClickHouse exporter
- 您只需在自定义配置中定义新的接收器和管道
- 处理器 (memory_limiter、transform、batch) 和导出器 (clickhouse) 已在基础 ClickStack 配置中定义，您只需按名称引用它们
- time_parser operator 会从 Nginx 的 time_local 字段中提取时间戳，以保留原始日志时间
- 这些管道会通过现有处理器将数据从您的接收器路由到 ClickHouse exporter
配置 ClickStack 以加载自定义配置
如需在现有的 ClickStack 部署中启用自定义 collector 配置，您必须：
- 将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml
- 设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
- 挂载 Nginx 日志目录，以便 collector 能够读取这些日志
选项 1：Docker Compose
更新您的 ClickStack 部署配置：services:
clickstack:
# ... 现有配置 ...
environment:
- CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
# ... 其他环境变量 ...
volumes:
- ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
- /var/log/nginx:/var/log/nginx:ro
# ... 其他挂载卷 ...
选项 2：Docker Run (All-in-One 镜像)
如果使用 all-in-one 镜像并通过 docker run 运行：docker run --name clickstack \
-p 8080:8080 -p 4317:4317 -p 4318:4318 \
-e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
-v "$(pwd)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
-v /var/log/nginx:/var/log/nginx:ro \
clickhouse/clickstack-all-in-one:latest
确保 ClickStack collector 具备读取 nginx 日志文件所需的适当权限。在生产环境中，请使用只读挂载 (:ro) ，并遵循最小权限原则。
在 HyperDX 中验证日志
配置完成后，登录 HyperDX，确认日志已正常流入：
- 进入搜索视图
- 将 source 设为日志，并确认你能看到包含
request、request_time、upstream_response_time 等字段的日志条目。
你应会看到类似下面的内容：下载样本数据集
# 下载日志
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
- 具有逼真流量模式的日志条目
- 各种端点和 HTTP 方法
- 混合了成功请求和错误请求
- 逼真的响应时间和字节数
创建测试 collector 配置
创建一个名为 nginx-demo.yaml 的文件，内容如下：cat > nginx-demo.yaml << 'EOF'
receivers:
filelog:
include:
- /tmp/nginx-demo/access.log
start_at: beginning # 演示数据从开头读取
operators:
- type: json_parser
parse_from: body
parse_to: attributes
- type: time_parser
parse_from: attributes.time_local
layout: '%d/%b/%Y:%H:%M:%S %z'
- type: add
field: attributes.source
value: "nginx-demo"
service:
pipelines:
logs/nginx-demo:
receivers: [filelog]
processors:
- memory_limiter
- transform
- batch
exporters:
- clickhouse
EOF
使用演示配置运行 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)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
-v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
clickhouse/clickstack-all-in-one:latest
在 HyperDX 中验证日志
ClickStack 运行后：
- 打开 HyperDX 并登录你的账户 (你可能需要先创建账户)
- 进入搜索视图，并将数据源设置为
Logs
- 将时间范围设置为 2025-10-19 11:00:00 - 2025-10-22 11:00:00
你应当会在搜索视图中看到以下内容：时区显示HyperDX 会按浏览器的本地时区显示时间戳。演示数据的时间范围为 2025-10-20 11:00:00 - 2025-10-21 11:00:00 UTC。较大的时间范围可确保无论你位于何处都能看到这些演示日志。看到日志后，你可以将范围缩小到 24 小时，以获得更清晰的可视化效果。
导入预构建仪表盘
- 打开 HyperDX，进入 Dashboards 部分。
- 点击右上角省略号菜单下的“Import Dashboard”。
- 上传 nginx-logs-dashboard.json 文件，然后点击完成导入。
系统将创建一个已预先配置好所有可视化内容的仪表盘
对于演示数据集，请将时间范围设置为 2025-10-20 11:00:00 - 2025-10-21 11:00:00 (UTC) (请根据你的本地时区调整) 。导入的仪表盘默认不会预设时间范围。
- 验证环境变量 CUSTOM_OTELCOL_CONFIG_FILE 是否已正确设置
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
- 检查自定义配置文件是否已挂载到
/etc/otelcol-contrib/custom.config.yaml
docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
- 查看自定义 config 的内容，确认其可正常读取
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
tail -f /var/log/nginx/access.log
docker exec `<container>` cat /var/log/nginx/access.log
- 验证当前生效的配置中包含 filelog receiver
docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog
docker exec `<container>` cat /etc/otel/supervisor-data/agent.log
- 为关键指标 (错误率、延迟阈值) 配置告警
- 针对特定场景 (API 监控、安全事件) 创建更多仪表盘
本指南在 ClickStack 内置的 OpenTelemetry Collector 基础上进行了扩展，便于快速完成设置。对于生产环境部署，我们建议运行您自己的 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅发送 OpenTelemetry 数据。
