Reference

LogDB OTLP And Query Reference

Source-backed reference for LogDB OTLP HTTP/protobuf, OTLP JSON compatibility, optional OTLP/gRPC, custom endpoint JSON helpers, tenant admission, and POST /v1/query.

Current availability

Private Beta. Public beta is scheduled for December 14, 2026.

LiveConfirm First

Readiness Notes

Implemented Route Surface

Live

The routes and services below are sourced from the current LogDB README, route modules, handlers, tenant admission code, and query API implementation.

Product Boundary

Confirm First

Use this reference for the implemented local route surface. Treat security, operations, and external-commitment language as Confirm First unless the related limits and compatibility pages state the supported scope.

Reference Summary

ID	Type	Name	Method	Path or service	Maturity	Source scope
`ldb-endpoint-json-ingest`	api	Custom endpoint JSON ingest Stores one JSON telemetry payload as a canonical envelope and returns its deterministic record ID.	`POST`	`/v1/endpoint/{activation_id}`	Live	documented source scope, documented source scope, endpoint_handler.rs
`ldb-endpoint-json-readback`	api	Custom endpoint readback Reads the latest envelope, up to 100 recent envelopes, or one envelope by deterministic record ID.	`GET`	`/v1/endpoint/{activation_id}/recent, /recent_100, /{record_id}`	Live	documented source scope, documented source scope, endpoint_handler.rs
`ldb-otlp-http-protobuf-logs`	api	Native OTLP HTTP/protobuf logs Accepts ExportLogsServiceRequest protobuf batches through tenant admission and WAL-backed publication.	`POST`	`/v1/logs`	Live	documented source scope, documented source scope, otlp_http_handler.rs
`ldb-otlp-http-protobuf-traces`	api	Native OTLP HTTP/protobuf traces Accepts ExportTraceServiceRequest protobuf batches through the same commit path as logs.	`POST`	`/v1/traces`	Live	documented source scope, documented source scope, otlp_http_handler.rs
`ldb-otlp-json-compat`	api	OTLP HTTP JSON compatibility Accepts OpenTelemetry-shaped JSON logs and traces and returns accepted record IDs.	`POST`	`/v1/otlp/logs, /v1/otlp/traces`	Live	documented source scope, documented source scope, otlp_http.rs
`ldb-otlp-grpc`	api	Optional OTLP/gRPC Enables generated OpenTelemetry LogsService and TraceService export methods when the gRPC bind address is configured.	`Export`	`LogsService, TraceService`	Live	documented source scope, documented source scope, otlp_grpc_handler.rs
`ldb-query-v1`	api	Query retained records Searches published local or configured S3 segment bundles by dataset, exact IDs, time filters, pagination, and deadline controls.	`POST`	`/v1/query`	Live	documented source scope, documented source scope, query_handler.rs
`ldb-tenant-admission`	auth	Tenant admission Requires tenant and bearer credentials for OTLP and query routes, and checks OTLP resource tenant claims against the authenticated tenant.	`mixed`	`OTLP and query routes`	Confirm First	documented source scope, tenant_admission.rs
`ldb-ingest-query-limits`	limit	Ingest and query limits Documents the current 512-record OTLP batch cap, gateway backpressure defaults, tenant quota defaults, and query page caps.	`n/a`	`batch, gateway, tenant, page, and store limits`	Confirm First	documented source scope, documented source scope, backpressure.rs

Headers And Tenant Admission

