DOCUMENTATION

Browser reports

The public endpoint a page sends its JavaScript errors and snapshots to.

A web page posts its JavaScript errors here, and a masked copy of the page beside the first one. The key is public: the Origin check and a per-address limit protect the endpoint.

Request

POST /api/v1/ingest/js/<js_key>
Origin: https://www.example.com
Content-Type: text/plain

The body is one report object or a JSON array of up to 10, at most 64 KB. text/plain keeps sendBeacon free of a CORS preflight; application/json works after one.

Example

curl

curl -X POST "https://codesafe.example/api/v1/ingest/js/$CODESAFE_JS_KEY" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: text/plain" \
  -d '[{"message": "Uncaught TypeError: cart is undefined", "name": "TypeError",
        "file": "https://www.example.com/assets/app.min.js", "line": 1, "col": 48211,
        "url": "https://www.example.com/checkout"}]'

JSON

[
  {
    "message": "Uncaught TypeError: cart is undefined",
    "name": "TypeError",
    "stack": "TypeError: cart is undefined\n    at submitOrder (https://www.example.com/assets/app.min.js:1:48211)",
    "file": "https://www.example.com/assets/app.min.js",
    "line": 1,
    "col": 48211,
    "url": "https://www.example.com/checkout?step=2",
    "priority": 3,
    "count": 4,
    "timestamp": 1793361900000,
    "release": "2.14.1",
    "environment": "production",
    "tags": ["shop", "eu"],
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "extra": {"userId": "1234", "snapshotId": "9f86d081884c7d65"}
  }
]

Fields

FieldTypeRequiredLimitWhat it does
messagestringno≤ 2,048 charsThe error's message
namestringno≤ 256 charsThe error class; Error when absent
stackstringno≤ 8,192 charsThe stack trace as text
filestringno≤ 512 charsThe URL of the script that threw
line, colintegernoWhere in that script; col lands in extra.col
urlstringnoa URLThe page: its host and path become the event's host and uri
priorityintegerno0–7Syslog severity; 3 when absent
countintegernoRepeats of this error in the page load; kept as extra.client_count
timestampnumber or stringnoepoch ms or s, ISO 8601When it happened
releasestringno≤ 64 charsThe deploy label; it also picks the source map
environmentstringno≤ 64 charsThe stage
tagsarray or stringno≤ 10 tagsFilterable tags
traceIdstringno≤ 64 charsThe trace id that links the report to the server's error
extraobjectno64 KBAnything else; a few keys are read, see below

codesafe reads these fields and ignores every other. The visitor's address, user agent and referer come from the request itself.

Snapshots

POST /api/v1/ingest/snapshot/<js_key>?id=<16 hex>&enc=gzip
Origin: https://www.example.com
Content-Type: application/octet-stream

The body is a masked copy of the page's HTML, raw or gzipped, at most 512 KB. The report names the same id in extra.snapshotId, and the event detail shows the page for 7 days.

ParameterRequiredLimitWhat it does
idyes16 lowercase hexChosen by the page; the first upload of an id wins
encnogzipSays the body is gzip; any other value answers 400

codesafe stores a snapshot as it arrives: masking inputs and private text is the page's job before the upload.

Through your own server

A page can post its reports to its own domain and let your server forward them, so the browser talks to your origin only. Each forwarded report then comes from your server's address, so your server names the visitor:

POST /api/v1/ingest/js/<js_key>
Origin: https://www.example.com
Content-Type: text/plain
X-Codesafe-Key: <api_key>
X-Codesafe-Visitor-Ip: 203.0.113.7
HeaderWhat it carries
X-Codesafe-KeyThe project's secret api_key, the one its server senders use. Only your server sends it; a page never sees it
X-Codesafe-Visitor-IpThe visitor's address as your server resolved it from the connection: one IPv4 or IPv6 address, never a value the browser sent
  • With the project's api_key and a valid address, the report is stored under that address and counts against that address's 30 requests a minute. ::ffff:203.0.113.7 is read as 203.0.113.7.
  • A forwarded report also counts against the project's budget for its api_key endpoints: 3,000 requests and 15,000 reports a minute, together with your server senders. Past it, 429 with Retry-After: 60.
  • A wrong key, or a value that is no single address, is ignored and never refused: the report counts as one from your server's own address.
  • Forward the method, the body and Content-Type byte for byte, and the browser's Origin, User-Agent and Referer. The Origin check, the first-party filter and the drop rules apply as to a direct report.
  • Pass codesafe's answer back unchanged: its status, its body and its Access-Control-* headers.
  • The snapshot endpoint reads neither header. Forwarded snapshots all count against your server's 30 a minute, so post them straight to codesafe or leave them off.

The api_key already lets a server sender name the visitor of its own errors, so forwarding with it gives your server nothing new.

With your web server. A few lines of configuration forward the client script and the project's report endpoint, and nothing else of codesafe. Replace codesafe.example with your codesafe address and <js_key> with the project's key; keep the api_key in a file or variable outside your repository.

