# The workload

Every schema and cache choice is judged against what the product does all day: which calls arrive, how often, and what each costs. This file is how the agent gets that table, and it ends at stop 1.

## Real traffic first

Search the repository and its configuration for evidence of real traffic before modelling any:

| Source | What it gives |
| --- | --- |
| Request or access logs (web server, gateway, load balancer, the framework's request log) | calls per route per period, distinct callers |
| APM and tracing exports | calls, latency per route, the statements each call ran |
| The database's statement statistics (MySQL `performance_schema.events_statements_summary_by_digest`, Postgres `pg_stat_statements`, a managed database's query insights) | statements by shape, calls, rows read |
| The database's table and index statistics (MySQL `performance_schema.table_io_waits_summary_by_index_usage`, Postgres `pg_stat_user_tables` and `pg_stat_user_indexes`) | reads per index, and inserts, updates and deletes per table (`indexes.md` § A production service) |
| The cache's command statistics (Redis `INFO commandstats`) | commands by type |
| Product analytics | active people per day, sessions, page views |

Report what was searched and what was found. Real data, however partial, replaces the matching assumption below; a figure taken from it says where it came from.

## The synthetic workload

With no real data, build the table from the product's own behaviour and stated assumptions:

- **The usage model:** per active person per day, state every assumption — active time, page loads, session length, the share of people who run agents or scripts, the share who administer, the rare events (sign-ups, resets, edits).
- **Background loops come first:** an SDK's refresh, polling or heartbeat usually outnumbers everything a person does; read the SDK's documentation for its cadence and cite it.
- **The top calls:** about 20 rows — activity, endpoint, calls per active person per day, calls per 10,000, the share of people making it in a day.
- **The write model:** the monthly rate of every activity that writes, per active person: sign-ups, edits, password changes, sign-ins and sign-outs, enrolments, administrative changes, background flushes and purges. Reads alone decide caches, and indexes need both (`indexes.md`).
- **Sensitivity:** say which assumption moves the ranking and how far it can move before it does.

## The three temperatures

Each call is costed three ways:

- **Hot:** every cache the call uses holds its entry. An ideal hot call reads nothing from the database, so a database read here is one no cache covers.
- **Warm:** the call's own cache entries missed, are read from the database and written back. Process-local caches still hold.
- **Cold:** the first time — nothing cached anywhere (a process just started, a new tenant or record), plus every record the call creates.

**Notation:** database statements as reads (`R`), updates (`U`) and creates (`C`), the cold column naming the table of each create (`1C (sessions)`); cache commands as reads (`R`) and writes (`W`), where a write is any command that changes the cache, a renewed expiry and a write-back included; `1U flushed` for a write a background flush makes later. Add, per call, the hot round trips (database and cache) and whether the call sits on the page-load path.

## The cost trace

Dispatch one trace sub-agent at the cheapest capable tier, read-only, with the endpoint list and these instructions: count every statement and cache command each call issues at each temperature with `file:line` evidence; confirm how the cache helper maps to commands before counting; name the shared pieces many calls reuse (authentication, session load, the assembled user object, token minting) with an id each, so optimizers can cite them. Verify the counts the verdict will rest on directly.

## Stop 1

Write the table into the run folder (`docs/research/optimizer/{date}-{scope}/workload.md`) and return a report of at most 40 lines:

- the traffic sources searched and what each held;
- the question, when real data was partial or absent: where does production traffic live — logs, an APM, the database's statistics — or is the synthetic model acceptable;
- the usage model's assumptions, the table, the write model, and the share of database load by temperature;
- the price of the fan-out: the number of optimizers, the frame reviewer, the tracers, and their tiers.

The fan-out waits for the user's confirmation.