Journal, metrics and state

Three ways to see what an emulator did and what it holds: the journal lists every request it received, metrics count them, and state reads and edits the stored rows directly.

#Interface

#Manual retry verification

Manual controls (/__admin/ui#manual) combines request targeting, bounded delay/timeout/503 faults, and a live filtered journal. Journal (/__admin/ui#journal) also shows attempt counts grouped by method, path and operation, with first and latest statuses. Both refresh every 1.5 seconds and have a Live/Paused switch. A new row after clicking Retry demonstrates another request reached the emulator; counts alone cannot distinguish retries from background polling. Requests appear when they finish or fail. Status 0 means a dropped connection.

#The journal

#GET /__admin/requests

One entry per vendor request the namespace received, oldest first. Admin calls are not journaled. Bodies are never recorded.

curl 'localhost:8787/__admin/requests?operationId=CreateCharge&status=503'

{
  "size": 1000,
  "requests": [
    {
      "service": "stripe",
      "namespace": "default",
      "operationId": "CreateCharge",
      "method": "POST",
      "path": "/v1/charges",
      "status": 503,
      "durationMs": 2000,
      "unmatched": false,
      "faultId": "fault_1",
      "delayMs": 2000,
      "at": "2030-01-01T00:00:02.000Z"
    }
  ]
}

size is how many entries each namespace keeps (journalSize, default 1000); the oldest fall off.

#DELETE /__admin/requests

Clear the namespace's journal. ?all=1 clears every namespace's.

curl -X DELETE localhost:8787/__admin/requests

{ "status": "ok" }

#Metrics

#GET /__admin/metrics

Totals for every namespace, or for one with ?namespace=<key> or the namespace header.

curl localhost:8787/__admin/metrics

{ "requests": 0, "byOperation": {}, "unmatched": [], "faults": 0, "totalDurationMs": 0 }

#DELETE /__admin/metrics

Clear them. Answers {"status": "ok"}.

curl -X DELETE localhost:8787/__admin/metrics

#State

Stored rows, without going through the vendor API. Use it to seed a record a test needs, or to assert on what a request wrote. Collection names and row shapes are the emulator's own.

#POST /__admin/state/<collection>

Create a row.

curl -X POST localhost:8787/__admin/state/customers \
  -d '{"id": "cus_1", "value": {"id": "cus_1", "email": "ada@example.com"}}'

{ "id": "cus_1", "seq": 1, "value": { "id": "cus_1", "email": "ada@example.com" } }

Status 201. seq is the row's position in its collection.

#GET /__admin/state

The namespace's collections, with the fields their rows hold.

curl localhost:8787/__admin/state

{
  "namespace": "default",
  "collections": [{ "name": "customers", "label": "Customers", "count": 1 }]
}

Each collection also lists its fields ({name, kind, optional}) and whether its shape was declared by the emulator or inferred from the rows.

#GET /__admin/state/<collection>

A page of rows. ?limit= (default 50, at most 200) and ?offset= page through them; next is the offset of the next page, or null.

curl localhost:8787/__admin/state/customers

{
  "collection": "customers",
  "count": 1,
  "records": [{ "id": "cus_1", "seq": 1, "value": { "id": "cus_1", "email": "ada@example.com" } }],
  "next": null
}

#GET /__admin/state/<collection>/<id>

One row, as {id, seq, value}.

curl localhost:8787/__admin/state/customers/cus_1

#PUT /__admin/state/<collection>/<id> · PATCH /__admin/state/<collection>/<id>

PUT replaces the row with {"value": …}. PATCH shallow-merges {"value": …} into it.

curl -X PATCH localhost:8787/__admin/state/customers/cus_1 -d '{"value": {"name": "Ada"}}'

{ "id": "cus_1", "value": { "id": "cus_1", "email": "ada@example.com", "name": "Ada" } }

#DELETE /__admin/state/<collection>/<id>

Delete a row. Answers its id.

curl -X DELETE localhost:8787/__admin/state/customers/cus_1

{ "id": "cus_1" }

A state edit is a write like any other: it files a checkpoint. PUT, PATCH and DELETE answer 404 for a row that is not there. To load many rows at once, import a snapshot document.

#The admin page

GET /__admin/ui and GET /__admin/ui/ serve the page. Open http://localhost:8787/__admin/ui. GET /__admin/ui/manifest lists the emulator's own panels beside the shared screens. The map of every shared screen is on Reference. Jump (⌘K or Ctrl+K) searches their names.

Snapshot restore is not on these screens. It is Snapshot & restore, its own page.

#In process

runtime.journal.list({ namespace: "default", operationId: "CreateCharge", status: 503 })
runtime.journal.clear("default")
runtime.metrics.report()            // every namespace
runtime.metrics.report("worker-3")
runtime.state("worker-3")           // { namespace, collections }

#Rules

• A namespace's journal and metrics are its own. Reset empties both. Restoring a snapshot leaves them: what happened is not undone.
• A faulted request is journaled with its faultId, and a dropped one with status 0.

#Errors

#Related

• Faults for the rules a faultId names.
• Snapshot and restore to save and load whole namespaces of rows.