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 November 2, 2026.

Maturity Status

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.

Review Boundary

Verification Required

Product, security, operations, and docs QA reviewers still need to accept the exact wording before this page supports external commitments.

Reference Summary

ID	Type	Name	Method	Path or service	Maturity	Evidence
`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	LDB-EVID-001, LDB-EVID-008, 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	LDB-EVID-001, LDB-EVID-008, 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	LDB-EVID-001, LDB-EVID-008, 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	LDB-EVID-001, LDB-EVID-008, 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	LDB-EVID-002, LDB-EVID-008, 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	LDB-EVID-001, LDB-EVID-008, 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	LDB-EVID-004, LDB-EVID-008, 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`	Verification Required	LDB-EVID-003, 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`	Verification Required	LDB-EVID-004, LDB-EVID-008, 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	Evidence
`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	Evidence
`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	Evidence
`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 malformed or invalid query; 401/403 authorization; 408 deadline_exceeded; 500 segment scan, index, or read failures.	http-query-api.md, query_handler.rs, query/api.rs

Query request fields
Field	Required	Behavior	Notes
`dataset`	Required	Limits the scan to one dataset for the authenticated tenant.	Empty dataset requests are rejected.
`filter.record_id`	Optional	Uses the exact record ID sidecar index when present.	Successful responses list used_indexes: ["record_id"].
`filter.trace_id`	Optional	Uses the exact identity sidecar index for trace IDs.	Successful responses list used_indexes: ["identity.trace_id"].
`filter.source_time`	Optional	Applies start and end bounds to source timestamps.	Timestamp strings are passed through the query scan filter.
`filter.ingested_time`	Optional	Applies start and end bounds to ingest timestamps.	Use RFC 3339 strings in examples and docs guidance.
`page.limit`	Optional	Defaults to 100 and caps at 500.	Invalid or oversized limits return a rejected query body.
`page.cursor`	Optional	Uses stable integer offsets returned as next_cursor.	Pass the previous next_cursor string to read the next page.
`deadline_ms`	Optional	A zero deadline fails immediately with deadline_exceeded.	Nonzero deadlines are checked during scan and index work.

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 evidence
Use the evidence index before strengthening ingest, query, S3, replay, BYOC, support, or GA claims.
Available: DOCS-034
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: DOCS-039
Compare OTLP and S3 query scope
Distinguish live ingest, optional gRPC, local query, S3 query reads, metrics/profile exclusions, and future publication work.