Surface	Content type	Credentials	Tenant claim
Custom endpoint JSON helpers	content-type: application/json for POST bodies	No tenant header is read by the endpoint helper routes.	The helper writes canonical envelopes for the activation ID and local tenant path.
OTLP HTTP/protobuf	content-type: application/x-protobuf; content-encoding may be omitted, identity, or gzip	x-logdb-tenant: local and authorization: Bearer local-dev-token in local development.	The batch must contain exactly one claimed tenant and it must match the authenticated tenant.
OTLP HTTP JSON compatibility	content-type: application/json	x-logdb-tenant: local and authorization: Bearer local-dev-token in local development.	Resource attributes service.logdb.tenant_id or tenant_id must match the header.
OTLP/gRPC	Generated OpenTelemetry protobuf request messages; gzip request and response compression are enabled.	x-logdb-tenant and authorization metadata use the same local-development values as HTTP.	Prepared protobuf records flow through the same tenant-admission check as HTTP/protobuf.
Query	content-type: application/json	x-logdb-tenant: local and authorization: Bearer local-dev-token in local development.	The query dataset is authorized against the authenticated tenant credential.

Custom Endpoint Routes

Custom endpoint JSON helper routes
Route	Request	Response	Errors	Source scope
`POST /v1/endpoint/{activation_id}`	JSON payload for one activation ID.	200 OK JSON with status "stored" and record_id.	400 or 503 rejected JSON when the durable ingest path rejects or cannot publish the record.	endpoint_handler.rs
`GET /v1/endpoint/{activation_id}/recent`	Activation ID path segment; no body.	200 OK canonical telemetry envelope for the latest record.	404 No data found; 500 when segment readback fails.	endpoint_handler.rs
`GET /v1/endpoint/{activation_id}/recent_100`	Activation ID path segment; no body.	200 OK array with up to 100 canonical telemetry envelopes.	404 No data found; 500 when segment readback fails.	endpoint_handler.rs
`GET /v1/endpoint/{activation_id}/{record_id}`	Activation ID and deterministic record ID path segments.	200 OK canonical telemetry envelope.	404 No data found; 500 when segment readback fails.	endpoint_handler.rs

OTLP Routes And Services

OTLP ingest routes and services
Route	Request	Response	Errors	Source scope
`POST /v1/logs`	ExportLogsServiceRequest protobuf body with application/x-protobuf and local tenant headers.	200 OK application/x-protobuf ExportLogsServiceResponse with no partial_success.	415 unsupported content type or encoding; 400 malformed protobuf; 401/403 tenant admission; 429 batch, quota, or gateway pressure; 503 retryable publication failure.	otlp_http_handler.rs
`POST /v1/traces`	ExportTraceServiceRequest protobuf body with application/x-protobuf and local tenant headers.	200 OK application/x-protobuf ExportTraceServiceResponse with no partial_success.	Same protobuf status-body behavior as POST /v1/logs.	otlp_http_handler.rs
`POST /v1/otlp/logs`	OpenTelemetry-style JSON body with resourceLogs, scopeLogs, and logRecords.	202 Accepted JSON with status "accepted", signal "log", accepted_records, and record_ids.	400 malformed JSON compatibility shape; 401/403 tenant admission; 429 batch, quota, or gateway pressure; 503 retryable publication failure.	otlp_http_handler.rs, otlp_http.rs
`POST /v1/otlp/traces`	OpenTelemetry-style JSON body with resourceSpans, scopeSpans, and spans.	202 Accepted JSON with status "accepted", signal "trace", accepted_records, and record_ids.	Same JSON rejected-body behavior as POST /v1/otlp/logs.	otlp_http_handler.rs, otlp_http.rs
`LogsService.Export and TraceService.Export`	OTLP/gRPC ExportLogsServiceRequest or ExportTraceServiceRequest; listener starts only when LOGDB_OTLP_GRPC_BIND_ADDRESS is set.	Generated ExportLogsServiceResponse or ExportTraceServiceResponse; gzip compression is accepted and sent by the service builders.	invalid_argument, unauthenticated, permission_denied, resource_exhausted, unavailable, or internal gRPC status codes.	otlp_grpc_handler.rs

Query Route

