Skip to main content
Superlog is built on OpenTelemetry (OTel). It accepts all three OTel signal types — traces, logs, and metrics — over the standard OTLP HTTP protocol. If your services are already instrumented with an OpenTelemetry SDK or agent, you can point them at Superlog without changing your instrumentation code.

​
Ingest endpoints

Send your telemetry to the following OTLP HTTP endpoints. All endpoints accept both application/x-protobuf and application/json content types. The AWS Firehose endpoints accept CloudWatch Metric Streams (OTLP format) and CloudWatch Logs subscription filters respectively. They authenticate using the X-Amz-Firehose-Access-Key header rather than the standard Authorization header.

​
Authentication

All OTLP ingest requests require your project’s ingest API key (sl_public_ prefix). Pass it as a Bearer token in the Authorization header:
You can also pass the key in the x-api-key header if your SDK or collector does not support Bearer auth.
Never use a management key (sl_management_) for OTLP ingest. Management keys are for the REST API only; sending them to the ingest endpoint will return a 401 error.

​
Resource attributes

Superlog uses standard OTel resource attributes to organize your data across the dashboard, filters, and incident grouping. Set these attributes in your SDK’s Resource configuration:
Always set service.name. Without it, Superlog cannot group your telemetry by service and the incident grouping and service map features will be less accurate.

​
Traces

Superlog stores distributed traces as collections of spans. Each span includes its attributes, events, links, status, and timing. You can explore traces in the Explore → Traces view or retrieve a specific trace by ID via the management API.

​
Span status and incident grouping

Superlog triggers incident grouping when a span’s status code is STATUS_CODE_ERROR. A few key points about when this is set:
  • HTTP 5xx responses should set STATUS_CODE_ERROR on the server span, per OTel HTTP semantic conventions.
  • HTTP 4xx responses (client errors) should remain STATUS_CODE_UNSET — they are not automatically promoted to errors. Only set STATUS_CODE_ERROR for 4xx responses that represent genuine server-side failures in your application logic.
  • Exception events on a span do not automatically set the span status to error — your instrumentation must call span.setStatus({ code: ERROR }) explicitly, or use an SDK that does this automatically (many do for unhandled exceptions).
This behavior follows the OTel HTTP semantic conventions. It means 404 errors from clients will not create incidents, which is usually what you want — an absent resource is a client problem, not a server problem.

​
Logs

Superlog stores log records with their severity, body, attributes, trace context (trace_id, span_id), and resource attributes. Logs at ERROR severity trigger incident grouping alongside error spans. You can explore logs in the Explore → Logs view, filter by service, severity, or free text, and correlate them with traces when trace_id is present.

​
Metrics

Superlog supports all four OTel metric instrument types: Metrics are queryable in the Explore → Metrics view and can be used as the basis for dashboard panels and alerts.

​
Querying your data

Once your telemetry is flowing, you can access it from several places:

Explore view

Interactive query interface for traces, logs, and metrics. Filter by service, time range, severity, attributes, and more.

Dashboards

Build panels from metrics and log queries. Share dashboards with your team or embed them in runbooks.

Alerts

Define threshold and anomaly alerts on metrics or log patterns. Route notifications to Slack or PagerDuty.

MCP server

Query traces and logs programmatically from your AI assistant using query_traces and query_logs MCP tools. The agent uses these same tools during incident investigations.
  • OTLP Ingest API — full reference for ingest endpoints, request formats, and response codes
  • Ingest Keys — create and manage the API keys used to authenticate OTLP requests