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
| logs | POST /api/v1/ingest/otel (or …/otel/v1/logs) |
| metrics | POST /api/v1/ingest/otel/v1/metrics — one rollup counter |
| auth | X-Codesafe-Key: <api_key> |
| encoding | JSON only — protobuf answers 415 |
| compression | gzip or none; zstd where the server has the PHP zstd extension; anything else answers 415 |
| limits | 200 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
| OTLP | codesafe |
|---|---|
severityNumber / severityText | priority — FATAL→2, ERROR→3, WARN→4, INFO→6, DEBUG/TRACE→7; none → 3 |
body | message (structured bodies are kept as JSON) |
exception.type / .message / .stacktrace | class, message, backtrace |
code.file.path / code.line.number | file and line — the file feeds the fingerprint, except on browser records; the line never does |
service.name / service.version | host (the "application" column) and release |
deployment.environment.name | environment |
resource telemetry.sdk.language | runtime — webjs makes a browser record |
record kind / entry / runtime | codesafe's own axes — kind: not_found is a 404 probe, kind: security a security event named in event.name |
resource and record tags | tags |
url.* / http.* / client.address / user_agent.original | request context: uri, method, ip, ua |
http.request.body.content / http.request.header.* | the request a replay re-issues |
session.id / user.id / enduser.id | session and user columns |
traceId | trace id — one request's errors across every service |
extra.* | extra, the prefix dropped |
| everything unmapped | extra — span id, scope, severity, resource attributes |
5. Avoid what trips people up
- Protobuf is refused. Set
encoding: jsonon the exporter or every export answers415. - 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_WARNdrops them. Exempt them:severity_number < SEVERITY_NUMBER_WARN and attributes["kind"] == nil. - Stamp the language on file-tailed logs. An SDK sets
telemetry.sdk.languageon its resource; a collector tailing log files does not, and codesafe cannot name the runtime. Upsert it in theresourceprocessor (php,nodejs,python, …). - Metrics are one counter. A monotonic DELTA sum named
codesafe.rollup.requests, sent to…/otel/v1/metricsand gated per project. Everything else in a metrics export is reported back throughpartialSuccessand never stored.
6. Check it worked
Send one WARN-level record and watch EVENTS.
| answer | meaning |
|---|---|
200 {} | accepted |
200 with partialSuccess | some 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 |
400 | malformed JSON, or a body that does not decode or inflates past 8 MiB |
401 | the X-Codesafe-Key is missing or names no active project |
403 | metrics, on a project without rollups enabled |
404 | a signal other than logs or metrics, such as traces at …/otel/v1/traces |
413 | the body is over 1 MiB on the wire |
415 | protobuf, or a compression codesafe does not decode |
429 | the key is past its project's budget — the exporter waits out Retry-After and retries |
503 | codesafe 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.