# Reading attack logs and forensics

> Where attack history, timelines, and forensics live in the console, what each attack record field means, and how to tell a real attack from a traffic spike.
>
> Canonical: https://xdp.network/docs/attack-mitigation/reading-attack-logs · Updated 2026-08-09

Every attack the agent sees is recorded with the numbers you need for a post-mortem or a
support ticket. This page shows where that data lives and how to read it.

## Where attack data lives

Open the server in the console and go to its **Live metrics** tab. Three views matter:

- **Attack history** — one row per recorded attack.
- **Attack timeline** (`attack_timeline`) — state transitions: when detection fired, when
  mitigation engaged, when it ended.
- **Recent events** (`recent_events`) — the agent's latest event entries.

## What each attack record field means

| Field | Meaning |
| --- | --- |
| `number` | Sequential attack number — quote it in tickets |
| `type` | The attack classification |
| `start_time` / `end_time` | When detection opened and closed the incident |
| `duration_seconds` | Total length of the attack |
| `mitigated` | Whether the agent actively dropped traffic |
| `mitigation_seconds` | How long mitigation was engaged |
| `peak_pps` / `avg_pps` / `p95_pps` | Packet-rate peak, average, and 95th percentile |
| `peak_bps` | Peak bandwidth of the flood |
| `ips_involved` | How many source IPs took part |
| `top_countries` | Top source countries, each with `ips`, `peak_pps`, and `pct` |
| `forensics_dir` | On-disk directory with the attack's forensics |

## Telling a real attack from a traffic spike

Three signals separate an attack from a busy evening:

1. **`mitigated` is `true`** and `mitigation_seconds` is a real share of
   `duration_seconds` — the agent found offending traffic worth dropping, not just volume.
2. **The spike factor was clearly exceeded.** Compare `attack.current_pps` against
   `attack.spike_pps_threshold` (baseline × spike factor). A borderline crossing that ends
   in seconds is usually a flash crowd; a sustained multiple of baseline is an attack.
3. **Duration and source count.** A long `duration_seconds` with high `ips_involved`
   points to a distributed flood; a short spike from few sources rarely is.

:::note
`mitigated: false` with a brief threshold crossing usually means legitimate burst traffic.
Check what shipped or went viral before tuning thresholds.
:::

## Getting alerted

The agent can push alerts to your systems through the webhook alerter, configured with
`alerter.*` keys in `/etc/openshield/openshield.yaml`. The metrics payload reports its
health: `alerter.webhook_set`, `alerter.queued`, `alerter.sent`, and `alerter.last_error`.
If `last_error` is set, alerts are queuing but not arriving — see
[Common errors](/docs/troubleshooting/common-errors).

## Next steps

- [During an attack: what to do](/docs/attack-mitigation/during-an-attack)
- [Common errors](/docs/troubleshooting/common-errors)
- [Glossary](/docs/getting-started/glossary)