nginx

# the client script and this project's report endpoint, nothing else
location = /codesafe/js/codesafe-client.min.js {
    proxy_pass https://codesafe.example/js/codesafe-client.min.js;
    proxy_ssl_server_name on;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
}

location = /codesafe/api/v1/ingest/js/<js_key> {
    limit_except POST OPTIONS { deny all; }
    proxy_pass https://codesafe.example/api/v1/ingest/js/<js_key>;
    proxy_ssl_server_name on;
    # holds the one line: proxy_set_header X-Codesafe-Key "<api_key>";
    include /etc/nginx/codesafe-key.conf;
    proxy_set_header X-Codesafe-Visitor-Ip $remote_addr;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
    proxy_connect_timeout 2s;
    proxy_read_timeout 2s;
    proxy_next_upstream off;
}

Apache

# in the virtual host, not .htaccess: mod_proxy, mod_proxy_http, mod_headers, mod_ssl
SSLProxyEngine on

<Location "/codesafe/js/codesafe-client.min.js">
    ProxyPass "https://codesafe.example/js/codesafe-client.min.js" timeout=2
    RequestHeader unset Cookie
    RequestHeader unset Authorization
</Location>

<Location "/codesafe/api/v1/ingest/js/<js_key>">
    ProxyPass "https://codesafe.example/api/v1/ingest/js/<js_key>" timeout=2
    <LimitExcept POST OPTIONS>
        Require all denied
    </LimitExcept>
    # CODESAFE_API_KEY comes from a Define or the server's environment
    RequestHeader set X-Codesafe-Key "${CODESAFE_API_KEY}"
    RequestHeader set X-Codesafe-Visitor-Ip "expr=%{REMOTE_ADDR}"
    RequestHeader unset Cookie
    RequestHeader unset Authorization
</Location>

The page then loads /codesafe/js/codesafe-client.min.js from your own domain and calls init({url: 'https://www.example.com/codesafe', key: '<js_key>'}).

  • Forward these exact paths only. A whole /codesafe/ prefix would put codesafe's sign-in and console on your domain.
  • The visitor is the address your web server sees ($remote_addr, REMOTE_ADDR). Behind a CDN or a load balancer, set up nginx's real_ip or Apache's mod_remoteip first, or every report names the balancer.
  • proxy_set_header and RequestHeader set replace what the browser sent, so a visitor can neither pick an address nor send a key.

Responses

StatusWhenWhat the client does
202Taken: a report answers {"success": true, "accepted": 1}, a snapshot {"success": true, "stored": true}Nothing
204The CORS preflight passedSend the request
400Malformed JSON, an empty batch or over 10 reports; a snapshot id, enc or body codesafe refusesFix the client; never retry
403The Origin is not on ALLOWED ORIGINS, or browser reports are offFix the project's settings
404Snapshots are off on this instanceStop sending snapshots
405The method is neither POST nor OPTIONSFix the client
409The snapshot id is taken: {"success": true, "stored": false}Drop it
413Over 64 KB of reports, or 512 KB of snapshotSend less
429The address sent over 30 requests this minute, the project's day of snapshots is spent, or a forwarded report is past the project's budgetDrop it
503codesafe cannot store it at the moment; Retry-After: 30 when it can sayDrop it, or retry once later

Notes

  • js_key is public. The Origin header must equal an allowed origin exactly, scheme://host[:port]: www and the bare domain are two origins.
  • A 403 carries no CORS headers, so the page cannot read it; ACTIVITY counts every one with the origin it refused.
  • Every report is stored as runtime: "browser", entry: "web" and kind: "error".
  • A dropped report still answers 202; accepted does not count it.
  • Reports and snapshots share the address's 30 requests a minute. No project budget applies: that limit holds a leaked key. Only a report your server forwards with the api_key also counts against the project's budget.
What codesafe drops on arrival
  • a report thrown by a browser extension or an in-app browser (chrome-extension:, moz-extension:, safari-extension:, iabjs:, gsa: …), read off file or the first frame of stack, on every project;
  • with the project's FIRST-PARTY FILTER on, the default, a report thrown by a script on any host but an allowed origin, a listed first-party host or the page's own;
  • a report less severe than the project's accept errors for priority ≤.
The extra keys codesafe reads
KeyWhat it becomes
userId, sessionIdthe event's user and session
snapshotIdthe link to the snapshot uploaded with that id
webdrivertrue flags the event webdriver
scriptsNotLoaded, scriptsFaileda non-empty list flags it scripts_missing or scripts_failed
tagsmore tags for this event, joined with the top-level tags
CORS

An allowed origin gets Access-Control-Allow-Origin with its own value, POST, OPTIONS as the methods, Content-Type as the only request header and a preflight cached for a day. A preflight from any other origin answers 403.

The snapshot budget

Each project takes 2,000 snapshots or 256 MiB of them a day, whichever comes first, from every address together. Past either, an upload answers 429 with Retry-After: 3600. A body that claims gzip and is none, or an empty body, answers 400.