README
¶
sig
A SigNoz CLI built for AI agents.
Query logs, traces, and metrics with structured JSON output.
Quick start · Usage · AI agents · Documentation
sig is an independent CLI for SigNoz. Find the logs behind an error, inspect a slow trace, or query a metric without leaving your workflow. It connects directly to your SigNoz API and returns JSON that works equally well in a shell pipeline or an agent's tool call.
- Investigate across signals. Search logs and spans, fetch trace waterfalls, calculate statistics, and run PromQL.
- Discover as you go. Find field names, observed values, and available metrics before building a query.
- Bring your agent. Machine-readable commands and offline query recipes are built in. No MCP server is needed.
Install
CLI
go install github.com/sprisa/sig@latest # with Golang (no auto update)
npm install -g @sprisa/sig # with npm (no auto update)
Check either installation:
sig version
Installation help · Build from source
Agent skill
Install the skill for your AI agent with skills
(requires Node.js and npx):
npx skills add sprisa/sig
The skill includes CLI installation instructions, so you can start here even if
you haven't installed sig yet. It also teaches the investigation workflow and
when to load the bundled query recipes.
Quick start
You'll need your SigNoz URL and a service-account API key. Replace the example URL with your instance:
sig auth login --url https://signoz.example.com
sig auth status
sig logs search --since 15m
Login prompts for the key and saves it in your OS keychain. Your first login
creates the default context, so subsequent commands already know where to connect.
Using CI, a headless machine, or an existing MCP configuration? You can supply
SIGNOZ_URL, SIGNOZ_API_KEY, and optional SIGNOZ_CUSTOM_HEADERS through the
environment instead. See authentication and configuration.
Everyday queries
Find the logs you need
sig logs search --where "body CONTAINS 'timeout'" --since 1h --limit 20
Not sure what to filter on? Discover the fields and values in your instance:
sig logs fields --search service --since 1h
sig logs values severity_text --field-context log --since 1h
Get the big picture
Count matching records or group them into a trend instead of downloading every row:
sig logs aggregate --aggregation 'count()' --since 1h
sig logs aggregate --aggregation 'count()' --group-by severity_text --step 1m --since 1h
Follow a trace
Search returns spans. Use a trace ID from the results to retrieve its waterfall:
sig traces search --where "has_error = true" --since 1h --limit 20
sig traces get "$TRACE_ID"
Query your metrics
Discover a metric name, then query it with PromQL. Replace the example expression with one that matches your instrumentation:
sig metrics list --search http --since 1h
sig metrics query 'sum(rate(http_requests_total[5m]))' --since 1h --step 1m
Need a fixed window, more results, or a native query?
Use explicit bounds for an incident window (replace these example times):
sig logs search --start 2026-01-01T12:00:00Z --end 2026-01-01T13:00:00Z
Fetch a few pages or resume with meta.next_page_token from a previous response:
sig logs search --since 1h --limit 100 --pages 3
sig logs search --page-token "$PAGE_TOKEN"
For a native SigNoz v5 query you've saved to a file:
sig query preview --file query.json
sig query run --file query.json
JSON that fits your workflow
Successful commands write {data, meta?} to stdout. Errors write {error} to
stderr and return a nonzero exit code. Help is plain text.
For example, use jq to inspect the metadata for a search:
sig logs search --since 1h --limit 20 | jq '.meta'
Check warnings and completeness before treating a result as exhaustive. Output shapes, pagination, and exit codes explain what each command returns.
AI agents
Use the skill install command above, or add
skills/sig/SKILL.md through your agent's usual skill
mechanism. The skill points to focused recipes instead of loading a full manual
on every request.
Agents can also discover the installed interface directly:
sig agent schema logs aggregate
sig agent recipes
sig agent recipes workflow
Schema and recipes work offline. Everyone gets the same JSON interface; no agent-mode flag or environment detection is required.
Learn more
| Looking for… | Start here |
|---|---|
| Headless auth, multiple contexts, or proxy headers | Configuration |
| Time windows, pagination, output contracts, or native JSON queries | Querying |
| Field contexts, units, and investigation techniques | Query recipes |
| Credential handling and the trust model | Security |
| Building, testing, architecture, or contributing | Contributing |
Run sig --help or sig <command> --help for command details.
Compatibility: sig targets SigNoz v0.132.0's APIs. Compatibility with other versions needs verification. See compatibility notes.
Licensed under MPL 2.0.
Documentation
¶
There is no documentation for this package.
Source Files
Directories