Query route
Route	Request	Response	Errors	Source scope
`POST /v1/query`	JSON body with required dataset plus optional filter, page, and deadline_ms.	200 OK JSON with status, api_version, tenant_id, dataset, results, page, scanned_bundles, matched_records, and used_indexes.	400 request/filter/page errors; 401 authentication; 403 dataset_not_authorized; 408 deadline_exceeded; 500 segment scan, exact-index, record-read, or DataFusion failures.	http-query-api.md, query_handler.rs, query/api.rs

Query request parameters

The route accepts one JSON body. Omitting the optional filter or page object uses its empty default; sending JSON null for either object is malformed. Optional leaf fields accept JSON null as omission unless noted otherwise.

LogDB query request parameters
Field	Location	Type	Requirement	Default or omission	Accepted values and constraints
`dataset`	JSON body	string	Required; JSON null and non-string values are malformed	No default. Omission reaches authorization as an empty value and is rejected.	Trimmed value must be non-empty and authorized for the authenticated tenant.
`filter`	JSON body	object	Optional; JSON null is malformed	Empty filter object; only tenant and dataset constrain the scan	Recognized fields are listed below. All supplied filters combine with AND.
`filter.record_id`	JSON body	string	Optional; JSON null is treated as omitted	No record-ID filter	Trimmed value must be non-empty and matches exactly. A used index is reported as "record_id".
`filter.trace_id`	JSON body	string	Optional; JSON null is treated as omitted	No trace-ID filter	Trimmed value must be non-empty and matches exactly. A used index is reported as "identity.trace_id".
`filter.source_time`	JSON body	object	Optional; JSON null is treated as omitted	No source-time filter	Include start or end. Bounds compare with the stored source_timestamp string; records without a source timestamp do not match a supplied source-time filter.
`filter.source_time.start`	JSON body	string	Optional; JSON null is treated as omitted	No lower source-time bound	Non-empty after trimming and inclusive. Use the same serialized form as stored source timestamps; OTLP examples use decimal Unix nanoseconds. Must be less than or equal to end when both are present.
`filter.source_time.end`	JSON body	string	Optional; JSON null is treated as omitted	No upper source-time bound	Non-empty after trimming and inclusive. Use the same serialized form as stored source timestamps; OTLP examples use decimal Unix nanoseconds. Must be greater than or equal to start when both are present.
`filter.ingested_time`	JSON body	object	Optional; JSON null is treated as omitted	No ingest-time filter	Include start or end. Bounds compare with the canonical ingested_at string; use consistently normalized RFC 3339 values, preferably UTC.
`filter.ingested_time.start`	JSON body	string	Optional; JSON null is treated as omitted	No lower ingest-time bound	Non-empty after trimming and inclusive. Must be less than or equal to end when both are present.
`filter.ingested_time.end`	JSON body	string	Optional; JSON null is treated as omitted	No upper ingest-time bound	Non-empty after trimming and inclusive. Must be greater than or equal to start when both are present.
`page`	JSON body	object	Optional; JSON null is malformed	Empty page object: limit 100 and offset 0	Recognized fields are limit and cursor.
`page.limit`	JSON body	positive integer	Optional; JSON null is treated as omitted	100 records	From 1 through 500 records.
`page.cursor`	JSON body	string	Optional; JSON null is treated as omitted	Offset 0; an empty or whitespace-only string also selects 0	A nonnegative decimal integer offset, normally the previous response's next_cursor. An offset beyond the current match count returns an empty final page.
`deadline_ms`	JSON body	unsigned integer milliseconds	Optional; JSON null is treated as omitted	No service deadline	0 returns 408 deadline_exceeded immediately. A positive value is checked before, between, and after query phases; no separate maximum is defined below the unsigned 64-bit JSON model.

Query response and behavior contract

