快速开始

用一条 docker 命令运行 sigiro。把 OpenTelemetry 指向它。然后问它发生了什么变化以及为什么。这需要五分钟。你不需要采集器，也不需要配置文件。

在本教程中，你将启动一个 sigiro 服务端，从你自己的服务向它发送遥测数据，并向它提出两个问题。最后你会读到一份诊断结果，并运行其背后的 SQL。这需要五分钟。

sigiro 是单个进程。你不需要部署采集器，也不需要编写配置文件。

1. 运行它

curl -fsSL https://sigiro.com/install | sh
sigiro serve

该脚本会读取你的操作系统和处理器，然后用已发布的校验和核对下载文件的 SHA-256。它会把二进制文件写入 ~/.local/bin。若要使用其他目录，请设置 SIGIRO_INSTALL_DIR。

我们为 arm64 架构的 Linux 和 macOS，以及 x86-64 架构的 Linux 提供了构建版本。在其他平台上，请使用容器。

docker run -p 4317:4317 -p 4318:4318 -p 9999:9999 ghcr.io/sigiroai/sigiro

添加 -v sigiro-data:/var/lib/sigiro 可以在容器重启后保留数据。

这三个端口各有一项功能：

端口	协议
`4317`	基于 gRPC 的 OTLP
`4318`	基于 HTTP 的 OTLP
`9999`	查询与诊断 API

首次启动时，sigiro 会下载它的查询扩展。这可能需要 30–90 秒，因此服务端接受请求前会有一段停顿。之后每次启动都是即时的。sigiro 把数据写入 SIGIRO_DATA_DIR。对于二进制文件，该目录是 ~/.local/share/sigiro；在镜像中则是 /var/lib/sigiro。

请注意，服务端不会向你索要密钥。自托管的服务端不对任何请求做鉴权，所以请把它放在私有网络中。网络就是安全边界。

2. 向它发送遥测数据

你技术栈中的任何 OpenTelemetry SDK 或采集器都无需改动即可工作。把标准环境变量指向 sigiro：

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=checkout \
  <your-app-start-command>

如果你的代码还没有埋点，不要手工添加。请先按照用 agent 为你的代码埋点操作，然后再回到这里。

现在向你的服务发送一些真实流量，并确认遥测数据已经到达：

curl http://localhost:9999/v1/services

响应是一个包含 services 数组的 JSON 对象。首次请求后的几秒内，你的服务就会出现在该数组中。如果数组为空，请检查端口：基于 HTTP 的 OTLP 是 4318，基于 gRPC 的 OTLP 是 4317。

3. 询问发生了什么变化

anomalies 是这个闭环的入口。它返回相对于各服务近期基线出现偏离的变化，偏离最大的排在最前。

sigiro anomalies
sigiro anomalies --service checkout

这里你不需要配置任何东西。没有阈值需要选择，而一个一直很慢但稳定的服务并不算异常。要了解 sigiro 如何做出这一判断，请参阅关于用证据取代仪表盘。

请注意，在刚启动不久的服务端上，这个列表可能为空。sigiro 需要几个 5 分钟的历史分桶才能进行比较，所以让你的服务运行一段时间后再来询问。

4. 询问为什么

diagnose 针对一个服务和一个时间窗口返回一个结构化的证据块。这个块以一份按重要程度排序的关注项列表开头。在其下，它包含错误计数、各操作的错误细分、各模型的 LLM 统计、抽样的 span，以及去重后的日志模式。每一行还附带一条可直接运行的 SQL 查询。

sigiro diagnose checkout
sigiro diagnose checkout --from $(date -v-1H +%s)

该命令会打印带缩进的 JSON。先读 findings 数组：它按严重程度从高到低排序，每一项都带有可供阅读的 summary 和可供运行的 drill_down_sql。

agent 通过 HTTP 提出同样的问题。HTTP 请求需要显式指定时间窗口，且两个时间戳都是自 Unix 纪元以来的微秒数：

curl -X POST http://localhost:9999/v1/diagnose \
  -H 'content-type: application/json' \
  -d "{\"service\":\"checkout\",
       \"from_ts\":$(( $(date +%s) - 900 ))000000,
       \"to_ts\":$(date +%s)000000}"

CLI 上的 --from/--to 标志接受纪元秒数，且 CLI 默认使用最近 15 分钟的窗口。HTTP 请求体接受微秒数，且没有任何默认值。如果在 HTTP 路径上传入秒数值，sigiro 会拒绝该请求并在消息中指明单位，这样单位错误会显式失败，而不是返回一个空窗口。

5. 运行某一行背后的查询

当证据块回答不了你的问题时，就运行某一行给出的 SQL。你的遥测数据是一组表，而查询请求的请求体是原始 SQL，而不是 JSON：

curl -X POST http://localhost:9999/v1/query \
  --data "SELECT service_name, count(*) AS errors
          FROM sigiro_spans
          WHERE status_code = 2 AND timestamp > now() - INTERVAL '1 hour'
          GROUP BY 1 ORDER BY errors DESC"

响应是一个由行对象组成的 JSON 数组。status_code 是 OTLP 枚举值，所以 2 表示错误。

请注意这个查询限定了 timestamp 的范围。在每个查询中都要限定 timestamp：sigiro 不维护二级索引，因此有范围限定的查询只读取少量文件，而没有限定的查询会读取每一个文件。

sigiro_spans 是九张表之一。托管版指南列出了全部九张表以及适用于它们的规则，关于这些表则解释了每一类表所度量的内容。

你做了什么

你启动了一个服务端，向它发送了 OpenTelemetry 数据，问它发生了什么变化，问它为什么，并运行了能佐证其中一个答案的查询。这就是 agent 自行运行的完整闭环。

下一步

用 agent 为你的代码埋点 —— 如果你的服务仍然没有 OpenTelemetry
向托管版 sigiro 发送遥测数据 —— 如果你不想自己运行服务端
CLI 参考 —— 另外四个子命令，以及每一个标志和环境变量
GET /openapi.json —— 完整的 API，机器可读，且无需密钥