SigNoz v0.146.0 常用 CLI 命令详解

目标：沉淀 SigNoz v0.146.0 日常运维三类命令——clickhouse-client 直查 signoz 各库表、otel-collector（signoz-otel-collector）的启动参数与 migrate 子命令、SigNoz Server 的 HTTP API（curl），外加 Foundry/compose 运维命令；全部命令均在 2026-10-20 的实测环境中逐条执行并保留真实回显。

一、clickhouse-client：直查遥测数据

1.1 连接方式

方式	命令	适用
原生端口（容器网内/本机）	`clickhouse-client --host <CH主机> --port 9000`	在 ClickHouse 节点上执行，collector/migrator 即此方式写入
HTTP 端口	`curl 'http://<CH主机>:8123/?query=SELECT+1'`	无客户端二进制时；B2 实测映射宿主 8146
容器内客户端	`docker exec signoz-telemetrystore-clickhouse-0-0 clickhouse-client --query "..."`	部署后即时验证

冒烟：curl -s 'http://localhost:8146/?query=SELECT+1' 返回 1.。

1.2 库表地图（v0.146.0 实测）

SHOW DATABASES;
-- signoz_logs / signoz_meter / signoz_metadata / signoz_metrics / signoz_traces / system

常用分布式表（查询一律打 distributed_ 前缀表，自动路由到本地表）：

库	表	内容
signoz_traces	`distributed_signoz_index_v3`	span 主索引（trace_id/name/duration/属性）
signoz_traces	`distributed_signoz_error_index_v2`	异常事件索引
signoz_traces	`distributed_signoz_spans`	span 原始数据
signoz_traces	`distributed_top_level_operations`	顶层操作（服务入口聚合）
signoz_logs	`distributed_logs_v2`	日志主表
signoz_logs	`distributed_tag_attributes_v2` / `logs_attribute_keys`	属性/字段键目录
signoz_metrics	`distributed_samples_v4`	指标原始样本
signoz_metrics	`distributed_samples_v4_agg_5m/30m`	5 分钟/30 分钟预聚合
signoz_metrics	`distributed_metadata`	指标元数据（名称/类型）
signoz_metadata	`distributed_attributes_metadata` 等	属性元数据与 schema 演进

计数实测（部署 + 一轮 OTLP 测试数据后）：

SELECT count() FROM signoz_traces.distributed_signoz_index_v3;   -- 2
SELECT count() FROM signoz_logs.distributed_logs_v2;             -- 2
SELECT count() FROM signoz_metrics.distributed_samples_v4;       -- 44（含 collector 自监控指标）

1.3 高频查询模板（均实测）

按 trace_id 还原一次调用链：

SELECT timestamp, name, kind_string, duration_nano, hasError
FROM signoz_traces.distributed_signoz_index_v3
WHERE trace_id = '5b8efff798038103d269b633813fc60c'
ORDER BY timestamp
FORMAT Vertical;
-- 实测：name=POST /checkout, kind_string=Server, duration_nano=355330438, hasError=0

最近 1 小时最慢的 10 个服务端 span：

SELECT service_name, name, count() AS cnt, max(duration_nano)/1e6 AS p_max_ms
FROM signoz_traces.distributed_signoz_index_v3
WHERE timestamp > now() - INTERVAL 1 HOUR AND kind_string = 'Server'
GROUP BY service_name, name
ORDER BY p_max_ms DESC LIMIT 10;

最近错误 span（告警排查入口）：

SELECT timestamp, service_name, name, exception_message
FROM signoz_traces.distributed_signoz_error_index_v2
WHERE timestamp > now() - INTERVAL 1 HOUR
ORDER BY timestamp DESC LIMIT 10;

按服务查日志（属性在 Map 列里）：

SELECT timestamp, severity_text, body
FROM signoz_logs.distributed_logs_v2
WHERE resources_string['service.name'] = 'frontend-api'
  AND timestamp > now() - INTERVAL 1 HOUR
ORDER BY timestamp DESC LIMIT 20;

模糊检索日志正文：

SELECT timestamp, body FROM signoz_logs.distributed_logs_v2
WHERE body LIKE '%checkout%' ORDER BY timestamp DESC LIMIT 5;
-- 实测命中：order checkout completed amount=258.00（severity_text=INFO）

