企业官网建设流程全解析

Monoscope 是一个开源可观测性平台，把日志（Logs）、追踪（Traces）与指标（Metrics）统一存储在 S3 兼容存储中，并支持通过 LLM 用自然语言查询。它的命令行工具Monoscope CLI是零依赖的单二进制文件。本文带你逐个走通 8 个覆盖搜索、监控与分诊的高频命令，并演示如何用jq把它们的 JSON 输出接进自动化管道。

🚀 快速安装与登录：零依赖可观测性 CLI 一键上手

Monoscope CLI 只需要一个二进制文件，不依赖libpq、protobuf等外部库：

# 自动检测平台（Linux/macOS、x86_64/arm64）、校验 SHA256 并安装 curl https://monoscope.tech/install.sh | sh

也可以先克隆仓库 gh_mirrors/mo/monoscope 查看安装脚本 scripts/install.sh 的完整逻辑。登录有两种方式：

monoscope auth login # 交互式：自动打开浏览器 monoscope auth login --token <your-api-key> # 非交互式：适合 CI

在 CI 环境里，直接导出环境变量即可，无需本地存储凭证：

命令 1｜status：一屏完成可观测性健康检查

排查故障的第一步永远是"现在到底有没有问题"。status用一次命令回答这个问题：时间窗口内的吞吐量、错误率、最忙的服务、未关闭的 Issue，以及正在告警的 Monitor：

monoscope status --since 24h

它相当于替你跑了 4 个命令，只产生 1 屏输出。一个值得注意的细节：面板查询失败时会内联显示错误，而不是渲染成一张空图——"不可用"和"平静"是两回事。

命令 2｜logs search：KQL 语法快速搜索错误日志

logs search使用与 Web UI 相同的 KQL 查询语言（字段清单见 docs/kql-reference.md）：

# 裸字符串自动改写为 body/summary 全文搜索，直接搜关键词即可 monoscope logs search POISON_ROW_DROPPED --since 24h # 按服务 + 级别过滤：最近 30 分钟的 error 日志 monoscope logs search --service checkout-api --level error --since 30m --limit 50 # 精确 KQL 写法：按 HTTP 状态码过滤 monoscope events search 'attributes.http.response.status_code >= 500' --since 1h

小贴士：--service可重复使用（--service a --service b会展开为in (a, b)）；不确定有哪些字段时，先用monoscope schema --search http查一遍。

命令 3｜logs tail：tail -f 式实时日志监控

排障时盯住实时流，logs tail就是终端里的tail -f：

monoscope logs tail --service api --level error # 只盯 api 的 error monoscope logs tail --grep timeout # 按消息子串过滤 monoscope logs tail --format logfmt | grep -v health # 转 key=value 后继续管道处理

它每次轮询都会请求一个比轮询间隔更宽的时间窗并去重，所以晚到一拍的日志也恰好出现一次，不会丢行也不会重行。

命令 4｜metrics query：指标聚合查询与 CI 断言门

metrics query对同一存储跑 KQL 聚合，summarize做聚合、by做分组：

# 最近 30 分钟各服务的 p99 延迟 monoscope metrics query 'summarize percentile(duration, 99) by resource.service.name' --since 30m # 断言门：结果为数值且不满足条件时以非零码退出，天然适合 CI monoscope metrics query 'where severity.severity_text=="error" | summarize count()' --since 30m --assert '< 100'

第二条是发布流水线里非常好用的"错误率门禁"：最近 30 分钟错误事件少于 100 才放行。

命令 5｜traces get --tree：瀑布图定位延迟瓶颈

拿到一个 trace id 后，--tree会在终端画出瀑布图：每个 span 一行、按深度缩进，右侧是耗时，错误 span 标红——直接回答"时间到底花在哪"：

monoscope traces get <trace-id> --tree

配合--json则输出原始 span 行，方便用sort找出最慢的 span：

monoscope traces get <trace-id> --json | jq -r '.events[] | [.duration, .span_name] | @tsv' | sort -rn | head

命令 6｜dashboards render：终端直接渲染监控仪表盘

不需要打开浏览器，dashboards render会把整个仪表盘——每个 widget、各自的网格位置——按 Web UI 的布局画出来，数据由服务端一次性解析变量和查询，所见即所得：

monoscope dashboards render <id> --since 24h --watch 1m # 故障时挂墙自动刷新 monoscope dashboards render <id> --widget p95-latency # 只渲染单个 widget，全宽 monoscope dashboards render <id> --json | jq '.widgets[] | {title, value}'

仓库自带大量现成仪表盘模板可以参考，例如 static/public/dashboards/kitchensink.yaml。

命令 7｜monitors apply：告警监控 YAML 化一键上线

Monitor 的定义就是一个 YAML 文件，可以进 Git 版本管理。仓库中的示例 docs/examples/monitors/http-5xx.yaml 展示了阈值、持续时间和 Slack 通知的完整配置。

日常运维命令：

monoscope monitors apply monitors/ # 目录级幂等 upsert，按名字做键 monoscope monitors mute <id> --for 30 # 静默 30 分钟，先降噪再定位 monoscope monitors bulk resolve --ids id1,id2

apply的幂等性意味着它可以直接放进 CI：配置改动合并后，监控随之更新。

命令 8｜issues list/issues ack：问题分诊与通知静默

Issue 是"检测到的问题"面向人的表示。每个 Issue 处于三种状态之一：Open（需分诊，持续通知）、Acknowledged（有人认领，暂停通知，到期或复发后回到 Inbox）、Archived（不再可操作）。

monoscope issues list --status open --service checkout-api monoscope issues ack <id> --for 240 # 认领 240 分钟并暂停通知 monoscope issues bulk acknowledge --ids id1,id2,id3

Acknowledge 是唯一能静默 Issue 的方式（没有单独的 mute），这让"谁认领了、静默多久"在审计上始终清晰。

🔧 JSON 管道技巧：把 CLI 接进自动化

CLI 的输出模式有一条黄金规则：stdout 是终端就是表格，stdout 被管道就是 JSON。所以一切"命令 | jq"都天然成立。两种核心响应包络：

三个实用组合：

# 1. 游标翻页：has_more 控制循环，cursor 传入下一次请求 monoscope logs search --service api --since 6h -o json | jq '{cursor, has_more}' # 2. 只取字段：--fields 在源头裁剪，--id-only 直接输出事件 id 供 events get 接力 monoscope events search 'severity.severity_text=="error"' --id-only # 3. 从 facets 动态取最忙的服务再搜索，免手写服务名 SVC=$(monoscope facets resource.service.name --top 1 | jq -r '.["resource.service.name"][0].value') monoscope events search '' --service "$SVC" --since 1h

还有一个容易踩的坑：schema返回的fields是对象而非数组，jq '.fields[]'可用，jq '.fields[0]'不行。

📚 延伸路径

掌握这 8 个命令加 JSON 管道之后，你在终端里就完成了"检查 → 搜索 → 聚合 → 定位 → 监控 → 分诊"的完整故障闭环——而这正是 Monoscope CLI 的设计初衷。