一个 CLI 查 10+ 个可观测后端：obz 用原生 PromQL/LogQL/TraceQL 收口

项目地址：

安装：

curl -sSL https://raw.githubusercontent.com/alibaba/obz-cli/main/install.sh | sh

Rust 1.75+。obz 是一个面向 metrics、logs、traces 的多后端可观测性 CLI，统一接口，对 AI Agent 友好。目前支持 10+ 后端，语义化查询（OTel Semantic Conventions）在 Roadmap 里，尚未实现。

为什么需要 obz

可观测数据散落在多个后端：Prometheus、Loki、Jaeger、Elasticsearch、Datadog 等。每个后端有自己的 CLI、自己的查询语言、自己的输出格式，跨后端查询没有统一路径——对需要结构化、可预期响应的 AI Agent 来说尤其麻烦。

obz 现在做的事：一个 CLI 查询 10+ 后端上的 metrics、logs、traces，输出结构化 JSON，退出码确定，内置 skill 文档，让 Agent 调用时不用猜解析规则。

obz 接下来做的：接入并扩展 OTel Semantic Conventions，把语义感知带到查询侧。

特性

• 统一接口 — 一套命令覆盖 10+ 后端：VictoriaMetrics、Prometheus、Grafana Mimir、GreptimeDB、VictoriaLogs、Grafana Loki、VictoriaTraces、Jaeger、Grafana Tempo、OpenSearch、Elasticsearch、阿里云 SLS、Datadog
• Agent-first — 默认 JSON 输出，错误响应带结构化字段（category、exit code、recoverability、修复建议）；每个 provider 有内置 skill 文档；--fields、--truncate 做输出投影以省 token
• 后端透传 — 直接使用后端原生查询语言（MetricsQL、PromQL、LogsQL、LogQL、TraceQL、DQL 等），不发明新 DSL
• 可扩展 — 三层架构（CLI / core framework / provider adapters），依赖单向；接入新后端只需实现 provider trait 并注册，不改 core
• 配置文件 — 在 ~/.config/obz/ 预置 endpoint 和凭证，之后查询只写 -p

Quick Start

obz metric query -p vm --endpoint http://localhost:8428 -q 'up'
obz metric query -p prom --endpoint http://localhost:9090 -q 'up'
obz metric query -p mimir --endpoint http://localhost:9009 -q 'up'
obz log search -p vl --endpoint http://localhost:9428 -q 'error' --from now-1h
obz log search -p loki --endpoint http://localhost:3100 -q '{job="varlogs"}' --from now-1h
obz trace search -p vt --endpoint http://localhost:10428 -q 'frontend'
obz trace search -p jg --endpoint http://localhost:16686 -q 'frontend'
obz trace search -p tempo --endpoint http://localhost:3200 --from now-1h
obz log search -p os --endpoint http://localhost:9200 --index 'otel-logs-*' -q 'error' --from now-1h
obz log search -p es --endpoint http://localhost:9200 --index 'logs-*' -q 'error' --from now-1h
obz metric query -p sls --project my-proj --metricstore prom-store -q 'up'
obz log search -p dd -q 'service:web status:error' --from now-1h
obz metric query -p vm -q 'up'              # uses ~/.config/obz/config.yaml
obz log search -p sls -q 'error'            # credentials from config.yaml

命令清单

obz metric query          Execute a metric query (instant or range)
obz metric list           List metric names
obz metric info           Get metric metadata
obz metric labels         List label names
obz metric label-values   List values for a specific label
obz metric series         Find series matching selectors
obz log search            Search for log entries
obz trace search          Search for spans across traces
obz trace get             Get all spans for a specific trace by ID
obz trace services        List available service names (VT/Jaeger)
obz trace operations      List operations for a service (VT/Jaeger)
obz trace tags            List available tag names (Tempo)
obz trace tag-values      List values for a specific tag (Tempo)
obz provider list         List built-in providers
obz provider check        Validate provider configuration
obz completions           Generate shell completion scripts
obz skills                Show provider skill documents