LogDB query response and behavior contract
Operation	Access	Success response	Completion and side effects	Filtering and ordering	Pagination and consistency	Retry and idempotency
`POST /v1/query`	application/json plus x-logdb-tenant and a Bearer credential authorized to query the requested dataset. Local development uses tenant local and token local-dev-token.	200 OK, application/json. The body contains status, api_version, tenant_id, dataset, results, page, scanned_bundles, matched_records, and used_indexes. Each result contains the complete canonical record and its bundle_id.	A 200 response means the bounded read completed against the currently configured local or S3 query store. Query is read-only: it does not commit a cursor, reserve a snapshot, or change retained records. matched_records is counted before pagination; scanned_bundles reflects candidates after exact-index filtering.	All supplied filters combine with AND. Exact record and trace IDs use sidecar candidates when present. Time bounds are inclusive string comparisons. Results are deduplicated by record_id and ordered by ingested_at and then record_id.	The default limit is 100 and the maximum is 500. Send page.next_cursor as the next request's page.cursor until next_cursor is null. The cursor is an offset into a freshly evaluated match set, not a snapshot; concurrent ingest can shift records between requests.	The read is non-mutating and can be retried, but a retry can observe newer retained data. deadline_exceeded reports retryable:true; narrow the filters or use an appropriate positive deadline. Request, authorization, and internal read errors report retryable:false and require correction or investigation before retrying. Omitting deadline_ms applies no service deadline.

Query error contract

LogDB query error contract
Status	Error kinds	Trigger	Retryable	Recovery
`400 Bad Request`	malformed_query, invalid_request, invalid_filter, invalid_time_bounds, invalid_limit, invalid_cursor	Wrong JSON types or non-nullable objects, missing or blank dataset, blank filter text, reversed bounds, a limit outside 1–500, or a cursor that is not a nonnegative integer string.	`false`	Correct the request body before retrying.
`401 Unauthorized`	missing_tenant, missing_credentials, unknown_tenant, invalid_credentials	The tenant header or bearer credential is missing, or the local admission policy cannot authenticate it.	`false`	Supply credentials for the intended environment. Local development uses x-logdb-tenant: local and authorization: Bearer local-dev-token.
`403 Forbidden`	dataset_not_authorized	The authenticated credential cannot execute a query for the requested dataset.	`false`	Use an authorized dataset or a credential with the required dataset-scoped query permission.
`408 Request Timeout`	deadline_exceeded	deadline_ms is 0 or the positive deadline expires at a query phase check.	`true`	Narrow the filters or retry the read with an appropriate positive deadline. A retry can observe newer data.
`500 Internal Server Error`	segment_scan, record_id_index, identity_index, segment_read, datafusion_scan	The configured store, manifest scan, exact index lookup, segment read, or DataFusion row scan failed.	`false`	Inspect the local segment root or S3 query-read configuration, file or object permissions, and service logs before retrying.

JSON Compatibility Example

curl -X POST http://127.0.0.1:4318/v1/otlp/logs   -H 'content-type: application/json'   -H 'x-logdb-tenant: local'   -H 'authorization: Bearer local-dev-token'   -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          {"key": "tenant_id", "value": {"stringValue": "local"}},
          {"key": "service.name", "value": {"stringValue": "checkout"}}
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "1783947600000000000",
          "body": {"stringValue": "payment accepted"}
        }]
      }]
    }]
  }'

{
  "status": "accepted",
  "signal": "log",
  "accepted_records": 1,
  "record_ids": ["logdb_..."]
}

Query Example

curl -X POST http://127.0.0.1:4318/v1/query   -H 'content-type: application/json'   -H 'x-logdb-tenant: local'   -H 'authorization: Bearer local-dev-token'   -d '{
    "dataset": "checkout",
    "filter": {
      "record_id": "logdb_..."
    },
    "page": {
      "limit": 10
    }
  }'

