sumocli

Files (1)

• SKILL.md

SKILL.md (first lines)

# sumocli

`sumocli` is a small Go CLI that wraps the Sumo Logic Search Job API. It is
read-only: create job → poll → paginate results → delete job. No tenancy
management, no mutations.

## Core command

```
sumocli query '<query>' [flags]
```

Exit code is non-zero on any error. The job ID is written to stderr on
stdout-clean runs, e.g. `search job <search-job-id>`.

### Flags

| Flag | Default | Notes |
| --- | --- | --- |
| `--from` | `-15m` | `now`, relative (`-15m`, `-1h30m`, `-7d`, `-1w`), or RFC3339 (`2025-04-16T08:30:00Z`) |
| `--to` | `now` | same formats |
| `--limit` | `1000` | `0` = no limit (API cap is 100k messages) |
| `--mode` | `auto` | `auto`, `messages`, or `records` |
| `-o`, `--output` | `ndjson` | `ndjson`, `json`, or `tsv` |
| `--poll-interval` | `1s` | initial poll; backs off to 5s |
| `--by-receipt-time` | `false` | search by receipt time instead of message time |
| `--no-header` | `false` | omit header row in tsv output |

## Always write results to a file first

Log results can be huge (tens of thousands of rows, many MB). Dumping raw
results into the conversation burns context and often truncates. **Always
redirect `sumocli` output to a file, then inspect it with targeted tools
(`jq`, `rg`, `wc`, `head`, `duckdb`).** Do not dump raw unfiltered
`sumocli` output into the conversation; filtered or aggregated output is fine.

Use a predictable scratch location so files can be cleaned up later:

```bash
mkdir -p /tmp/sumocli
out=/tmp/sumocli/$(date +%s).ndjson

sumocli query 'cluster=prod error' --from=-1h --limit 10000 > "$out"
wc -l "$out"                                   # how many rows
jq -r '._raw' "$out" | head -50                # peek
jq -r '[._messagetime, ._sourcehost, ._raw] | @tsv' "$out" | rg -i timeout
```

The job ID is written to stderr, so redirecting stdout does not hide it:

```bash
sumocli query '...' --from=-15m > "$out"       # job id still visible on stderr
```

### Analyse ndjson with duckdb

For anything beyond simple filtering — grouping, joins, windowed counts,
percentiles — use duckdb against the ndjson file. It reads ndjson natively
and is far faster and less error-prone than long `jq` pipelines.

```bash
duckdb -c "
  select _sourcehost, count(*) n
  from read_json_auto('$out', format='newline_delimited')
  group by 1 order by n desc limit 20;
"
```

For a one-off filtered export, create a temporary table in the same command:

```bash
duckdb -c "
  create temp table logs as
    select * from read_json_auto('$out', format='newline_delimited');
  select _messagetime, _sourcehost, _raw
  from logs
  where lower(_raw) like '%timeout%'
  limit 50;
"
```

For aggregations (records mode), result sets are almost always small and
can be read in full:

```bash
sumocli query 'cluster=prod | count by pod' --from=-1h > /tmp/sumocli/by_pod.ndjson
cat /tmp/sumocli/by_pod.ndjson | jq -r '[._count, .pod] | @tsv' | sort -rn
```

## Prefer ndjson when piping

`ndjson` (default) writes one JSON object per line — best for `jq`, `awk`,
`duckdb`, streaming, and for feeding results into other tools. Keep it as
the default.

Use `--output json` only for small results where a single pretty array is
more convenient. Use `--output tsv` when piping into `column`, `sort`, or
spreadsheets.

## Start narrow, then widen

When investigating, start with a small `--limit` and a short `--from`
window to validate the query shape cheaply, then widen once the query is
known to be correct.

```bash
# 1. sanity check — 50 rows, last 5 minutes
sumocli query '_sourceCategory=prod/api error' --from=-5m --limit 50 \
  > /tmp/sumocli/probe.ndjson

# 2. if the shape looks right, widen
sumocli query '_sourceCategory=prod/api error' --from=-1h --limit 10000 \
  > /tmp/sumocli/full.ndjson
```

## Messages vs records — what `--mode auto` does

Sumo has two result shapes:

From seruman/pi-things, MIT.

More from seruman/pi-things