Skip to content
DocumentationReference
Reference
OpenTelemetry API

OpenTelemetry API

Send OTLP/HTTP logs, traces, and metrics with an OpenTelemetry SDK, collector, or HTTP client. Altertable writes accepted telemetry to the environment's opentelemetry catalog.

For setup and verification, follow Configure an exporter. The deployed OpenAPI contract lists the operations; the OTLP specification defines the signal payloads.

Authentication

Use HTTP Basic Auth with lakehouse credentials from the target environment. Every request requires Authorization: Basic <BASE64_USERNAME_COLON_PASSWORD>. With curl, pass --user "$ALTERTABLE_USERNAME:$ALTERTABLE_PASSWORD" to construct the header.

Set these variables with the same environment’s lakehouse credentials before running the request examples:

Terminal
ALTERTABLE_USERNAME='YOUR_LAKEHOUSE_USERNAME'
ALTERTABLE_PASSWORD='YOUR_LAKEHOUSE_PASSWORD'

Encoding and responses

  • Set Content-Type to application/x-protobuf for binary protobuf or application/json for OTLP JSON.
  • For compressed requests, gzip the body and send Content-Encoding: gzip.
  • The response uses the request's encoding and the corresponding OTLP Export*ServiceResponse message. A successful JSON response is currently {}.
  • Compatibility aliases /otel/v1/logs, /otel/v1/traces, and /otel/v1/metrics use the same handlers. Prefer /v1/* for new integrations.
Status
Meaning
200
OTLP export accepted
400
Invalid protobuf, JSON, or gzip payload
401
Authentication required or credentials rejected
415
Unsupported Content-Type; use application/x-protobuf or application/json

POST /v1/logs

Export OpenTelemetry logs.
Authentication
HTTP Basic Auth
Permission
Write telemetry

Parameters

Content-Typeapplication/x-protobuf | application/json· header · Required
Encoding of the OTLP export request.
Content-Encodinggzip· header · Optional
Set when the body is gzip-compressed.
bodyExportLogsServiceRequest· body · Required
OTLP logs payload in protobuf or JSON encoding.

Query accepted logs in opentelemetry.main.logs. See Send logs for setup and verification.

The response is an ExportLogsServiceResponse, encoded as protobuf or JSON to match the request. The response statuses apply to this endpoint.

POST /v1/traces

Export OpenTelemetry traces.
Authentication
HTTP Basic Auth
Permission
Write telemetry

Parameters

Content-Typeapplication/x-protobuf | application/json· header · Required
Encoding of the OTLP export request.
Content-Encodinggzip· header · Optional
Set when the body is gzip-compressed.
bodyExportTraceServiceRequest· body · Required
OTLP traces payload in protobuf or JSON encoding.

Query accepted traces in opentelemetry.main.spans. See Send traces for setup and verification.

The response is an ExportTraceServiceResponse, encoded as protobuf or JSON to match the request. The response statuses apply to this endpoint.

POST /v1/metrics

Export OpenTelemetry metrics.
Authentication
HTTP Basic Auth
Permission
Write telemetry

Parameters

Content-Typeapplication/x-protobuf | application/json· header · Required
Encoding of the OTLP export request.
Content-Encodinggzip· header · Optional
Set when the body is gzip-compressed.
bodyExportMetricsServiceRequest· body · Required
OTLP metrics payload in protobuf or JSON encoding.

Query accepted metrics in opentelemetry.main.metrics. This view joins the underlying metric_points and metric_series tables. Gauge, sum, histogram, exponential histogram, and summary points are supported. See Send metrics for setup and verification.

The response is an ExportMetricsServiceResponse, encoded as protobuf or JSON to match the request. The response statuses apply to this endpoint.