{
  "status": "ok",
  "api_version": "v1",
  "tenant_id": "local",
  "dataset": "checkout",
  "results": [{
    "record": {
      "schema_version": 1,
      "record_id": "logdb_...",
      "tenant_id": "local",
      "dataset": "checkout",
      "source": "v1.otlp_http",
      "signal": "log",
      "source_timestamp": "1783947600000000000",
      "ingested_at": "2026-07-13T15:00:00+00:00",
      "raw_payload": {}
    },
    "segment": {
      "bundle_id": "live_otlp-http_..."
    }
  }],
  "page": {
    "limit": 10,
    "cursor": null,
    "next_cursor": null
  },
  "scanned_bundles": 1,
  "matched_records": 1,
  "used_indexes": ["record_id"]
}

Limits

Limit	Value	Applies to
OTLP batch size	512 records	HTTP/protobuf logs, HTTP/protobuf traces, JSON compatibility logs and traces, and gRPC exports.
OTLP gateway in-flight requests	64 by default	Shared HTTP and gRPC ingest backpressure.
OTLP gateway in-flight records	8192 by default	Shared HTTP and gRPC ingest backpressure.
OTLP gateway in-flight bytes	33554432 by default	Shared HTTP and gRPC ingest backpressure.
Tenant admission window	10000 records, 16 MiB, 16 concurrent requests per 60 seconds by default	Local development tenant policy and policy-derived ingest checks.
Query page size	Default 100, maximum 500	POST /v1/query.
Endpoint recent readback	100 records	GET /v1/endpoint/{activation_id}/recent_100.
Query store selection	Local segment store by default; S3 query-read is separately configured	POST /v1/query read path only. It does not make ingest publish to S3.

Errors

Status	Surface	Meaning	Recovery
`400`	JSON compatibility and query	Malformed OTLP JSON, empty batches, invalid query bodies, empty datasets, or route-specific validation failed.	Fix the request shape, dataset, filter, or body fields.
`401`	OTLP and query	Tenant header, bearer token, tenant policy, or credential validation failed.	For local development, send x-logdb-tenant: local and authorization: Bearer local-dev-token.
`403`	OTLP and query	The authenticated tenant does not match OTLP tenant claims or is not authorized for the dataset.	Align service.logdb.tenant_id or tenant_id resource attributes with the header and dataset policy.
`408`	Query	deadline_ms expired before query execution completed.	Use a nonzero deadline or narrow the query filters.
`415`	HTTP/protobuf	content-type is not application/x-protobuf or content-encoding is not identity or gzip.	Post generated OTLP protobuf bytes with the expected content headers.
`429`	OTLP ingest	Batch size, tenant quota, or shared gateway in-flight capacity is exhausted.	Reduce batch size or request concurrency and honor Retry-After when present.
`500`	Query	Segment scan, exact index lookup, or segment record read failed.	Check segment publication root, local file permissions, S3 query-read configuration, and service logs.
`503`	OTLP ingest	Retryable durable publication failure after admission.	Inspect WAL and segment publication health before retrying.

Native HTTP/protobuf errors use application/x-protobuf bodies encoded as google.rpc.Status. JSON compatibility and query errors use JSON bodies with status: rejected, retryable, and error.kind.

Boundaries

S3 Query Read

POST /v1/query can be configured to read segment bundles from S3, but ingest still writes locally unless separately documented and reviewed.

Signal Scope

This page covers logs, traces, endpoint JSON helpers, and retained segment search. Metrics, profiles, dashboarding, SIEM replacement, and public replay routes remain outside this reference.

Safe Next Steps

Available now
Run OTLP ingest and query quickstart
Exercise JSON compatibility ingest, exact record ID query, trace pagination, tenant headers, and cleanup.
Available now
Review LogDB limits
Use the limits and compatibility guidance before strengthening ingest, query, S3, replay, BYOC, support, or GA claims.
Available
Review configuration and BYOC reference
Separate local bind/data settings, WAL durability settings, S3 query-read settings, gRPC bind configuration, and AWS BYOC values.
Available
Compare OTLP and S3 query scope
Distinguish live ingest, optional gRPC, local query, S3 query reads, metrics/profile exclusions, and future publication work.