Observability

Carlquist is OpenTelemetry-native. Every request through the platform generates distributed traces, structured logs, and Prometheus-compatible metrics. Correlation IDs flow end-to-end from adapter query through delivery.

Distributed Tracing

Carlquist propagates W3C Trace Context (traceparent header) on all outbound requests. If your system sends a traceparent header, Carlquist creates child spans under your existing trace. If no trace context is provided, Carlquist generates a root trace automatically.

Every response also includes an X-Request-Id header for correlation in logs and support requests.

Trace Spans

Carlquist creates the following span hierarchy for each request flowing through the pipeline:

adapter.query          (source system query)
└── mapping.transform  (schema transformation)
    └── policy.evaluate (auth, rate limit, masking)
        └── delivery.send (target delivery)
            └── delivery.retry (if needed)

Span Attributes

Each span carries structured attributes for filtering and analysis:

• adapter.type — Source system type (sqlserver, oracle, rest, etc.)
• adapter.name — Human-readable adapter name
• mapping.schema_version — Active schema version for the mapping
• endpoint.path — API endpoint path
• delivery.target — Target URL or identifier
• delivery.status_code — HTTP status code from the target
• delivery.duration_ms — End-to-end delivery time in milliseconds

Metrics

Carlquist exposes Prometheus-compatible metrics. All metrics use the carlquist_ prefix and include labels for filtering and aggregation.

Example Prometheus query for delivery error rate over the last hour:

rate(carlquist_delivery_total{status!="2xx"}[1h])
  / rate(carlquist_delivery_total[1h])

Structured Logs

All Carlquist logs are JSON-formatted with consistent fields across the platform:

{
  "timestamp": "2026-02-25T14:32:01.847Z",
  "level": "info",
  "message": "delivery.success",
  "request_id": "req_7f3a9b2c",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "adapter": "orders-db",
  "stream": "orders.created",
  "delivery_target": "https://your-app.com/hooks/orders",
  "status_code": 200,
  "duration_ms": 142
}

Log levels follow standard severity:

• debug — Detailed diagnostic information (disabled by default)
• info — Normal operations (delivery success, adapter connected)
• warn — Recoverable issues (retry triggered, backpressure applied)
• error — Failures requiring attention (delivery exhausted, adapter unreachable)

Export

Traces

Export traces via OTLP/gRPC or OTLP/HTTP to your OpenTelemetry collector:

carlquist config set observability.traces.exporter otlp
carlquist config set observability.traces.endpoint \
  https://otel-collector.internal:4317

Metrics

Metrics are available via a Prometheus scrape endpoint at /metrics (Enterprise plans) or can be pushed to your OTLP endpoint:

carlquist config set observability.metrics.exporter otlp
carlquist config set observability.metrics.endpoint \
  https://otel-collector.internal:4317

Logs

Logs are written to stdout in containerized deployments. Forward them to your log aggregator (Datadog, Elastic, Splunk) using your container runtime's log driver or a sidecar collector.

Dashboard

Carlquist includes built-in observability views in the dashboard for:

• Adapter query latency (p50, p95, p99)
• Delivery error rates by stream
• Throughput (events per second)
• DLQ depth over time
• Policy evaluation performance