An OpenTelemetry Collector or SDK exports its log records here, and they become codesafe events; the metrics path takes the rollup request counter.
Request
POST /api/v1/ingest/otel/v1/logs
X-Codesafe-Key: <api_key>
Content-Type: application/json
Content-Encoding: gzip
The body is an OTLP/JSON ExportLogsServiceRequest, gzipped or plain, at most 1 MiB on the wire and 8 MiB inflated. /api/v1/ingest/otel alone is the same logs endpoint; metrics have a path of their own, below.
Example
curl
curl -X POST https://codesafe.example/api/v1/ingest/otel/v1/logs \
-H "X-Codesafe-Key: $CODESAFE_KEY" \
-H "Content-Type: application/json" \
--data @logs.jsonJSON
{
"resourceLogs": [{
"resource": {"attributes": [
{"key": "service.name", "value": {"stringValue": "shop-api"}},
{"key": "service.version", "value": {"stringValue": "2.14.1"}},
{"key": "deployment.environment.name", "value": {"stringValue": "production"}},
{"key": "telemetry.sdk.language", "value": {"stringValue": "python"}}
]},
"scopeLogs": [{
"scope": {"name": "shop.checkout"},
"logRecords": [{
"timeUnixNano": "1793361600000000000",
"severityNumber": 17,
"body": {"stringValue": "payment provider timed out"},
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"attributes": [
{"key": "exception.type", "value": {"stringValue": "TimeoutError"}},
{"key": "url.path", "value": {"stringValue": "/checkout/pay"}},
{"key": "http.request.method", "value": {"stringValue": "POST"}}
]
}]
}]
}]
}Fields
| Field | Type | Required | Limit | What it does |
|---|---|---|---|---|
body | record field | one name | ≤ 2,048 chars | The message; a structured body is kept as JSON |
severityNumber | record field | no | 1–24 | Priority: FATAL 2, ERROR 3, WARN 4, INFO 6, DEBUG and TRACE 7 |
severityText | record field | no | Read when no number is sent; neither gives 3 | |
timeUnixNano | record field | no | nanoseconds | When it happened; else observedTimeUnixNano |
traceId | record field | no | ≤ 64 chars | The trace id: links one request across services |
exception.type | attribute | one name | ≤ 256 chars | The class; a browser record without one is Error |
exception.message | attribute | one name | ≤ 2,048 chars | The exception's message, and the message when body is empty |
exception.stacktrace | attribute | no | ≤ 8,192 chars | The backtrace |
code.file.path | attribute | one name | ≤ 512 chars | The file; part of the grouping except on browser records |
code.line.number, code.column.number | attribute | no | The line, and the column as extra.col | |
kind, entry, runtime | attribute | no | the closed lists | codesafe's axes; error, web and the SDK's language when absent |
event.name | attribute | no | a security name | A security record's name when exception.type is absent |
url.path, url.query, url.full | attribute | no | ≤ 2,048 chars | The request's uri |
http.request.method, user_agent.original | attribute | no | The method and the user agent | |
client.address | attribute | no | an IP address | The visitor's address |
http.request.header.<name>, http.request.body.content | attribute | no | The request a replay re-issues; referer is the referring page | |
session.id, user.id | attribute | no | The session and the user; enduser.id when user.id is absent | |
tags | attribute, resource | no | ≤ 10 tags | A string array or one string; the record's and the resource's are joined |
extra.<key> | attribute | no | Lands in extra as <key> | |
service.name | resource | no | ≤ 255 chars | The host, the EVENTS grid's application column; else host.name |
service.version | resource | no | ≤ 64 chars | The release |
deployment.environment.name | resource | no | ≤ 64 chars | The environment |
telemetry.sdk.language | resource | no | The runtime; webjs makes a browser record, nodejs is node | |
process.command_args | resource | no | The command line |
One name: a record needs a body, exception.message, exception.type or code.file.path (a security record its event.name), or it is dropped and counted in partialSuccess. Every other attribute lands in extra.
Metrics
POST /api/v1/ingest/otel/v1/metrics
X-Codesafe-Key: <api_key>
Content-Type: application/json
The OTLP way to send traffic rollups. codesafe takes one counter and reports every other data point back in partialSuccess; a project that takes no rollups answers 403.
| Rule | What codesafe takes |
|---|---|
| Name | codesafe.rollup.requests |
| Shape | a Sum with isMonotonic: true and DELTA temporality |
| Value | asInt, 0–100,000,000 |
| Time | timeUnixNano within 90 minutes of codesafe's clock |
| Attributes | route, status, method, authed as string values, from the rollup vocabulary |
| Resource | service.instance.id, else host.name, matching [A-Za-z0-9._-]{1,64} |
A data point counts into requests and into every attribute it names, so send one stream per attribute combination: separate counters per dimension would count each request several times. A retried point counts once.
Responses
| Status | When | What the client does |
|---|---|---|
200 | {}: every record or data point taken | Nothing |
200 | {"partialSuccess": {"rejectedLogRecords": 2, "errorMessage": "…"}}; metrics say rejectedDataPoints | Read the message; never resend |
400 | Malformed JSON, or a body that does not decode or inflates past 8 MiB | Fix the exporter |
401 | X-Codesafe-Key is missing, or no active project holds it | Fix the key |
403 | Metrics, for a project that takes no rollups | Switch rollups on, or stop exporting |
404 | A signal other than logs or metrics, such as /v1/traces | Export it elsewhere |
405 | The method is not POST | Fix the exporter |
413 | Over 1 MiB on the wire | Send smaller batches |
415 | Protobuf, or a Content-Encoding codesafe does not decode | Set encoding: json, and gzip or no compression |
429 | The project's budget is spent; Retry-After: 60 | The exporter retries after it |
503 | codesafe cannot store it at the moment; mostly Retry-After: 30 | The exporter retries after it |
A failure answers a google.rpc.Status, such as {"code": 3, "message": "malformed JSON"}, not codesafe's envelope.
Notes
- Set
encoding: jsonon theotlphttpexporter: protobuf answers415. - The exporter's plain
endpoint:appends/v1/logs,/v1/metricsand/v1/tracesitself; traces answer404, and the exporter drops them. - A request takes 200 log records; set the batch processor's
send_batch_max_sizeto 200. - Records pass the same gates as every event, and INFO lines are stored by default: filter in the collector.
What partialSuccess counts
Records past the 200th, records with no name, records less severe than the project's accept priority, a not_found or security record the project does not take or whose name is not on the list, and browser records thrown by an injected or third-party script. Ignore rules run after the answer and are never counted.
Browser records
A resource with telemetry.sdk.language: webjs, or any browser.* attribute, makes browser records. Their host is the page's, from url.full, and they group like reports from the browser endpoint.
Older attribute names
code.filepath, code.lineno, code.column, http.target, http.url, http.method, http.client_ip, http.user_agent and deployment.environment are read where the current name is absent, and so is a type attribute (http, cli, js, node, 404, security).
Compression and the unmapped rest
gzip or no compression works everywhere; zstd works where the instance has PHP's zstd extension, and any other encoding answers 415. Unmapped record attributes land in extra beside span_id, scope and severity; unmapped resource attributes land under extra.resource.