DOCUMENTATION

OpenTelemetry

Already instrumented? Point a collector at codesafe and skip the client entirely.

Already instrumented? Then you do not need a codesafe client at all. Point a collector's logs pipeline at codesafe and its log records become codesafe events — errors by default, 404 probes or security events when a record says so — grouped, prioritised, alerted and browsable like everything else.

Before you start

You need the project's api_key and a running OpenTelemetry Collector (or an SDK that can export OTLP/HTTP directly).

The api_key is a secret: export from a server or a collector, never from a web page. A page reports through the Browser client.

1. Decide whether this is the right door

  • Use OTLP if you already run a collector, or your language has an OTel SDK and no codesafe client.
  • Use a codesafe client if you want batching at shutdown, redaction and automatic context without configuring a pipeline.
  • Both at once is fine. They land in the same queue.

2. Know what the endpoint accepts

logsPOST /api/v1/ingest/otel (or …/otel/v1/logs)
metricsPOST /api/v1/ingest/otel/v1/metrics — one rollup counter
authX-Codesafe-Key: <api_key>
encodingJSON only — protobuf answers 415
compressiongzip or none; zstd where the server has the PHP zstd extension; anything else answers 415
limits200 records a request, 1 MiB on the wire, 8 MiB inflated
traces…/otel/v1/traces answers 404 — export them to a tracing backend instead

The bare URL is the logs door. Traces or metrics sent there find no log records: the answer is 200 {} and nothing is stored.

Why logs and not traces? codesafe is a place where a person decides what to fix. Traces are for a system that decides what is slow. Sending spans here would fill the grid with things nobody can act on.

3. Configure the exporter

Collector

receivers:
  otlp:
    protocols:
      http:                             # your services export here, port 4318

exporters:
  otlphttp/codesafe:
    logs_endpoint: https://yourcodesafe.cloud/api/v1/ingest/otel
    encoding: json                      # protobuf is refused with 415
    headers:
      X-Codesafe-Key: ${env:CODESAFE_KEY}

processors:
  filter/errors:                        # send what a person should see
    logs:
      log_record:
        - 'severity_number < SEVERITY_NUMBER_WARN'
  batch:
    send_batch_size: 200
    send_batch_max_size: 200            # codesafe takes 200 records a request
    timeout: 5s

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [filter/errors, batch]
      exporters: [otlphttp/codesafe]

SDK direct

Point the SDK's OTLP/HTTP log exporter at the endpoint:

	OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://yourcodesafe.cloud/api/v1/ingest/otel
	OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json
	OTEL_EXPORTER_OTLP_LOGS_HEADERS=X-Codesafe-Key=<api_key>

Not every SDK exports http/json: the JavaScript ones do. Where yours
exports only protobuf or gRPC, put a collector in between.

A collector in between is still worth it: it batches, filters and survives
your app restarting.

Docker Compose

# The collector listens on localhost by default, which a published port
# cannot reach. In otel-config.yaml, give the receiver every interface:
#   receivers: { otlp: { protocols: { http: { endpoint: 0.0.0.0:4318 } } } }
services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    environment:
      CODESAFE_KEY: ${CODESAFE_KEY}
    volumes:
      - ./otel-config.yaml:/etc/otel/config.yaml:ro
    ports:
      - "4318:4318"

4. Know what maps to what

OTLPcodesafe
severityNumber / severityTextpriority — FATAL→2, ERROR→3, WARN→4, INFO→6, DEBUG/TRACE→7; none → 3
bodymessage (structured bodies are kept as JSON)
exception.type / .message / .stacktraceclass, message, backtrace
code.file.path / code.line.numberfile and line — the file feeds the fingerprint, except on browser records; the line never does
service.name / service.versionhost (the "application" column) and release
deployment.environment.nameenvironment
resource telemetry.sdk.languageruntime — webjs makes a browser record
record kind / entry / runtimecodesafe's own axes — kind: not_found is a 404 probe, kind: security a security event named in event.name
resource and record tagstags
url.* / http.* / client.address / user_agent.originalrequest context: uri, method, ip, ua
http.request.body.content / http.request.header.*the request a replay re-issues
session.id / user.id / enduser.idsession and user columns
traceIdtrace id — one request's errors across every service
extra.*extra, the prefix dropped
everything unmappedextra — span id, scope, severity, resource attributes

5. Avoid what trips people up

  • Protobuf is refused. Set encoding: json on the exporter or every export answers 415.
  • Filter before exporting. A project stores every priority until you lower its accept priority (PROJECTS → DATA), so without the filter processor every INFO and DEBUG line your services emit is stored.
  • Mind the filter if you send 404 probes or security events. Both usually ride at INFO, and severity_number < SEVERITY_NUMBER_WARN drops them. Exempt them: severity_number < SEVERITY_NUMBER_WARN and attributes["kind"] == nil.
  • Stamp the language on file-tailed logs. An SDK sets telemetry.sdk.language on its resource; a collector tailing log files does not, and codesafe cannot name the runtime. Upsert it in the resource processor (php, nodejs, python, …).
  • Metrics are one counter. A monotonic DELTA sum named codesafe.rollup.requests, sent to …/otel/v1/metrics and gated per project. Everything else in a metrics export is reported back through partialSuccess and never stored.

6. Check it worked

Send one WARN-level record and watch EVENTS.

answermeaning
200 {}accepted
200 with partialSuccesssome records dropped at the door: over 200 in one request, with no body, exception or code location, below the project's accept priority, a 404 probe or security event the project does not take, or (browser records) thrown by an injected or third-party script. Ignore rules run after the answer and are not counted
400malformed JSON, or a body that does not decode or inflates past 8 MiB
401the X-Codesafe-Key is missing or names no active project
403metrics, on a project without rollups enabled
404a signal other than logs or metrics, such as traces at …/otel/v1/traces
413the body is over 1 MiB on the wire
415protobuf, or a compression codesafe does not decode
429the key is past its project's budget — the exporter waits out Retry-After and retries
503codesafe is full or its store is down — the exporter retries, after Retry-After when one is sent

Next: the wire-level detail is in OpenTelemetry endpoint; the rules a client follows are in Build your own client.