Skip to content
sigiro
Esc
↑↓navigate↵open⌘Jpreview
On this page

Quickstart

Run sigiro with one command, point OpenTelemetry at it, then query recent failures with SQL. Five minutes, no collector and no configuration file.

In this tutorial you start a sigiro server, send it telemetry from your own service, and run two bounded raw-telemetry queries. The results do not assert a cause. This takes five minutes.

sigiro is one process. You deploy no collector and you write no configuration file.

If you want hosted sigiro instead, run sigiro signup --name "Your Name" --email you@example.com; the hosted onboarding guide uses the resulting CLI session for telemetry and queries.

1. Run it

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

The script reads your operating system and processor. Then it checks the SHA-256 of the download against the published checksum. It writes the binary to ~/.local/bin. Set SIGIRO_INSTALL_DIR for a different directory.

Builds exist for Linux and macOS on arm64, and for Linux on x86-64. On another platform, use the container.

On a first run with a fresh data directory, the binary may download query extensions before it is ready. Check the startup logs rather than assuming a fixed wait time.

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

The named volume keeps data across container restarts; the restart policy starts the server after a reboot. Docker publishes these ports only on this host. If Jaeger or another service already uses 4317 and 4318, replace the first two -p flags with -p 127.0.0.1:14317:4317 -p 127.0.0.1:14318:4318 before running the command. Point OTLP HTTP at http://localhost:14318 (or gRPC at localhost:14317). Host port 9999 must also be free; if you remap it, use the new host port for the API requests below.

To keep an existing Jaeger v2 receiver and mirror its traces instead of repointing applications, follow Try sigiro beside Jaeger.

Each of the three ports has one function:

Port Protocol
4317 OTLP over gRPC
4318 OTLP over HTTP
9999 the telemetry query API

Wait for the server to be ready before sending telemetry:

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

For Docker, docker inspect --format '{{.State.Health.Status}}' sigiro reports healthy when ready; if it does not, check docker logs sigiro. The data directory is ~/.local/share/sigiro for the binary and /var/lib/sigiro in the image.

Notice that the server asks you for no key. A self-hosted server authenticates no request. The Docker command limits access to the local host; do not expose these ports on an untrusted network. The network is the security boundary.

2. Send it telemetry

Any OpenTelemetry SDK or collector in your stack works without a change. Point the standard environment variables at sigiro:

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

If your code has no instrumentation yet, do not add it by hand. Follow Instrument your code with an agent first, then come back here.

Now send some real traffic through your service, and confirm that the telemetry arrived:

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

The response is a JSON object with a services array. Your service appears in that array within a few seconds of the first request. If the array is empty, check that the port is 4318 for OTLP over HTTP and 4317 for OTLP over gRPC.

3. Query recent errors

The first query compares operation volumes and failures in your chosen window. It does not claim a cause.

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. Inspect the underlying spans

The second returns raw span evidence. Check related traces and deployments yourself before deciding what to fix. No scheduled anomaly table or diagnosis endpoint is involved.

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"

What you did

You started a server, sent it OpenTelemetry, and queried bounded raw telemetry. The results are evidence, not an automated root-cause verdict.

Next

Was this page helpful?