OpenTelemetry
Vaka accepts OTLP/HTTP traces and logs from any OpenTelemetry SDK or the OpenTelemetry Collector, so backend services in Java, Go, Python, .NET, Node, Ruby or Rust need no Vaka SDK.
| What you send | Where it goes |
|---|---|
| Spans | Performance: transactions, slow endpoints, traces and release comparisons (performance.md) |
Span exception events |
Errors, grouped into issues, with the trace id and a parsed stack trace |
| Log records | The logs store (search with REST or the search_logs MCP tool), shown on their trace |
| ERROR and FATAL log records | Errors too (the log body is the message, or exception.* attributes when present) |
| Metrics | Accepted and dropped, so exporters with all signals on don't retry |
Endpoint and key
Use the project's ingest key as a header (X-Vaka-Key: vk_… or Authorization: Bearer vk_…).
export OTEL_EXPORTER_OTLP_ENDPOINT=https://vaka.example.com/ingest/otlp
export OTEL_EXPORTER_OTLP_HEADERS="x-vaka-key=$VAKA_INGEST_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf # or http/json
export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES="service.version=2.4.0,deployment.environment.name=production"
export OTEL_METRICS_EXPORTER=none
SDKs append /v1/traces and /v1/logs. The full URLs are https://vaka.example.com/ingest/otlp/v1/traces and
https://vaka.example.com/ingest/otlp/v1/logs. Both protobuf (application/x-protobuf) and JSON
(application/json) work, gzip too. gRPC is not supported; use the HTTP exporter.
OpenTelemetry Collector
exporters:
otlphttp/vaka:
endpoint: https://vaka.example.com/ingest/otlp
headers:
x-vaka-key: ${env:VAKA_INGEST_KEY}
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/vaka]
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/vaka]
Mapping
| OpenTelemetry | Vaka |
|---|---|
service.version |
release (so release health, comparisons and regressions work per version) |
deployment.environment.name (or deployment.environment) |
environment |
service.name |
service (span and log field, service tag on errors) |
telemetry.sdk.language |
platform |
| SERVER and CONSUMER spans | transactions, even with a remote parent |
http.request.method + http.route |
transaction name, such as GET /carts/{id} |
http.response.status_code |
HTTP status (5xx counts as an error) |
db.system, messaging.system, rpc.system |
span op db, queue.publish / queue.process, rpc.client / rpc.server |
status ERROR |
span status error |
enduser.id, session.id |
user id and session id |
exception.type, .message, .stacktrace |
exception type, value and frames (Java/Kotlin, JavaScript, Python, .NET, Go and Ruby stack formats; vendor frames are marked not in-app) |
exception.escaped: true |
unhandled |
Use the same trace context in the browser or app: the Vaka JavaScript SDK sends a W3C
traceparent header, so backend spans join the frontend trace.
Logs
curl "https://vaka.example.com/api/v1/projects/checkout/logs?since=1h&severity=warn&q=timeout" \
-H "Authorization: Bearer $VAKA_TOKEN"
Filters: q (text in the body, case-insensitive), severity (minimum: trace, debug, info, warn,
error, fatal), trace_id, service, release, environment, since, until, limit (default
100). The response has logs (newest first) and counts per severity. GET /projects/{p}/traces/{trace_id} includes the trace's logs. MCP: search_logs.
Logs follow the project's retention and are erased with the rest of a user's data when they carry
enduser.id.