http-log-stats

Files (2)

• SKILL.md
• http-log-stats.sh · scripts/

SKILL.md (first lines)

# HTTP Access Log Statistics

Answers **measurement** questions about HTTP traffic: how many of each status
code, how the request durations distribute, how many exceeded a threshold.

This is deliberately separate from `ingress-debug`, which diagnoses *why*
traffic fails (404 / 502 / TLS / no ADDRESS). Here nothing is broken
necessarily — the user wants numbers.

## Before you run it: identify the layer

A request usually passes through several components that can each return a
status code, and the user's word for the one they mean ("router", "gateway",
"entry", "网关") rarely maps to exactly one of them. **Counting on the wrong
layer produces a confident, wrong answer**, so establish the path first:

```bash
kubectl get ingress,svc,endpoints -n <ns> | grep <service>
```

- An Ingress in front → the user's "router 503" is almost certainly the
  **ingress controller's** access log. Use this skill.
- No Ingress, traffic reaches the Service directly → there is no access log to
  count; the numbers must come from the application's own logs or metrics, and
  the format is application-specific.
- **Do not** grep the application pod's log for the string `503`. Application
  logs contain the digits 503 in request bodies, upstream error text and
  unrelated fields; that count is not the number of HTTP 503 responses the
  entry layer returned.

This step costs one command and routinely saves the entire investigation.

## Tool

```
local_script: cluster="<cluster>", skill="http-log-stats",
              script="http-log-stats.sh", args="<args>"
```

Runs `kubectl` from the agent's own context — no debug pod, no node access.

**Set `cluster`** to the target cluster's credential name (from `cluster_list`).
`local_script` resolves it to a kubeconfig and exports `KUBECONFIG` into the
script's environment, so the `kubectl` calls inside the script pick it up
automatically. You may omit it only when the agent is bound to exactly one
cluster; with several bound, omitting it is an error listing the available
names, not a silent default.

Do **not** pass `--kubeconfig` or a `KUBECONFIG=` prefix in `args` — cluster
selection goes through the tool parameter, and the script takes no such flag.
If the name is wrong or the agent is not bound to that cluster, the call fails
with the available names; it never silently talks to the wrong cluster.

## Parameters

Required:

| Parameter | Description |
|-----------|-------------|
| `--since-time T` | Window start, RFC3339 UTC (`2026-08-17T12:02:06Z`). Absolute on purpose — see Notes. |

Optional:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `--until-time T` | now | Window end, RFC3339 UTC |
| `-n, --namespace N` | `ingress-nginx` | Controller namespace |
| `--selector S` | `app.kubernetes.io/name=ingress-nginx` | Pod label selector |
| `--pod P[,P2]` | — | Explicit pod names; overrides `--selector` |
| `--match S` | — | Only count lines containing this substring (ingress name, host, or path) |
| `--buckets a,b,c` | `1,10,60` | Duration bucket edges in seconds |
| `--preset P` | `nginx-ingress` | Access log format |

## Output

```
window:    2026-08-17T12:02:06Z .. 2026-08-17T14:02:06Z
source:    live cluster (kubectl logs), ns=ingress-nginx, 3 pod(s)
coverage:  FULL  (earliest retained line 2026-08-17T11:47:33Z)
match:     my-service
parsed:    1007 lines (status 1007, request_time 1007)

status codes:
  200      1000   99.3%
  499         7    0.7%

request_time buckets (seconds):
  <1        983   97.6%
  1-10       17    1.7%
  10-60       7    0.7%
  >=60        0    0.0%
```

### `coverage` is part of the answer — always report it

| Value | Meaning | What to tell the user |
|-------|---------|-----------------------|
| `FULL` | Live log reaches back past the window start | Report the numbers plainly |
| `PARTIAL` | Log only reaches back to a later point | **Say so.** The counts cover only from that point on — they are a lower bound, not the window total |
| `UNAVAILABLE` | No controller pod matched | There is no live source; do not report zero |
| `UNKNOWN` | Earliest line unreadable | Treat as PARTIAL and say the bound is unverified |

A count over a window the log no longer covers is not a smaller truth, it is a
wrong number. Never present `PARTIAL` results as the window total.

## Safety

Read-only, and it creates **no files** — not even a temporary one that is
cleaned up afterwards.

- Only two cluster verbs are ever issued: `kubectl get pods` and `kubectl logs`.
  Nothing is created, patched, deleted, or exec'd; no debug pod is spawned.
- No output redirection, no scratch file. Every log line is streamed through a
  pipe into a single `awk` that keeps only counters in memory, so a
  multi-gigabyte window costs a constant amount of RAM and zero disk.
- Shell constructs that create a temp file behind your back are avoided on
  purpose: no here-doc / here-string (bash backs those with a file in `$TMPDIR`
  before 5.1 and beyond the pipe buffer) and no `sort` (spills to `/tmp` above
  its memory threshold). `awk` formats the report itself.

From scitix/siclaw, Apache-2.0.

More from scitix/siclaw