{"result":{"depiction_url":null,"edges":{"in_module":{"objects":[{"created":"2026-11-11T09:19:20Z","object_id":{"id":1457,"is_a":["text","documentation","reference","module"],"name":"doc_module_mod_development","title":"mod_development","uri":"https:\/\/zotonic.com\/id\/1457"},"seq":1}],"predicate":{"id":333,"is_a":["meta","predicate"],"name":"in_module","title":{"_type":"trans","tr":{"en":"In module"}},"uri":"https:\/\/zotonic.com\/id\/in_module"}},"refers":{"objects":[{"created":"2026-11-11T12:17:46Z","object_id":{"id":1457,"is_a":["text","documentation","reference","module"],"name":"doc_module_mod_development","title":"mod_development","uri":"https:\/\/zotonic.com\/id\/1457"},"seq":1000000},{"created":"2026-11-11T12:17:46Z","object_id":{"id":3182,"is_a":["text","documentation","reference","model"],"name":"doc_model_model_development_tools","title":"development_tools","uri":"https:\/\/zotonic.com\/id\/3182"},"seq":1000000}],"predicate":{"id":2409,"is_a":["meta","predicate"],"name":"refers","title":{"_type":"trans","tr":{"en":"Refers"}},"uri":"https:\/\/zotonic.com\/id\/refers"}},"subject":{"objects":[{"created":"2026-11-11T09:19:20Z","object_id":{"id":2555,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_reference","title":"Reference","uri":"https:\/\/zotonic.com\/id\/2555"},"seq":1},{"created":"2026-11-11T09:19:20Z","object_id":{"id":2563,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_frontend_developer","title":"Frontend developer","uri":"https:\/\/zotonic.com\/id\/2563"},"seq":2},{"created":"2026-11-11T09:19:20Z","object_id":{"id":2564,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_backend_developer","title":"Backend developer","uri":"https:\/\/zotonic.com\/id\/2564"},"seq":3},{"created":"2026-11-11T09:19:20Z","object_id":{"id":2607,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_logging_and_monitoring","title":"Logging and monitoring","uri":"https:\/\/zotonic.com\/id\/2607"},"seq":4},{"created":"2026-11-11T09:19:20Z","object_id":{"id":2613,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_development_and_debugging","title":"Development and debugging","uri":"https:\/\/zotonic.com\/id\/2613"},"seq":5},{"created":"2026-11-11T09:19:20Z","object_id":{"id":2625,"is_a":["categorization","keyword","keyword_architecture"],"name":"zotonic_topic_model","title":"Model","uri":"https:\/\/zotonic.com\/id\/2625"},"seq":6}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"export_revision":24,"id":3183,"is_a":["text","documentation","reference","model"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/3183"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_model_model_development_capture","page_url":{"en":"https:\/\/zotonic.com\/docs\/3183\/development_capture","x-default":"https:\/\/zotonic.com\/docs\/3183\/development_capture"},"preview_url":null,"resource":{"version":8,"pivot_location_lat":null,"title":"development_capture","is_authoritative":true,"body":"

Capture template rendering and browser console output from an open page without\nlosing its current state. Use this model with model#development_tools<\/code><\/a> to inspect\nhow a page is built and verify conditional or lazy rendering.<\/p>\n

For local and remote workflows, see the\nLLM site development guide<\/a>.<\/p>\n

Access and setup<\/h2>\n

Enable module#mod_development<\/code><\/a> on the site. All data and mutation endpoints\nrequire an administrator with use mod_development<\/code> permission and a site\nenvironment of development<\/code>, test<\/code>, or acceptance<\/code>. Production is denied,\nincluding trusted CLI calls. The console_allowed<\/code> capability probe returns a\nboolean rather than an access error.<\/p>\n

Read-only administrators can list captures and read their status, traces, and\nlogs. Attaching, starting, stopping, and submitting logs require write access.\nAttaching to an existing capture and submitting logs also require the browser\nsession that created it. Session IDs are never returned.<\/p>\n

The browser API is window.z_development_capture<\/code>. Its script is included on\nauthorized pages when the floating template trace button is enabled. Use the\nnormal development head assets; the button and JavaScript use the same API.<\/p>\n

Capture an open page<\/h2>\n

Run this in the intended page's browser console or browser execution tool:<\/p>\n

const capture = await window.z_development_capture.attach();\n\/\/ Interact with the page: scroll, open a panel, or trigger a lazy component.\nawait window.z_development_capture.flush();\nconst trace = await window.z_development_capture.trace();\nconst logs = await window.z_development_capture.console();\nawait window.z_development_capture.stop();\n<\/code><\/pre>\n
trace<\/code> contains {capture, nodes, edges}<\/code>. logs<\/code> contains\n{entries, truncated}<\/code>; each entry has seq<\/code>, text<\/code>, and received_at<\/code>.\nRead results through the execution tool's return value rather than logging them\nback into the capture. Reads do not submit or clear browser logs.<\/p>\n
JavaScript reference<\/h2>\n
All methods return promises. Permission and transport failures reject; model\nerrors expose error.code<\/code>. An optional ID defaults to the page's attachment.<\/p>\n
Method<\/th>Behavior<\/th><\/tr><\/thead>
list()<\/code><\/td>GET all available capture summaries; returns []<\/code> when none exist.<\/td><\/tr>
status(captureId?)<\/code><\/td>GET a capture summary.<\/td><\/tr>
trace(captureId?)<\/code><\/td>GET the accumulated template graph.<\/td><\/tr>
console(captureId?)<\/code><\/td>GET stored console entries without flushing pending logs.<\/td><\/tr>
attach()<\/code><\/td>Reuse the page's attachment or create one; start it if stopped.<\/td><\/tr>
attach(captureId)<\/code><\/td>Validate write access and session ownership, then reconnect and start if stopped.<\/td><\/tr>
start(captureId)<\/code><\/td>Start an existing capture; an ID is required.<\/td><\/tr>
stop()<\/code><\/td>Flush this page's pending logs, then stop its capture.<\/td><\/tr>
stop(captureId)<\/code><\/td>Stop an existing capture without flushing this page's logs.<\/td><\/tr>
flush()<\/code><\/td>Submit this page's pending logs without starting or stopping its capture.<\/td><\/tr>
detach()<\/code><\/td>Clear the local attachment and pending logs, restore console.log<\/code>, and leave the server capture running.<\/td><\/tr><\/tbody><\/table>\n
Status and evidence reads return null<\/code> when the capture is missing or expired,\nor when no page attachment exists. Explicit-ID start\/stop also return null<\/code>\nfor a missing capture. Explicit-ID reads and start\/stop do not change the local\nattachment or sessionStorage, including on errors.<\/p>\n
attach(captureId)<\/code> rejects missing, expired, or foreign-session IDs; it never\ncreates a replacement. Validation and start must succeed before the ID is saved.\nSwitching IDs discards the previous browser buffer; call flush()<\/code> first to retain\nit. Reconnecting the same ID preserves that buffer.<\/p>\n
flush()<\/code> returns status, or null<\/code> when unattached or expired. It does not submit\nto a stopped capture. detach()<\/code> returns null<\/code>, makes no network request, and\nworks offline and with read-only access. Queued local commands and late replies\ncannot reattach a detached page; already-sent server requests may still complete.\nDo not automatically retry mutations after a timeout.<\/p>\n
Ownership and capture summaries<\/h2>\n
List and status results contain these fields:<\/p>\n
Field<\/th>Meaning<\/th><\/tr><\/thead>
id<\/code><\/td>Capture ID used by every interface.<\/td><\/tr>
path<\/code><\/td>Page path recorded at attachment; tracing is session-scoped, not restricted to this path.<\/td><\/tr>
state<\/code><\/td>active<\/code> or stopped<\/code>.<\/td><\/tr>
expires<\/code><\/td>Absolute expiry time, in Unix seconds.<\/td><\/tr>
truncated<\/code><\/td>A graph or server console limit has been reached.<\/td><\/tr>
trace_scope<\/code><\/td>session<\/code>. Other tabs in the session may contribute renders.<\/td><\/tr>
is_owner<\/code><\/td>Whether this request has the browser session that created the capture. False without a session.<\/td><\/tr>
write_allowed<\/code><\/td>Whether the caller may mutate captures; independent of ownership.<\/td><\/tr>
console_allowed<\/code><\/td>Whether the caller may access console diagnostics.<\/td><\/tr><\/tbody><\/table>\n
To find a capture this browser can reconnect to:<\/p>\n
const captures = await window.z_development_capture.list();\nconst owned = captures.find(c => c.is_owner && c.write_allowed);\nif (owned) {\n    await window.z_development_capture.attach(owned.id);\n}\n<\/code><\/pre>\n
Read-only owners cannot attach or submit logs. Writable non-owners can start or\nstop captures by ID but cannot attach or submit browser logs. Server checks are\nauthoritative; the flags help clients select the right operation.<\/p>\n
The browser requires is_owner === true<\/code> before wrapping console.log<\/code> or\nsubmitting logs. Local attach\/flush\/stop and background polling refresh status\nfirst. Lost or missing ownership restores normal console output and discards\npending logs. Local mutations reject with eacces<\/code>; background polling uses GET\nonly. Use detach()<\/code> to clear a stale local attachment.<\/p>\n
HTTP and MQTT endpoints<\/h2>\n
HTTP uses \/api\/model\/development_capture\/<method>\/<path><\/code>. Browser MQTT calls\nuse bridge\/origin\/model\/development_capture\/<method>\/<path><\/code>; a direct server\nMQTT client uses model\/development_capture\/<method>\/<path><\/code>.<\/p>\n
Method<\/th>Path<\/th>Payload<\/th>Result<\/th><\/tr><\/thead>
GET<\/td>console_allowed<\/code><\/td>None<\/td>Capability boolean.<\/td><\/tr>
GET<\/td>list<\/code><\/td>None<\/td>Array of capture summaries.<\/td><\/tr>
GET<\/td>status\/ID<\/code><\/td>None<\/td>Capture summary.<\/td><\/tr>
GET<\/td>trace\/ID<\/code><\/td>None<\/td>{capture, nodes, edges}<\/code>.<\/td><\/tr>
GET<\/td>console\/ID<\/code><\/td>None<\/td>{entries, truncated}<\/code>.<\/td><\/tr>
POST<\/td>attach<\/code><\/td>{path: "\/example"}<\/code><\/td>New, stopped capture bound to the caller's browser session.<\/td><\/tr>
POST<\/td>start\/ID<\/code><\/td>None<\/td>Active capture summary; existing evidence is retained.<\/td><\/tr>
POST<\/td>stop\/ID<\/code><\/td>None<\/td>Stopped capture summary.<\/td><\/tr>
POST<\/td>poll\/ID<\/code><\/td>{entries: ["message"]}<\/code><\/td>Submit logs to an active capture and return status; requires the owning session.<\/td><\/tr><\/tbody><\/table>\n
HTTP JSON and MQTT response payloads use {status: "ok", result: ...}<\/code> or\n{status: "error", error: ...}<\/code>. Raw model endpoints return enoent<\/code> for missing\nor expired captures; JavaScript methods translate it to null<\/code> where described\nabove. eacces<\/code> denotes denied access; invalid arguments or a foreign-session\npoll can return badarg<\/code>.<\/p>\n
An OAuth2 administrator token can inspect existing captures and, with write\naccess, start\/stop them. A token without the owning browser session cannot\nattach to that capture or submit its console logs. The browser normally handles\nattachment and polling; CLI\/API control alone does not collect browser output.<\/p>\n
CLI and SSH<\/h2>\n
Run from the server's Zotonic checkout as its normal server user:<\/p>\n
bin\/zotonic capture mysite list\nbin\/zotonic capture mysite status CAPTURE_ID\nbin\/zotonic capture mysite start CAPTURE_ID\nbin\/zotonic capture mysite trace CAPTURE_ID\nbin\/zotonic capture mysite console CAPTURE_ID\nbin\/zotonic capture mysite stop CAPTURE_ID\n<\/code><\/pre>\n
For remote access, run the same commands through SSH:<\/p>\n
ssh site-host 'cd \/srv\/zotonic && bin\/zotonic capture mysite list'\n<\/code><\/pre>\n
CLI commands use trusted Erlang node RPC and still enforce the environment\nrestriction. They return JSON {ok: true, result: ...}<\/code> or\n{ok: false, error: ...}<\/code>, with a nonzero exit status for failures.<\/p>\n
Lifetime and limits<\/h2>\n
  • A capture expires ten minutes after creation. Polling and restarting do not\nextend it. Stopping retains evidence until expiry.<\/li>
  • At most 16 captures exist per site. Attach a fresh capture for a fresh graph;\nstarting an existing one is idempotent and retains evidence.<\/li>
  • The graph is capped at approximately 1,000 nodes and 5,000 edges. Console\nhistory retains the latest 500 entries, up to 4,096 bytes each and 50 per upload.<\/li>
  • Browser console collection covers subsequent console.log<\/code> calls only. It is\nbest effort: overflow, navigation, disconnection, or remote stopping can lose logs.<\/li>
  • The browser polls every second. Attachment survives reload via sessionStorage;\nrenders before attachment cannot be reconstructed. Attach before reloading to\ntrace the initial render. Duplicated tabs may inherit the stored attachment.<\/li>
  • This API provides template traces and console text, not screenshots, DOM\nsnapshots, historical console output, or browser action execution.<\/li><\/ul>\n
    Existing human template tracing remains independent of capture sessions.<\/p>","slug":"development_capture","is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"doc_source_hash":"d6035bba66bf8e303125b5a224c0002f1d6e711129695e6df50c98d678dc4934","is_featured":false,"content_group_id":{"id":2551,"is_a":["meta","content_group"],"name":"content_group_imported_docs","title":"Imported documentation","uri":"https:\/\/zotonic.com\/id\/content_group_imported_docs"},"category_id":{"id":322,"is_a":["meta","category"],"name":"model","title":"Models","uri":"https:\/\/test.zotonic.com\/id\/322"},"doc_source_path":"apps\/zotonic_mod_development\/src\/models\/m_development_capture.erl","publication_start":"2026-11-11T09:19:20Z","github_url":"https:\/\/github.com\/zotonic\/zotonic\/blob\/master\/apps\/zotonic_mod_development\/src\/models\/m_development_capture.erl","pivot_location_lng":null,"doc_source_kind":"model","name":"doc_model_model_development_capture","is_unfindable":false,"is_published":true,"pivot_geocode":null,"created":"2026-11-11T09:19:20Z","uri":null,"doc_status":"current","is_dependent":false,"erlang_app":"zotonic_mod_development","publication_end":"9999-06-01T00:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_source_commit":"8e6aad17c4d86dee983db46a656ed6f6a930bcbb\n","erlang_module":"m_development_capture","creator_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"modified":"2026-11-11T14:07:16Z","title_slug":"development_capture"},"uri":"https:\/\/zotonic.com\/id\/3183","uri_template":"https:\/\/zotonic.com\/id\/:id","version":24,"websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/3183"}},"status":"ok"}