指标样本与元数据：

SELECT metric_name, count() FROM signoz_metrics.distributed_samples_v4
WHERE metric_name LIKE 'checkout%' GROUP BY metric_name;
-- checkout_requests_total   1

SELECT metric_name, type, is_monotonic FROM signoz_metrics.distributed_metadata
WHERE metric_name = 'checkout_requests_total' LIMIT 3;
-- checkout_requests_total  Sum  true

查 clickhouse 集群拓扑：

SELECT cluster, shard_num, replica_num, host_name, port
FROM system.clusters WHERE cluster = 'cluster';
-- cluster / 1 分片 1 副本 / signoz-telemetrystore-clickhouse-0-0:9000

二、signoz-otel-collector 命令行

2.1 主命令与全局参数

Usage: signoz-otel-collector [flags] [command]
可用子命令: help / migrate
常用全局参数（--help 实测）：
  --config string            collector 配置文件路径
  --manager-config string    OpAMP 管理配置路径
  --copy-path string         实际生效配置落盘路径（默认 /etc/otel/signozcol-config.yaml）
  --clickhouse-dsn string    迁移/组件用 CH 连接（默认 tcp://0.0.0.0:9001）
  --clickhouse-cluster string  集群名（默认 cluster）
  --clickhouse-replication   是否启用副本（默认 true）

容器内实际启动命令（compose 渲染，实测）：先 migrate sync check 校验迁移一致性，再带 --config=/etc/otel-collector-config.yaml --manager-config=/etc/opamp-config.yaml --copy-path=/var/tmp/collector-config.yaml 运行。

2.2 migrate 子命令（ClickHouse schema 迁移）

signoz-otel-collector migrate <subcommand>
  ready       检查存储是否就绪可迁移
  bootstrap   创建迁移状态跟踪表
  sync        同步迁移（schema 变更，必须先完成）；sync check 为校验、sync up 为执行
  async       异步迁移（数据回填类，可后台跑）；async up 为执行

对应 migrator 初始化容器的实测命令链：

/signoz-otel-collector migrate ready
/signoz-otel-collector migrate bootstrap
/signoz-otel-collector migrate sync up
/signoz-otel-collector migrate async up

手工重跑（迁移失败修复时，需在 collector 容器网内执行）：

docker exec signoz-01460-stack-ingester-1 \
  /signoz-otel-collector migrate sync check --clickhouse-dsn tcp://signoz-telemetrystore-clickhouse-0-0:9000

2.3 配置校验（失败即 fatal，实测）

该二进制没有独立的 validate 子命令，校验发生在启动阶段。喂一个缺 exporter 的配置实测：

{"level":"fatal",...,"msg":"failed to run service:",
 "error":"failed to start collector service: failed to start : invalid configuration: no exporter configuration specified in config"}

排障结论：配置错误看 docker compose logs ingester 的 fatal 行即可，无需额外的 dry-run 参数。

三、SigNoz Server API（curl 实测清单）

基础地址 http://<服务器>:8143（容器 8080）。无需认证的两个探针：

curl -s http://localhost:8143/api/v1/health    # {"status":"ok"}
curl -s http://localhost:8143/api/v1/version   # {"version":"v0.146.0","ee":"Y","setupCompleted":true}

3.1 首次注册（仅 setupCompleted=false 时可用）

curl -s -X POST http://localhost:8143/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@signoz.local","name":"admin","password":"Q1w2e3r4#@$%","orgName":"signoz"}'
# {"status":"success","data":{}}

弱口令实测报错：Password must be at least 12 characters long and contain at least one uppercase letter, one lowercase letter, one digit, and one special character。

3.2 登录换 token（v2 端点）

curl -s -X POST http://localhost:8143/api/v2/sessions/email_password \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@signoz.local","password":"Q1w2e3r4#@$%","orgID":"<orgId>"}'
# {"status":"success","data":{"accessToken":"Tgf17gc0Y6qfI97xU0V3G8zqN5A8lNf3",
#  "tokenType":"Bearer","expiresIn":86400}}

