OpenTelemetry Collector

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

The OpenTelemetry Collector is the preferred ingest gateway. Applications send standard OTLP to the Collector; the Collector batches, retries, enriches, and exports it to PulsusDB.

OTLP endpoints

PulsusDB accepts protobuf OTLP/HTTP requests on its HTTP listener:

Signal	Endpoint
Logs	POST /v1/logs
Metrics	POST /v1/metrics
Traces	POST /v1/traces
Profiles	POST /v1development/profiles

Prometheus remote write is also available at POST /api/v1/write.

Collector configuration

otel-collector.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  batch:
    send_batch_size: 4096
    timeout: 1s

exporters:
  otlphttp/pulsusdb:
    endpoint: http://pulsusdb:3100
    compression: gzip
    retry_on_failure:
      enabled: true

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/pulsusdb]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/pulsusdb]
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/pulsusdb]

The otlphttp exporter appends the signal-specific path to endpoint, so specify the PulsusDB base URL without /v1/logs or another signal path.

Authentication and TLS

When PulsusDB Basic authentication is enabled, configure an authenticator extension supported by your Collector distribution and attach it to the exporter.

For TLS, use an https:// exporter endpoint. PulsusDB’s listener is TLS-only when both PULSUS_TLS_CERT and PULSUS_TLS_KEY are set; exactly one of the two causes startup to fail.

Backpressure

PulsusDB protects memory with a bounded ingest queue. It returns 429 when the queue is full and 413 when one push exceeds PULSUS_BATCH_BYTES. Keep Collector retries enabled and tune batch sizes below the server’s per-push limit.

PulsusDB records one accepted push as one ClickHouse insert block and uses a stable insert token to suppress retries. It does not split an oversized push.

Compatibility receivers

Set PULSUS_COMPAT_ENDPOINTS=true only when a client cannot send OTLP or remote write. This mounts third-party-compatible paths such as Loki push and selected trace/profile receivers. The product-neutral PulsusDB APIs and OTLP remain available regardless of this flag.