# Tickets

A ticket records a known problem that takes more than a moment to fix: a disk failing slowly, a service that keeps restarting, a backup that times out at night. It says what is wrong, what has been tried and, once resolved, what fixed it. Acknowledging an alert only quiets it. A ticket keeps the story, and while it is open the alerts and anomalies it covers read as a **known issue**.

Open the list from **Tickets** in the sidebar. A host's page, a monitor's page and a container's page each show a **Known issues** card with their open tickets. MCP clients use `list_tickets`, `get_ticket`, `open_ticket`, `update_ticket`, `comment_ticket`, `resolve_ticket` and `reopen_ticket`.

**Source:** `steward/tickets/` (`service.py` for every write, `routes.py` for the pages), `steward/mcp/tools/tickets.py`
**Tables:** `tickets`, `ticket_links`, `ticket_notes` (`steward/models/tickets.py`)

---

## What a ticket holds

| Field | |
|---|---|
| Number | `#12`, in order of opening |
| Title | What is wrong, one line (up to 200 characters) |
| Area | One of the timeline's areas (Settings → Timeline) |
| Hosts | The hosts it is on, by name; none for a problem not on any one host |
| Subject | What it is about when that is not a host as a whole: an alert rule's resource (`web-1:/`), a container (`web-1/nginx`), a monitor's name |
| Description | What is seen, since when, what has been tried |
| Links | Alert rules and metric anomalies it covers |
| Log | Opened, comments, edits (which fields changed, what was linked or unlinked), resolved, reopened, each with who and when |

A ticket is **open** or **resolved**. Resolving one needs a resolution: what fixed it, or why it no longer matters. Reopening clears it, with an optional reason.

## Opening one

- **From an alert:** **Open a ticket** on an active alert (Alerts page) fills in the title, area, hosts and subject from the rule, and links the rule.
- **From an anomaly:** **Open a ticket** on an anomaly to review, or one reviewed as real, does the same and links the anomaly.
- **From a page:** the **Known issues** card on a host, monitor or container opens one about it.
- **From scratch:** **Open a ticket** on the Tickets page.
- **Through MCP:** `open_ticket(title, area, description, hosts, subject, alert_rules, anomalies)`.

Opening, editing, commenting, resolving and reopening need an operator or admin. Viewers read everything.

## Known issues

An alert or anomaly is a known issue while an open ticket:

- links its alert rule (or the covering group rule it came from), or the anomaly;
- names its resource as its subject; or
- is about its host as a whole (no subject), when the resource is the host itself.

The Alerts page and the anomaly lists show a **Known issue** badge with the ticket. `list_alerts` and `list_anomalies` return the same as `known_issue`. `get_overview` lists up to ten open tickets in `open_tickets` and counts them all in `counts.tickets_open`. `get_host`, `get_monitor` and `get_container` carry their own `open_tickets`.

## On the timeline

Opening, resolving and reopening a ticket each write a timeline entry under the ticket's area, on its hosts and subject (`ticket.opened`, `ticket.resolved`, `ticket.reopened`, kind Ticket). The resolution is the resolved entry's note, so the timeline keeps what fixed it. Comments and edits stay in the ticket's own log.

Every step is audited (`ticket.opened`, `ticket.edited`, `ticket.commented`, `ticket.resolved`, `ticket.reopened`). Those audit rows stay off the timeline, which holds the ticket's own entries.

## Backups

Tickets are not in Steward's backups yet, the same as the timeline itself (`steward/backup/contents.py`, `EXCLUDED`).