DOCUMENTATION

OpenTelemetry endpoint

OTLP/HTTP logs and metrics, straight from a collector.

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.json

JSON

{
  "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

FieldTypeRequiredLimitWhat it does
bodyrecord fieldone name≤ 2,048 charsThe message; a structured body is kept as JSON
severityNumberrecord fieldno1–24Priority: FATAL 2, ERROR 3, WARN 4, INFO 6, DEBUG and TRACE 7
severityTextrecord fieldnoRead when no number is sent; neither gives 3
timeUnixNanorecord fieldnonanosecondsWhen it happened; else observedTimeUnixNano
traceIdrecord fieldno≤ 64 charsThe trace id: links one request across services
exception.typeattributeone name≤ 256 charsThe class; a browser record without one is Error
exception.messageattributeone name≤ 2,048 charsThe exception's message, and the message when body is empty
exception.stacktraceattributeno≤ 8,192 charsThe backtrace
code.file.pathattributeone name≤ 512 charsThe file; part of the grouping except on browser records
code.line.number, code.column.numberattributenoThe line, and the column as extra.col
kind, entry, runtimeattributenothe closed listscodesafe's axes; error, web and the SDK's language when absent
event.nameattributenoa security nameA security record's name when exception.type is absent
url.path, url.query, url.fullattributeno≤ 2,048 charsThe request's uri
http.request.method, user_agent.originalattributenoThe method and the user agent
client.addressattributenoan IP addressThe visitor's address
http.request.header.<name>, http.request.body.contentattributenoThe request a replay re-issues; referer is the referring page
session.id, user.idattributenoThe session and the user; enduser.id when user.id is absent
tagsattribute, resourceno≤ 10 tagsA string array or one string; the record's and the resource's are joined
extra.<key>attributenoLands in extra as <key>
service.nameresourceno≤ 255 charsThe host, the EVENTS grid's application column; else host.name
service.versionresourceno≤ 64 charsThe release
deployment.environment.nameresourceno≤ 64 charsThe environment
telemetry.sdk.languageresourcenoThe runtime; webjs makes a browser record, nodejs is node
process.command_argsresourcenoThe 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.

RuleWhat codesafe takes
Namecodesafe.rollup.requests
Shapea Sum with isMonotonic: true and DELTA temporality
ValueasInt, 0–100,000,000
TimetimeUnixNano within 90 minutes of codesafe's clock
Attributesroute, status, method, authed as string values, from the rollup vocabulary
Resourceservice.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

StatusWhenWhat the client does
200{}: every record or data point takenNothing
200{"partialSuccess": {"rejectedLogRecords": 2, "errorMessage": "…"}}; metrics say rejectedDataPointsRead the message; never resend
400Malformed JSON, or a body that does not decode or inflates past 8 MiBFix the exporter
401X-Codesafe-Key is missing, or no active project holds itFix the key
403Metrics, for a project that takes no rollupsSwitch rollups on, or stop exporting
404A signal other than logs or metrics, such as /v1/tracesExport it elsewhere
405The method is not POSTFix the exporter
413Over 1 MiB on the wireSend smaller batches
415Protobuf, or a Content-Encoding codesafe does not decodeSet encoding: json, and gzip or no compression
429The project's budget is spent; Retry-After: 60The exporter retries after it
503codesafe cannot store it at the moment; mostly Retry-After: 30The 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: json on the otlphttp exporter: protobuf answers 415.
  • The exporter's plain endpoint: appends /v1/logs, /v1/metrics and /v1/traces itself; traces answer 404, and the exporter drops them.
  • A request takes 200 log records; set the batch processor's send_batch_max_size to 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.