# sigiro > Point OpenTelemetry at it. When something breaks, you get an answer with the query that proves it, not a chart to read. ## Run it ``` docker run -p 4317:4317 -p 4318:4318 -p 9999:9999 ghcr.io/sigiroai/sigiro ``` Ports: 4317 OTLP/gRPC, 4318 OTLP/HTTP, 9999 query + investigate API. ## API The full machine-readable surface is at https://sigiro.com/openapi.json — no key required. - GET /v1/anomalies — ranked shifts against each service's own baseline - POST /v1/investigate — one structured evidence block per service - POST /v1/query — SQL over your telemetry - GET /v1/services, /v1/traces/{trace_id}, /v1/health ## Docs - [Fetch one whole trace](https://sigiro.com/docs/api/get-trace): Every span of one trace, parent links included, so a caller can rebuild the tree. Trace IDs come from the sampled spans in an investigation, or from any SQL query over sigiro_spans. - [API reference](https://sigiro.com/docs/api): Every endpoint sigiro answers on, generated from the spec an agent reads. - [Diagnose a service: ranked findings with runnable SQL](https://sigiro.com/docs/api/investigate-services): Root-cause an incident for one or more services over a time window. Returns a triage summary — NOT raw telemetry: a ranked findings array (read this first), per-operation anomaly flags, and bounded samples of spans/logs. Every lead carries a ready-to-run SQL string (drill_down_sql on findings, operations, spans, and log patterns; drill_all_sql on the spans/logs sections) that you paste VERBATIM into POST /v1/query to fetch the underlying rows and go deeper. Typical agent loop: GET /v1/services → POST /v1/investigate → for any finding or anomalous operation, run its drill_down_sql via /v1/query. Timestamps are microseconds since the Unix epoch. The response is a map {results: {service: block}, errors: {service: message}} — partial results survive a single failing service. - [Ranked shifts against each service's own baseline](https://sigiro.com/docs/api/list-anomalies): Precomputed anomalies: worsening regime shifts (BOCPD changepoints, threshold-free) detected continuously over persisted 5-minute series of every signal — error_rate and latency_p95 per operation, log_volume, error_log_rate and profile_cost (the service's total profiled cost) per service (the operation field holds the entity) — and persisted to the sigiro_anomalies table. Ordered by the unit-free shift magnitude (after - before) / (after + before) descending (1.0 = appeared from a zero baseline, 1/3 = doubled), so the most significant shifts lead regardless of the signal's units — nothing is filtered out; judge significance from before/after (raw signal units: %, µs, logs, profile cost). Optionally filter by service and a from_ts/to_ts window (microseconds since the Unix epoch) over the shift time. Each row carries a ready-to-run drill_down_sql for POST /v1/query. Rows whose shifts fall in the same or adjacent 5-minute detection bucket on the same service share an incident_id — one incident across signals, not N independent anomalies (the correlation window is the detection pass's own bucket resolution, never a tuned threshold); incident_id is null for uncorrelated rows. - [List services seen, with time bounds](https://sigiro.com/docs/api/list-services): Every service that has reported telemetry, with the first and last timestamp seen for each (microseconds since the Unix epoch). The entry point of an agent loop: pick a service here, then investigate it. - [Run SQL over your telemetry](https://sigiro.com/docs/api/run-query): Accepts exactly one SELECT statement as the raw request body. Allowed tables: sigiro_spans, sigiro_logs, sigiro_log_templates, sigiro_metrics_gauge, sigiro_metrics_sum, sigiro_metrics_histogram, sigiro_metrics_exp_histogram, sigiro_profiles, sigiro_anomalies (optionally qualified as lake.* or main.*). WITH/CTE clauses are not supported — rewrite as derived-table subqueries. Scalar functions are allowlisted (aggregates, json extraction, date/time, string, math, conditional helpers); file/network readers are blocked. Every drill_down_sql returned by /v1/investigate can be pasted here verbatim. - [Hosted beta](https://sigiro.com/docs/hosted-onboarding): Ship OpenTelemetry to hosted sigiro with a tenant key and query it back with SQL — no infrastructure to run. Onboarding is manual during the invited beta. - [sigiro docs](https://sigiro.com/docs): sigiro is the detect and diagnose layer for self-improving software — OpenTelemetry in, ranked findings and runnable SQL out, for agents rather than dashboards. - [Instrument your code with an AI agent](https://sigiro.com/docs/install-with-ai): Give a coding agent one prompt and it adds OpenTelemetry auto-instrumentation to your service, pointed at sigiro. Works with Claude Code, OpenCode, and Codex. - [Quickstart](https://sigiro.com/docs/quickstart): Run sigiro with one docker command, point OpenTelemetry at it, then ask it what changed and why. Five minutes, no collector, no config. - [Full text of every page](https://sigiro.com/llms-full.txt): all docs as markdown, one file ## FAQ ### What is sigiro, in one sentence? An observability backend built to be read by an agent. You send it OpenTelemetry, ask in SQL or in one investigate call, and get back a diagnosis instead of a dashboard. ### Does it replace Datadog or Grafana? It replaces what you were using them for when the reader is a machine. If a person needs to look at a chart, keep the dashboard. This is for everything downstream of that. ### Do I have to change my code? No. It speaks standard OTLP on ports 4317 and 4318, so any OpenTelemetry SDK or collector you already run points at it unchanged. ### Where does my data go? Nowhere you did not put it. You run sigiro on your own infrastructure and it writes to your own storage. It does not phone home and there is no account to create. Hosted exists if you would rather not run anything, and that one does hold your telemetry for you. ### Does it page me? No, deliberately. Paging exists to interrupt someone who cannot watch continuously. What you get back is a table something else reads on a loop, so the interruption is the part we deleted. ### How does it know what is worth reporting without thresholds? Each service is compared against its own recent history instead of against a number you picked. A service that is chronically slow but steady reports nothing, because nothing changed. A service that quietly doubled reports, even though no rule existed for it. ### What about sampling? There is none. The request you need is kept, not one in a hundred. Sampling was a bargain struck because nobody was ever going to read them all. Something will. ### What query language do I need to learn? None. You ask in plain SQL, which your agent already writes fluently. There is no proprietary query language between you and your own telemetry, and every answer hands you the query that produced it. ### Can my coding agent use it without me? Yes, that is the design. It reads the API description itself at /openapi.json, with no key and no hand-written tool definition, then queries in SQL it already knows. ### What does it cost? Running it yourself is free and the storage is yours, so there is no per-host fee, no per-seat fee and no ingest bill. Hosted is about $14 a month and currently invite-only. ### What does it not do? It does not write your patches, run your pipeline, or evaluate alert rules. There is no dashboard builder and no full-text log index. Questions are structured, which is how an agent asks them.