SigNoz - OpenSRE Documentation

Overview

Query logs, metrics, and traces from SigNoz via the Query Range API. OpenSRE uses POST /api/v5/query_range for query_signoz_logs, query_signoz_metrics, and query_signoz_traces. Configure SIGNOZ_URL and SIGNOZ_API_KEY (service account key).

Prerequisites

A running SigNoz instance (Cloud, self-hosted, or local Docker)
A SigNoz service account API key (see Credentials)

Setup

Option 1: Interactive CLI

opensre integrations setup signoz

Setup prompts for SigNoz URL and API key only.

Option 2: Environment variables

export SIGNOZ_URL="http://localhost:8080"
export SIGNOZ_API_KEY="<service-account-api-key>"

Variable	Description
`SIGNOZ_URL`	SigNoz base URL (local Docker: `http://localhost:8080`)
`SIGNOZ_API_KEY`	Service account API key

Local Docker quick start

If you already run SigNoz, skip to credentials and env setup above. For a local stack, use the official SigNoz Docker setup.

docker compose -f signoz/docker/docker-compose.yaml up -d
# ... later
docker compose -f signoz/docker/docker-compose.yaml down

Local Docker serves the UI and API on http://localhost:8080 (not 3301).

Credentials

In SigNoz: Settings → Service Accounts → create a service account → Keys → Add Key. Copy the key (shown once).

Investigation tools

Tool	What it does
`query_signoz_logs`	Search logs by service, severity, and time window
`query_signoz_metrics`	Query CPU, memory, and request-rate signals
`query_signoz_traces`	Query error spans, latency percentiles, and dependencies

When alert_source is signoz, OpenSRE auto-seeds these three tools before the ReAct loop.

Supported metrics (V1)

Alias	Actual SigNoz metric
`cpu_usage`	`system_cpu_usage`
`memory_usage`	`system_memory_usage`
`request_rate`	`signoz_calls_total`

You can also pass any raw metric name known to SigNoz. For latency percentiles (p95/p99), prefer query_signoz_traces.

Verify

opensre integrations verify signoz

Expected verify output mentions the SigNoz Query API (/api/v2/metrics, /api/v5/query_range).

Troubleshooting

Symptom	Fix
`SigNoz configuration is incomplete`	Set both `SIGNOZ_URL` and `SIGNOZ_API_KEY`.
`HTTP 401` on verify	Regenerate the service account key; check URL (local Docker: port 8080).
`No logs returned`	Confirm telemetry exists in SigNoz and filter fields match (`service.name` for logs).
`No metrics returned`	Verify the metric name in SigNoz Metrics Explorer; empty results return a warning for unknown metrics.
Gateway `422` on `/investigate`	Body must include `raw_alert` (object). A bare SigNoz webhook JSON is not enough.

Security

Use a dedicated SigNoz service-account key with the minimum permissions needed for query access.
Store SIGNOZ_API_KEY in .env or your secret manager — not in source control.
Protect POST /investigate with OPENSRE_ALERT_LISTENER_TOKEN on any non-loopback gateway.

Extras

Webhook / gateway trigger

SigNoz can emit Prometheus-style webhook payloads. The OpenSRE gateway does not accept a raw SigNoz webhook body as-is. Synchronous investigations use:

POST /investigate

with a JSON body matching InvestigateRequest:

Field	Required	Description
`raw_alert`	Yes	Alert object passed into the investigation pipeline
`alert_name`	No	Optional override
`severity`	No	Optional override

Include alert_source: "signoz" inside raw_alert (or set fields the pipeline can resolve to SigNoz) so auto-seed and tool relevance apply. Auth: set OPENSRE_ALERT_LISTENER_TOKEN and send Authorization: Bearer <token>; if unset, only loopback callers are accepted. See API. Example (map or wrap your SigNoz notification into this shape):

curl -X POST "https://your-opensre-host/investigate" \
  -H "Authorization: Bearer $OPENSRE_ALERT_LISTENER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_alert": {
      "alert_source": "signoz",
      "alert_name": "HighErrorRate",
      "pipeline_name": "payment-service",
      "severity": "critical",
      "commonLabels": {
        "service_name": "payment-service",
        "severity": "critical"
      },
      "commonAnnotations": {
        "summary": "Error rate exceeded 5%"
      }
    }
  }'

In SigNoz, create a Webhook notification channel that POSTs a body your adapter transforms into this shape (or post directly from a small proxy). Pointing the channel at /investigate with an unmodified SigNoz payload will fail validation (raw_alert required).

API reference

Endpoint: POST {SIGNOZ_URL}/api/v5/query_range
Auth header: SigNoz-Api-Key: <YOUR_API_KEY>
Validation probe: GET {SIGNOZ_URL}/api/v2/metrics

Example investigation (CLI)

uv run opensre investigate --input-json '{
  "alert_source": "signoz",
  "alert_name": "HighErrorRate",
  "pipeline_name": "payment-service",
  "severity": "critical",
  "commonLabels": {
    "service_name": "payment-service",
    "severity": "critical"
  },
  "commonAnnotations": {
    "summary": "Error rate exceeded 5%"
  }
}'

​Overview

​Prerequisites

​Setup

​Option 1: Interactive CLI

​Option 2: Environment variables

​Local Docker quick start

​Credentials

​Investigation tools

​Supported metrics (V1)

​Verify

​Troubleshooting

​Security

​Extras

​Webhook / gateway trigger

​API reference

​Example investigation (CLI)