Provider 能力矩阵

Metric

Log

Trace

实际差异集中在几处：GreptimeDB 没有 metric list / metric info；SLS 没有 metric info，但 metric labels / label-values / series 可用；Datadog 没有 metric labels、label-values、series；trace 侧只有 VictoriaTraces 和 Jaeger 提供 trace services / trace operations，只有 Tempo 提供 trace tags / trace tag-values。跨后端写脚本时这些缺口要提前处理。

Provider 别名：vm (VictoriaMetrics)、vl (VictoriaLogs)、vt (VictoriaTraces)、sls (阿里云 SLS)、dd (Datadog)、prom (Prometheus)、greptime (GreptimeDB)、jg (Jaeger)、os (OpenSearch)、es (Elasticsearch)、mimir (Grafana Mimir)、loki (Grafana Loki)、tempo (Grafana Tempo)

配置

在 ~/.config/obz/config.yaml（或 OBZ_CONFIG_DIR）中预配置 provider：

providers:
vm:
provider: vm
endpoint: http://localhost:8428
auth:
token: ${env:OBZ_VM_TOKEN}

mimir:
provider: mimir
endpoint: http://localhost:9009
headers:
X-Scope-OrgID: my-tenant
auth:
username: ${env:MIMIR_USERNAME}
password: ${file:~/.secrets/mimir-password.txt}

sls:
provider: sls
endpoint: https://my-proj.cn-hangzhou.log.aliyuncs.com
project: my-proj
metricstore: prom-store
logstore: nginx
auth:
access-key-id: ${file:~/.obz/sls-ak.txt}
access-key-secret: ${file:~/.obz/sls-sk.txt}

dd:
provider: dd
endpoint: https://api.datadoghq.com
auth:
api-key: ${env:DD_API_KEY}
app-key: ${env:DD_APP_KEY}

greptime:
provider: greptimedb
endpoint: http://localhost:4000  # root URL only; no path, query, or fragment
db: public                      # required; GreptimeDB database name

es-prod:
provider: es
endpoint: https://es.example.com:9200
auth:
credential-process:
command: vault
args: ["kv", "get", "-format=json", "secret/es-prod"]
timeout: 10s

支持的 auth 字段：token（bearer）、username/password（basic）、access-key-id/access-key-secret（SLS）、api-key/app-key（Datadog）、credential-process（查询时动态取凭证）。

变量引用：${env:VAR}（未设置则报错）、${env?:VAR}（未设置时为空字符串）、${file:path}（相对 config 目录的路径，~ 会展开）。

优先级：CLI flags > credential-process > config.yaml（含已解析的 ${env:} / ${file:} 值）。

Roadmap

• Semantic Conventions querying — 接入并扩展 OTel Semantic Conventions，做语义感知的数据发现与查询
• 扩展 provider 覆盖范围
• 文档站点

边界与取舍

这个项目创建于 2026-04，目前约 27 star，属于早期状态。语义化查询还没落地，provider 之间的能力也并不齐整，前面矩阵里的「—」是真实缺口，不是文档遗漏。

它是查询侧的收口工具，不是采集或存储组件——别把它当成生产环境唯一的采集/存储方案。更合适的用法是：本机同时跑着 VictoriaMetrics、Loki、Jaeger 这类后端时，用一套命令做排查；或者把它当作 Agent 的查询入口，靠 JSON 输出和确定退出码做自动化。配置里的认证方式（包括 Vault credential-process 这类动态取凭证）建议在自己的环境里先验证一遍再用。

License

Apache License, Version 2.0。Repo: 。Install: curl -sSL https://raw.githubusercontent.com/alibaba/obz-cli/main/install.sh | sh。Rust 1.75+。

tags: 数据监控, 可观测性, CLI, PromQL, LogQL, TraceQL, AI Agent, Rust