---
name: clinic-loki
description: |
  Loki log query guidance for Clinic logs through clinic-cli.
---

# Loki logs

Use the parent CLI command:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py logs --help
```

Typical use:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py logs \
  --cluster-id <cluster_id> \
  --query '<logql>' \
  --start <start_unix_or_ns> \
  --end <end_unix_or_ns> \
  --limit 500
```

## Query rules

- For common follow-up log aggregation, prefer
  `clinic_cli.py ad-hoc logs` or `clinic_cli.py ad-hoc cpu-logs` before
  constructing broad LogQL manually.
- Use bounded incident windows.
- Start with targeted component filters when known, such as `tidb`, `tikv`, `pd`, or `tiflash`.
- Prefer focused regex terms for severe signals: panic, fatal, error, OOM, disk full, region unavailable, unavailable, timeout.
- Increase `--limit` only when sampling is insufficient.
- Treat empty logs as useful evidence only when the query and time range are clearly correct.
- The same `logs` command supports logical and physical BYOC IDs through the
  canonical org/cluster route. Data Proxy enforces the BYOC environment and
  physical namespace; do not add placement parameters or fall back to the
  historical `/data-proxy/loki/{cluster_id}` path.

## Common LogQL patterns

Panic or fatal:

```text
{container="tidb"} |~ `(?i)panic|fatal`
```

Errors:

```text
{container="tidb"} |~ `(?i)\\[error\\]|error`
```

Warnings:

```text
{container="tidb"} |~ `(?i)\\[warn(ing)?\\]|warning`
```

TiKV unavailable / timeout:

```text
{container="tikv"} |~ `(?i)unavailable|timeout|stale command|server is busy`
```

OOM signals:

```text
{container=~"tidb|tikv|pd"} |~ `(?i)oom|out of memory|memory quota`
```

## Interpretation notes

- Logs are supporting context unless they directly show an incident trigger.
- For performance diagnosis, correlate log timestamps with metrics and SQL evidence.
- Avoid broad all-component log pulls unless the user asks for general incident review.