Five minutes, one HTTP call. No SDK is required and nothing has to be installed on codesafe side.
1. Get a key
- In codesafe, open PROJECTS and create a project.
- Copy its
api_key— 64 hex characters, secret, server-side only. The grid shows it masked; the row menu's COPY API KEY copies it in full. - A browser app uses the project's
js_keyinstead. It is public by design and is checked against the project's allowed origins. Browser reports are off for a new project: on its REPORTING tab, tick accept browser reports and list every origin the page runs on, with scheme and port. The match is exact.
Why two keys? A browser cannot keep a secret. The public key names the project, and the Origin allowlist decides what is taken. A leaked js_key lets someone post browser-shaped reports that claim one of your origins — 30 requests a minute per address, 10 reports each, whitelisted fields only — but it reads nothing and opens none of the server doors.
2. Send one error
Every client does the same thing underneath: one POST with JSON in the body. A server sends its secret api_key in the X-Codesafe-Key header; a browser sends its public js_key in the URL (/api/v1/ingest/js/<js_key>). Pick your runtime.
curl
curl -X POST https://yourcodesafe.cloud/api/v1/ingest \
-H "X-Codesafe-Key: $CODESAFE_KEY" \
-H "Content-Type: application/json" \
-d '{
"v": 1,
"runtime": "php",
"entry": "web",
"kind": "error",
"priority": 3,
"message": "Hello from curl",
"events": [{"message": "Hello from curl", "className": "RuntimeException"}]
}'PHP
$payload = [
'v' => 1,
'runtime' => 'php',
'entry' => 'web',
'kind' => 'error',
'priority' => 3,
'message' => $throwable->getMessage(),
'events' => [[
'message' => $throwable->getMessage(),
'className' => $throwable::class,
'file' => $throwable->getFile(),
'line' => $throwable->getLine(),
'backtrace' => $throwable->getTraceAsString(),
]],
];
// give the visitor their page BEFORE spending a millisecond on telemetry:
// under php-fpm this flushes the response and ends the request for the
// browser, while this process keeps running. Call it last: anything the
// app still meant to print after it is lost
if(function_exists('fastcgi_finish_request'))
{
fastcgi_finish_request();
}
$curl = curl_init('https://yourcodesafe.cloud/api/v1/ingest');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Codesafe-Key: ' . $key],
CURLOPT_TIMEOUT_MS => 1000, // never let reporting slow a request
CURLOPT_RETURNTRANSFER => true,
]);
@curl_exec($curl); // fire and forget: failures are swallowedWordPress
Download ovos-codesafe.zip from the latest release and install it under
Plugins → Add New Plugin → Upload Plugin, then activate it.
https://github.com/ovos/codesafe-client-wordpress/releases/latest
Under Settings → ovos codesafe, type codesafe's address and press Connect.
Sign in, pick the project, and the URL and both keys arrive by themselves:
reporting is enabled and a test error is sent.
PHP errors, failed logins and scanner probes are reported from then on,
with no code in your theme. JavaScript errors also need the project's
browser reports switched on in codesafe: Connect adds the site's origin,
not the switch.Node.js
const report = async (error) => {
const body = JSON.stringify({
v: 1,
runtime: 'node',
entry: 'web',
kind: 'error',
priority: 3,
message: error.message,
events: [{message: error.message, className: error.name, backtrace: error.stack}],
});
// never await this on the request path; a timeout is dropped, never retried
await fetch('https://yourcodesafe.cloud/api/v1/ingest', {
method: 'POST',
headers: {'Content-Type': 'application/json', 'X-Codesafe-Key': process.env.CODESAFE_KEY},
body,
signal: AbortSignal.timeout(1000),
}).catch(() => {});
};Browser
<script src="https://yourcodesafe.cloud/js/codesafe-client.js"></script>
<script>
ovosCodesafe.init({
url: 'https://yourcodesafe.cloud',
key: 'YOUR_PUBLIC_JS_KEY',
});
</script>Python
import json, urllib.request
def report(exc: BaseException, key: str) -> None:
body = json.dumps({
"v": 1,
"runtime": "python",
"entry": "web",
"kind": "error",
"priority": 3,
"message": str(exc),
"events": [{"message": str(exc), "className": type(exc).__name__}],
}).encode()
req = urllib.request.Request(
"https://yourcodesafe.cloud/api/v1/ingest",
data=body,
headers={"Content-Type": "application/json", "X-Codesafe-Key": key},
)
try:
urllib.request.urlopen(req, timeout=1)
except Exception:
pass # reporting may never break the callerGo
body, _ := json.Marshal(map[string]any{
"v": 1,
"runtime": "go",
"entry": "web",
"kind": "error",
"priority": 3,
"message": err.Error(),
"events": []map[string]any{{"message": err.Error(), "className": "error"}},
})
req, _ := http.NewRequest("POST", "https://yourcodesafe.cloud/api/v1/ingest", bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Codesafe-Key", key)
client := &http.Client{Timeout: time.Second}
resp, err := client.Do(req) // ignore the error: never fail the caller
if err == nil {
resp.Body.Close()
}Java
// the JDK writes no JSON: escape every string that goes into the body
static String json(String value) {
var out = new StringBuilder("\"");
for (char c : value.toCharArray()) {
if (c == '"' || c == '\\') out.append('\\').append(c);
else if (c < 0x20) out.append("\\u%04x".formatted((int) c));
else out.append(c);
}
return out.append('"').toString();
}
static void report(Throwable e, String codesafe, String key) {
var message = json(Objects.toString(e.getMessage(), ""));
var payload = """
{"v":1,"runtime":"java","entry":"web","kind":"error","priority":3,
"message":%s,"events":[{"message":%s,"className":%s}]}
""".formatted(message, message, json(e.getClass().getName()));
var request = HttpRequest.newBuilder(URI.create(codesafe + "/api/v1/ingest"))
.header("Content-Type", "application/json")
.header("X-Codesafe-Key", key)
.timeout(Duration.ofSeconds(1)) // hard cap, always
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
// fire and forget: the future is never joined on the request path
HttpClient.newHttpClient()
.sendAsync(request, HttpResponse.BodyHandlers.discarding())
.exceptionally(t -> null);
}Rust
// reqwest, but any client works — this is one POST
let payload = serde_json::json!({
"v": 1,
"runtime": "rust",
"entry": "web",
"kind": "error",
"priority": 3,
"message": err.to_string(),
"events": [{ "message": err.to_string(), "className": "Error" }],
});
let client = reqwest::Client::builder()
.timeout(std::time::Duration::from_secs(1))
.build()?;
// spawned, never awaited by the handler: reporting must not add latency
tokio::spawn(async move {
let _ = client
.post(format!("{codesafe}/api/v1/ingest"))
.header("X-Codesafe-Key", key)
.json(&payload)
.send()
.await; // errors are deliberately ignored
});OpenTelemetry
# already instrumented? add codesafe to the collector's logs pipeline
receivers:
otlp:
protocols:
grpc:
http:
processors:
batch: # codesafe takes 200 records per request
send_batch_size: 200
send_batch_max_size: 200
exporters:
otlphttp/codesafe:
logs_endpoint: https://yourcodesafe.cloud/api/v1/ingest/otel
encoding: json
headers:
X-Codesafe-Key: ${env:CODESAFE_KEY}
service:
pipelines:
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/codesafe]A 202 means it is queued; the OpenTelemetry door answers 200 instead. It appears in EVENTS within about a second. The answer's accepted can be lower than what you sent: the project's priority gate, its 404 and security switches and, for browser reports, its first-party filter drop events on purpose.
3. What you get without doing anything else
- Grouping. The same fault a thousand times is one issue with a count.
- Priority. 0–7 on arrival, per project, so the gate is yours.
- Trace correlation. Put the request's trace id in
context.traceIdand a browser failure lines up with the server error behind it. The browser client sends atraceparentheader on same-origin calls for your server to read it from. - Lifecycle. Open, resolved or muted, per issue, with history. An issue that comes back after a resolve reopens as a regression.
4. Then send the parts that pay
A new project takes all four already. What decides is the sender.
| part | what it buys | what the sender does |
|---|---|---|
| 404 reporting | scanner probes, counted apart from bugs | sends kind: "not_found", the path as the message |
| security events | failed logins, refused actions, privileged changes | sends kind: "security" with a name from a closed list |
| traffic rollups | error counts read as rates, not raw numbers | counts requests per minute: APCu in PHP, memory in Node |
| software inventory | CVE matches against what you actually run | sends what is installed, with versions |
The WordPress plugin starts with all four on. The PHP library (ovos/php-library) sends the inventory unless told not to; 404s and rollups are switches you turn on, and a security event is a reportRefusal() call in your code.
Rules that keep reporting safe
- Fire and forget. Never await the report on the request path.
- One second, hard. A codesafe instance that is down must cost your users nothing.
- Never retry what may have arrived. A timeout after the body went out may already be stored. Drop it — or retry once, a second later and off the request path, only a connection that never opened, a
429/503, or a proxy's502/504. - Redact before sending. Passwords, tokens and cookies never leave the box.
- Batch, then flush. PHP collects during the request and sends once after the response has gone out. A long-running process flushes on a short timer, every second or two, and at exit. At most 50 per POST, and under 256 KB.
The long version, with the field reference and the failure rules, is in Build your own client and the API reference.
Next: Build your own client for the rules in full, Browser client for JavaScript errors, or Errors for every field.
No client for your stack?
A client is one POST, so anything that speaks HTTP can report. But you do not have to write it:
- We build CMS clients on request — TYPO3, Drupal, Shopware, or something in-house. Tell us what you run and we write the client and integrate it.
- WordPress is already done and public.
- Write to office@ovos.at with the platform and its version.