DOCUMENTATION

Rollups

Per-minute request counters: the traffic behind every error rate.

A server sender counts its requests per minute and posts one fragment per minute here, so codesafe reads error counts as rates against real traffic.

Request

POST /api/v1/ingest/rollup
X-Codesafe-Key: <api_key>
Content-Type: application/json

The body is one fragment: the counters of one finished minute from one process or pool, at most 16 KB. Several pools on one host each send their own, and codesafe adds them up.

Example

curl

curl -X POST https://codesafe.example/api/v1/ingest/rollup \
  -H "X-Codesafe-Key: $CODESAFE_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"minute\": $(( $(date +%s) / 60 - 1 )), \"instance\": \"web-1\", \"seq\": 1,
       \"requests\": 120, \"status\": {\"200\": 117, \"404\": 3}}"

JSON

{
  "minute": 29889360,
  "host": "web-03",
  "instance": "fpm-2",
  "seq": 88214,
  "requests": 18432,
  "status": {"200": 17801, "404": 187, "500": 11},
  "methods": {"GET": 17994, "POST": 421},
  "routes": {"/product/{slug}": 6104, "__unmatched": 187},
  "authed": {"yes": 2210, "no": 16222},
  "clients": 3421,
  "durations": {
    "__total": [17000, 1400, 20, 8, 3, 1, 0, 0, 0, 0, 0, 0],
    "/product/{slug}": [6000, 100, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0]
  },
  "durations_fine": {
    "__total": [9800, 5100, 2100]
  }
}

Fields

FieldTypeRequiredLimitWhat it does
minuteintegeryeswithin 90 minutes of codesafe's clockThe minute counted: epoch seconds divided by 60, rounded down
instancestringyes[A-Za-z0-9._-]{1,64}The process or pool that counted
hoststringno[A-Za-z0-9._-]{1,64}The server; tells two servers' pools apart
seqintegeryes≥ 0The fragment's number, rising per instance; makes a retry count once
requestsintegeryes0–100,000,000Every request that finished in the minute
statusobjectnokeys 100–599Requests per HTTP status
methodsobjectnoGET POST PUT PATCH DELETE HEAD OPTIONSRequests per method
routesobjectnoroute patterns, ≤ 200 charsRequests per matched route; __unmatched when none matched
authedobjectnoyes, noRequests by a signed-in user, and the rest
clientsintegerno0–100,000,000Distinct client addresses in the minute
durationsobjectno12 counts per keyRequest times per route; __total required when present
durations_fineobjectno3 counts per keyBucket 0 of durations split at 5, 10 and 25 ms
shield_observe, shield_block …objectnorule idsThe Shield's counters, sent by the official clients

Every counter is a JSON integer from 0 to 100,000,000; a zero is ignored. codesafe keeps what one minute of the site can count: clients at most requests, and no counter past 120 times the project's usual minute for that hour of day (never under 1,000). A counter past it is clipped and said in ACTIVITY; the fragment still answers 202.

Responses

StatusWhenWhat the client does
202Taken: {"success": true, "accepted": 1, "duplicate": false}; a replay answers accepted: 0, duplicate: trueNothing
400Malformed JSON, or a fragment codesafe refuses; error names the ruleFix the sender; never retry
401X-Codesafe-Key is missing, or no active project holds itFix the key
403The project takes no rollupsSwitch them on, or stop sending
405The method is not POSTFix the sender
413The fragment is over 16 KBFold more routes into __other
429The project's budget is spent; Retry-After: 60Retry once after it
503codesafe cannot store it at the momentRetry once later; the retry counts once

Notes

  • A project takes rollups while accept per-minute traffic rollups is on (DATA tab), the default for a new project. Off, a fragment answers 403 and writes nothing.
  • A route is the matched pattern, /product/{slug}, never the URI. A key with ? or % refuses the whole fragment.
  • Any broken rule refuses the whole fragment with 400; the message names the rule, never the value.
  • Rollups have no browser endpoint: a page sees one request, not the stream.
  • Nothing in a fragment may come from a request's content: no URI, no address, no user.
Duration buckets

The 12 counts in each durations vector are requests that took at most 25, 50, 100, 200, 400, 800, 1600, 3200, 6400, 12800 and 30000 ms, and the last one counts everything slower. Measure server time, from the request's start to its end. durations_fine splits bucket 0 into at most 5, 10 and 25 ms; a split that does not add up to bucket 0 is ignored for that key alone.

Routes past 40

A fragment keeps its 40 busiest routes; the rest are added into __other, counts and durations alike. __unmatched and __other never count against the 40.

How retries count once

codesafe remembers each fragment by host, instance, minute and seq for 26 hours. The same fragment again answers duplicate: true and adds nothing; a seq that starts over in a later minute still counts.

Reading it back

STATS → PERFORMANCE shows request times per route and the trend, and error rates per 10,000 requests appear in the release comparison. The MCP tool get_traffic answers the same counters for an agent.