注意：v0.146 旧的 POST /api/v1/login 已不存在（返回 SPA 首页 HTML），登录走 POST /api/v2/sessions/email_password，token 类型是不透明字符串（非 JWT），有效期 86400 秒。

3.3 身份与资源查询

AT="<accessToken>"
curl -s http://localhost:8143/api/v2/users/me -H "Authorization: Bearer $AT"
# data.details.role=ROOT；userTenantMappings[].tenantId 即 orgID
curl -s http://localhost:8143/api/v1/services/list -H "Authorization: Bearer $AT"
# {"status":"success","data":{"services":[{"name":"frontend-api","p99":355330438,...}]}}
curl -s http://localhost:8143/api/v1/logs/fields -H "Authorization: Bearer $AT" | head -c 300
# {"status":"success","data":[{"name":"body","type":"","dataType":"String",...},...]}

3.4 统一查询接口 /api/v4/query_range

日志/追踪（builder 形态，dataSource 二选一）：

START=$(($(date +%s) - 900))000; END=$(date +%s)000
curl -s -X POST http://localhost:8143/api/v4/query_range \
  -H "Authorization: Bearer $AT" -H 'Content-Type: application/json' \
  -d "{\"start\":$START,\"end\":$END,\"formatForWeb\":true,\"compositeQuery\":{\"panelType\":\"graph\",
  \"queryType\":\"builder\",\"builderQueries\":{\"A\":{\"queryName\":\"A\",\"dataSource\":\"logs\",
  \"aggregateOperator\":\"count\",\"expression\":\"A\",\"disabled\":false,\"type\":\"builder-query\"}}}}"
# {"status":"success","data":{"result":[{"queryName":"A","series":[{"labels":[],"values":[[1760942400,"1"]]}]}]}}

指标（PromQL 形态，实测通过）：

curl -s -X POST http://localhost:8143/api/v4/query_range \
  -H "Authorization: Bearer $AT" -H 'Content-Type: application/json' \
  -d "{\"start\":$START,\"end\":$END,\"formatForWeb\":true,\"compositeQuery\":{\"panelType\":\"graph\",
  \"queryType\":\"promql\",\"promQueries\":{\"A\":{\"name\":\"A\",
  \"query\":\"sum(rate(checkout_requests_total[5m]))\",\"disabled\":false}}}}"
# {"status":"success",...}

已知坑（实测）：v0.146 对不带聚合属性的指标 builder 查询（count/sum）会返回 {"errorType":"internal","error":"error in builder queries"}，服务端日志可见 SQL syntax error: Empty query；指标查询请用 PromQL 形态或补全 aggregateAttribute。

四、Foundry 与 Compose 运维命令

foundryctl version                 # 查 foundryctl 版本
foundryctl catalog                 # 查可用 casting 目录
foundryctl gauge -f casting.yaml   # 校验部署前置（docker/compose 可用性）
foundryctl forge -f casting.yaml   # 渲染 pours/deployment/（重复执行会覆盖产物）
foundryctl cast -f casting.yaml    # 投放到目标环境（本实录未用，直接 compose 起栈）

cd pours/deployment
docker compose ps                  # 栈状态（healthy/completed）
docker compose logs -f ingester    # 跟 collector 日志（排障主入口）
docker compose restart ingester    # 改 ingester.yaml 后热重启生效
docker compose down / down -v      # 停栈（保留/销毁数据卷）

五、速查卡

场景	命令
存活探针	`curl :8143/api/v1/health`、`curl :8146/?query=SELECT+1`
登录拿 token	`POST /api/v2/sessions/email_password`
查一条链路	clickhouse-client 查 `signoz_traces.distributed_signoz_index_v3 WHERE trace_id=...`
查错误明细	`signoz_traces.distributed_signoz_error_index_v2`
查日志	`signoz_logs.distributed_logs_v2`（属性用 `resources_string['service.name']`）
指标元数据	`signoz_metrics.distributed_metadata`
schema 迁移	`signoz-otel-collector migrate ready/bootstrap/sync up/async up`
collector 配置校验	启动期 fatal 校验，看 `docker compose logs ingester`
改 collector 配置	改 `ingester.yaml` → `docker compose restart ingester`