快速开始

用一条命令运行 sigiro，把 OpenTelemetry 指向它，然后用 SQL 查询最近的失败。只需五分钟，不需要采集器，也不需要配置文件。

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

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

如果使用托管版，请运行 sigiro signup --name "Your Name" --email you@example.com；托管指南会使用生成的 CLI 会话。

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 -d --name sigiro --restart unless-stopped \
  -p 127.0.0.1:4317:4317 -p 127.0.0.1:4318:4318 -p 127.0.0.1:9999:9999 \
  -v sigiro-data:/var/lib/sigiro ghcr.io/sigiroai/sigiro

命名卷会在容器重启后保留数据；重启策略会在主机重启后启动服务。Docker 发布的端口只能从本机访问。如果 Jaeger 等服务占用了 4317 和 4318，请在运行命令前将前两个 -p 参数替换为 -p 127.0.0.1:14317:4317 -p 127.0.0.1:14318:4318。随后把 OTLP HTTP 导出目标改为 http://localhost:14318（gRPC 使用 localhost:14317）。主机的 9999 端口也必须空闲；如果重映射它，下面的 API 请求也要使用新的主机端口。

如果要保留原有 Jaeger v2 接收器并镜像链路追踪，而不修改应用的目标地址，请参阅与 Jaeger 并行试用 sigiro。

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

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

发送遥测数据前，请确认服务端已准备就绪：

curl --fail http://localhost:9999/health

使用 Docker 时，docker inspect --format '{{.State.Health.Status}}' sigiro 会在准备就绪后返回 healthy；否则请查看 docker logs sigiro。数据目录对于二进制文件是 ~/.local/share/sigiro，在镜像中是 /var/lib/sigiro。

请注意，服务端不会向你索要密钥。自托管的服务端不对任何请求做鉴权。上述 Docker 命令将访问限制在本机；不要将这些端口暴露在不可信的网络中。网络就是安全边界。

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. 查询最近的错误

第一个查询显示所选时间窗口内各操作的调用量和失败数，并不推断原因。

curl -sS -X POST http://localhost:9999/v1/query \
  --data-binary "SELECT span_name, count(*) AS calls,
                   sum(CASE WHEN status_code = 2 THEN 1 ELSE 0 END) AS errors
                 FROM sigiro_spans
                 WHERE service_name = 'checkout'
                   AND timestamp > CURRENT_TIMESTAMP - INTERVAL '30 minutes'
                 GROUP BY span_name ORDER BY errors DESC LIMIT 10"

4. 检查原始 Span

第二个查询返回原始 Span。决定修复方案前，请自行核对关联 Trace 和部署记录。这里不使用已保存的异常表或诊断端点。

curl -sS -X POST http://localhost:9999/v1/query \
  --data-binary "SELECT trace_id, duration, status_message
                 FROM sigiro_spans
                 WHERE service_name = 'checkout' AND status_code = 2
                   AND timestamp > CURRENT_TIMESTAMP - INTERVAL '30 minutes'
                 ORDER BY timestamp DESC LIMIT 20"

你做了什么

你启动了服务、发送了 OpenTelemetry，并按时间范围查询了原始遥测数据。结果是证据，而不是自动的根因结论。

下一步

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