SigNoz v0.146.0 配置参数详解
SigNoz v0.146.0 配置参数详解：三层配置体系（Foundry casting/otel-collector ingester.yaml/SIGNOZ_* 环境变量）逐节拆解，覆盖 OTLP 接收端点、batch 与 spanmetrics 处理器、四类 ClickHouse exporter、server 环境变量映射规则与默认值、ClickHouse/Keeper 连接参数，并实测 debug exporter 改配生效全流程（2026-10-20）。
SigNozSigNoz监控2026/10/20
SigNoz v0.146.0 配置参数详解
目标：逐节拆解 SigNoz v0.146.0 渲染产物的三类配置——otel-collector 的
ingester.yaml（receivers/processors/exporters/pipelines）、SigNoz Server 的SIGNOZ_*环境变量、ClickHouse 与 Keeper 的连接参数，并做一次"改配置→重启→验证生效"的实配实测；全部参数值取自本专栏 B2 实测部署的渲染产物（2026-10-20），关键改动均有运行时回显证据。
一、配置体系总览
v0.146.0 的配置分三层，修改入口各不相同：
| 层 | 文件/载体 | 渲染来源 | 生效方式 |
|---|---|---|---|
| 部署编排 | compose.yaml | Foundry casting.yaml + spec.patches | docker compose up -d 重建 |
| 数据接入 | ingester/ingester.yaml（挂载为 collector 容器 /etc/otel-collector-config.yaml） | Foundry 渲染产物 | docker compose restart ingester |
| 服务端/存储 | SIGNOZ_* 环境变量（compose environment:）、telemetrystore/clickhouse/config-0-0.yaml、telemetrykeeper/clickhousekeeper/keeper-0.yaml | Foundry 渲染产物 | 改后重建对应服务 |
注意：
forge每次执行会覆盖pours/下的渲染产物，定制要么写进casting.yaml的spec.patches（推荐），要么改完产物后不再重跑 forge。
二、otel-collector 配置：ingester.yaml 逐节详解
这是数据接入的核心文件，v0.146.0 默认渲染值全文如下（实测提取），后续小节逐节解释：
2.1 receivers：OTLP 接入端点
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
| 参数 | 默认值 | 说明 |
|---|---|---|
otlp.protocols.grpc.endpoint | 0.0.0.0:4317 | OTLP gRPC 接入；B2 实测映射宿主 8147 |
otlp.protocols.http.endpoint | 0.0.0.0:4318 | OTLP HTTP（JSON/protobuf）；实测映射宿主 8148，`POST /v1/traces |
2.2 processors：批处理与信号加工
processors:
batch:
send_batch_max_size: 55000
send_batch_size: 50000
timeout: 5s
batch/meter:
send_batch_max_size: 25000
send_batch_size: 20000
timeout: 5s
signozspanmetrics/delta:
aggregation_temporality: AGGREGATION_TEMPORALITY_DELTA
dimensions:
- default: default
name: service.namespace
- default: default
name: deployment.environment
- name: signoz.collector.id
- name: service.version
dimensions_cache_size: 100000
enable_exp_histogram: true
latency_histogram_buckets: [100us, 1ms, 2ms, 6ms, 10ms, 50ms, 100ms, 250ms,
500ms, 1000ms, 1400ms, 2000ms, 5s, 10s, 20s, 40s, 60s]
metrics_exporter: signozclickhousemetrics
metrics_flush_interval: 60s
signozspanmapper:
groups: []
signozllmpricing:
attrs: {...} # gen_ai.usage.* 到成本属性的映射（LLM 观测计费）
要点（对应 B2/C1 实测行为）：
batch.timeout: 5s解释了"OTLP 发送后约 5 秒内数据才可见"的窗口；调小可降低查询延迟，但会放大 ClickHouse 写入次数。signozspanmetrics/delta把 span 自动转成 RED 指标（延迟直方图 17 桶到 60s），这是 SigNoz"发 trace 就有服务监控图"的原因；metrics_flush_interval: 60s表示 span 指标最长 60s 聚合一次。signozllmpricing是 v0.146 内建的 LLM 调用成本核算处理器（gen_ai.usage.*语义约定）。
2.3 connectors：用量计量
connectors:
signozmeter:
dimensions: [service.name, deployment.environment, host.name]
metrics_flush_interval: 1h
按资源维度统计三类信号的数据量，1 小时输出一次，供用量账单/配额使用。
2.4 exporters：ClickHouse 写入
exporters:
clickhouselogsexporter:
dsn: tcp://signoz-telemetrystore-clickhouse-0-0:9000/signoz_logs
sending_queue: {enabled: false}
timeout: 45s
use_new_schema: true
clickhousetraces:
datasource: tcp://signoz-telemetrystore-clickhouse-0-0:9000/signoz_traces
low_cardinal_exception_grouping: ${env:LOW_CARDINAL_EXCEPTION_GROUPING}
...
signozclickhousemetrics:
dsn: tcp://signoz-telemetrystore-clickhouse-0-0:9000/signoz_metrics
signozclickhousemeter:
dsn: tcp://signoz-telemetrystore-clickhouse-0-0:9000/signoz_meter
metadataexporter:
dsn: tcp://signoz-telemetrystore-clickhouse-0-0:9000/signoz_metadata
enabled: true
| 参数 | 说明 |
|---|---|
dsn/datasource | ClickHouse 原生端口 9000 + 目标库；四类信号分库写入（logs/traces/metrics/meter），元数据单独 signoz_metadata |
use_new_schema: true | 启用 v3/v4 新表族（distributed_signoz_index_v3、distributed_logs_v2、distributed_samples_v4），与迁移工具版本强相关，勿随意关闭 |
sending_queue.enabled: false | 单机栈直接同步写；ClickHouse 抖动时可在发送侧加重试队列 |
low_cardinal_exception_grouping | 异常分组按低基数字段聚合，值经环境变量注入 |
2.5 extensions 与 service.pipelines
extensions:
pprof: {endpoint: 0.0.0.0:1777} # 性能剖析端口（容器内）
signoz_health_check: {endpoint: 0.0.0.0:13133} # collector 健康检查
service:
extensions: [signoz_health_check, pprof]
pipelines:
logs: {receivers: [otlp], processors: [batch], exporters: [clickhouselogsexporter, signozmeter, metadataexporter]}
metrics: {receivers: [otlp], processors: [batch], exporters: [signozclickhousemetrics, signozmeter, metadataexporter]}
metrics/meter: {receivers: [signozmeter], processors: [batch/meter], exporters: [signozclickhousemeter]}
traces: {receivers: [otlp], processors: [signozspanmetrics/delta, signozspanmapper, signozllmpricing, batch], exporters: [clickhousetraces, signozmeter, metadataexporter]}
telemetry:
logs: {encoding: json}
traces 管线的处理器顺序即数据加工顺序：先转 span 指标、再补全 span 映射、再算 LLM 成本，最后批处理落库。
2.6 collector 容器的环境变量
environment:
- SIGNOZ_OTEL_COLLECTOR_CLICKHOUSE_DSN=tcp://signoz-telemetrystore-clickhouse-0-0:9000
- SIGNOZ_OTEL_COLLECTOR_TIMEOUT=10m
command: /signoz-otel-collector migrate sync check && /signoz-otel-collector --config=/etc/otel-collector-config.yaml --manager-config=/etc/opamp-config.yaml --copy-path=/var/tmp/collector-config.yaml
opamp.yaml 只有一行 server_endpoint: ws://signoz-signoz-0:4320/v1/opamp——collector 通过 OpAMP 协议向 SigNoz Server 上报自身状态并接收配置下发，--copy-path 是实际生效配置的落盘路径。
三、SigNoz Server：SIGNOZ_* 环境变量
3.1 环境变量到配置键的映射规则
Server 端配置完全由 SIGNOZ_ 前缀环境变量驱动：单下划线是键名的一部分，双下划线 __ 表示嵌套一层（来源：pkg/config/envprovider/provider.go，v0.146.0 源码）。例如：
SIGNOZ_SQLSTORE_POSTGRES_DSN → sqlstore.postgres.dsn
SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN → telemetrystore.clickhouse.dsn
SIGNOZ_TELEMETRYSTORE_PROVIDER → telemetrystore.provider
SIGNOZ_SQLSTORE_PROVIDER → sqlstore.provider
3.2 compose 中实测注入的四个变量
signoz-signoz-0:
environment:
- SIGNOZ_SQLSTORE_POSTGRES_DSN=postgres://signoz:signoz@signoz-metastore-postgres-0:5432/signoz?sslmode=disable
- SIGNOZ_SQLSTORE_PROVIDER=postgres
- SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN=tcp://signoz-telemetrystore-clickhouse-0-0:9000
- SIGNOZ_TELEMETRYSTORE_PROVIDER=clickhouse
3.3 内置默认值（源码核对）
不设置时 Server 取用的关键默认（pkg/apiserver/config.go，v0.146.0）：
| 配置键 | 默认值 | 说明 |
|---|---|---|
apiserver.address | 0.0.0.0:8080 | Web+API 监听地址（B2 映射宿主 8143） |
apiserver.read_timeout | 60s | HTTP 读超时 |
apiserver.timeout.default | 60s | 请求默认上下文超时 |
apiserver.timeout.max | 600s | 请求最大超时 |
apiserver.timeout.excluded_routes | /api/v1/logs/tail、/api/v3/logs/livetail、/api/v1/export_raw_data | 长连接路由不受超时约束 |
3.4 ClickHouse 连接参数速查
SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN 为 Go sqlclient DSN，格式 tcp://<host>:<port>[/<database>]：
- Server 直连原生 TCP 9000（不是 HTTP 8123）；
- 库名由各子系统内部选择（signoz_logs/signoz_metrics/signoz_traces/signoz_metadata），DSN 不写库即默认库；
SIGNOZ_OTEL_COLLECTOR_CLICKHOUSE_DSN（collector 与 migrator 用）同格式，实测值tcp://signoz-telemetrystore-clickhouse-0-0:9000。
四、ClickHouse 与 Keeper 配置要点
4.1 config-0-0.yaml（渲染产物）
| 参数 | 默认值 | 说明 |
|---|---|---|
http_port / tcp_port | 8123 / 9000 | HTTP 与原生端口（B2 映射宿主 8146） |
interserver_http_port | 9009 | 副本间 HTTP |
listen_host | 0.0.0.0 | 监听全部网卡 |
remote_servers.cluster | 单分片单副本（host=本容器，port 9000） | 集群名 cluster，宏 shard: "00"、replica: "00" |
profiles.default.log_queries | 1 | 记录 query_log |
query_log/trace_log/text_log 等 TTL | event_date + 1 DAY DELETE | 各类系统日志表 1 天自动清理 |
user_scripts_path | /var/lib/clickhouse/user_scripts/ | histogram-quantile UDF 所在（user-scripts 初始化容器注入） |
4.2 keeper-0.yaml
keeper_server:
tcp_port: 9181 # 四字命令端口（健康检查用 clickhouse-keeper-client -p 9181 -q ls）
raft_configuration: 单节点 server id=0, port=9234
coordination_settings:
operation_timeout_ms: 10000
session_timeout_ms: 30000
snapshot_distance: 100000
snapshots_to_keep: 3
ClickHouse 通过 distributed_ddl.path: /clickhouse/task_queue/ddl 与 Keeper 协作（建分布式表时队列化 DDL）。
五、实配实测：向 logs 管线加 debug exporter
5.1 改配置
在渲染产物 pours/deployment/ingester/ingester.yaml 中新增 exporter 并挂到 logs 管线：
exporters:
debug:
verbosity: detailed
service:
pipelines:
logs:
exporters:
- clickhouselogsexporter
- debug # 新增
- signozmeter
- metadataexporter
5.2 重启并验证
cd /opt/signoz-stack/pours/deployment
docker compose restart ingester
# Container signoz-01460-stack-ingester-1 Started
docker logs signoz-01460-stack-ingester-1 --since 2m | grep 'Everything is ready'
# {"level":"info",...,"msg":"Everything is ready. Begin running and processing data.",...}
重新向 :8148/v1/logs 发送上一节的日志样例后，collector 自身日志立即出现 debug exporter 的完整导出（实测节选）：
ResourceLog #0
Resource attributes:
-> service.name: Str(frontend-api)
LogRecord #0
SeverityText: INFO
Body: Str(order checkout completed amount=258.00)
Attributes:
-> order.id: Str(SO-20261020-0001)
Trace ID: 5b8efff798038103d269b633813fc60c
otelcol.component.id: "debug"
结论：ingester.yaml 修改无需改 compose，restart ingester 即生效；这是排障与数据管道验证最快的手段（验证完移除 debug 段再 restart 还原）。
六、配置校验与常见问题
- 配置写错怎么发现：collector 启动即做 schema 校验，错误直接 fatal。实测把一个非法 endpoint 配置喂给二进制：
failed to start collector service: failed to start : invalid configuration: no exporter configuration specified in config容器会反复重启，docker compose logs ingester即可定位。 - 改了 forge 产物又被覆盖：所有定制收敛到
casting.yaml的spec.patches（编排层）或独立维护配置 diff（接入层），重跑 forge 后重新套用。 use_new_schema相关表不存在：说明 migrator 未跑完（migrate sync up失败），查 migrator 日志并确认 ClickHouse/Keeper healthy 后重试。- 90 天长周期存储：默认 TTL 在表级定义，需调整时改 ClickHouse 表 TTL（C1 不展开，属 D1 查询篇范畴）。
章节目录