1. Endpoints and ingestion key #
Everything goes through OTLP.
Principle #
Available in: ✓ Open source ✓ Managed ClickStack
ClickStack receives all telemetry through its OpenTelemetry collector: OTLP HTTP on 4318 or gRPC on 4317. Each request must carry the ingestion key, shown in the UI (Team Settings › API Keys), in the authorization header.
Watch out : The ingestion key lets anyone write into your database: store it as a secret, and do not expose OTLP ports to the Internet without TLS or filtering (except for the browser SDK, behind a dedicated endpoint).
2. Instrumenting applications #
OpenTelemetry SDKs and agents.
Standard variables #
export OTEL_EXPORTER_OTLP_ENDPOINT=http://clickstack:4318
export OTEL_EXPORTER_OTLP_HEADERS="authorization=$CLICKSTACK_INGESTION_KEY" # Team Settings › API Keys
export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=2.4.1
# Java example: OpenTelemetry agent, no code change
java -javaagent:opentelemetry-javaagent.jar -jar checkout.jarThese variables apply to every language (Java, .NET, Node.js, Python, Go…). ClickStack also provides SDKs wrapping OpenTelemetry that accept the key in their init function.
Attributes to get right #
service.name: theServiceNamecolumn, main UI filter.deployment.environment.name,service.version: separate production and staging, spot a regression.- Logs emitted through the OpenTelemetry SDK (or correlated): they carry
TraceIdandSpanId, which lets you go from a trace to its logs.
3. Forwarding through a collector #
File logs, enrichment, buffering.
Configuration #
A collector close to the applications (host agent or Kubernetes DaemonSet) reads log files, enriches data and forwards it to ClickStack with the ingestion key.
# Existing collector (contrib) forwarding to ClickStack: file logs and application OTLP
receivers:
otlp:
protocols: { grpc: { endpoint: 0.0.0.0:4317 }, http: { endpoint: 0.0.0.0:4318 } }
filelog:
include: [/var/log/nginx/*.log]
operators:
- type: regex_parser
regex: '^(?P<client>\S+) \S+ \S+ \[(?P<time>[^\]]+)\] "(?P<method>\S+) (?P<path>\S+) \S+" (?P<status>\d{3})'
processors:
batch: { send_batch_size: 10000, timeout: 5s }
memory_limiter: { check_interval: 1s, limit_percentage: 80, spike_limit_percentage: 20 }
resourcedetection: { detectors: [env, system] }
exporters:
otlphttp/clickstack:
endpoint: http://clickstack:4318
headers: { authorization: ${env:CLICKSTACK_INGESTION_KEY} }
compression: gzip
service:
pipelines:
logs: { receivers: [otlp, filelog], processors: [memory_limiter, resourcedetection, batch], exporters: [otlphttp/clickstack] }
traces: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlphttp/clickstack] }
metrics: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlphttp/clickstack] }
telemetry:
metrics: { address: 0.0.0.0:9888 } # two collectors on one host: change the internal metrics portKubernetes #
- A DaemonSet collector reads pod logs (
/var/log/pods) and node metrics (kubeletstats); thek8sattributesprocessor adds namespace, pod and deployment. - A Deployment collector gathers cluster metrics (k8s_cluster) and events, once for the whole cluster.
- The official OpenTelemetry Collector Helm chart provides both modes (
kubernetesAttributes,logsCollection,kubeletMetricspresets).
4. Browser sessions #
Replay linked to traces.
The browser SDK #
// npm install @hyperdx/browser: sessions, errors and traces in the browser
import HyperDX from '@hyperdx/browser';
HyperDX.init({
url: 'https://otel.example.com', // collector OTLP HTTP endpoint (exposed over HTTPS)
apiKey: '<ingestion-key>',
service: 'shop-web',
tracePropagationTargets: [/api\.exemple\.fr/i], // propagates traceparent to the back end
consoleCapture: true,
advancedNetworkCapture: false, // only enable request body capture knowingly
});
HyperDX.setGlobalAttributes({ userId: 'u-1842' }); // opaque ID, never an e-mailSessions are stored in the hyperdx_sessions table. In the UI, a back-end error leads to the trace, then to the browser session that triggered it, with its replay.
Best practice : Replay masks input fields by default; check that no personal data appears in replayed pages and collect consent if needed.
5. Schema, throughput and security #
The settings that matter.
Map or JSON? #
By default, attributes are stored in Map(LowCardinality(String), String) columns (LogAttributes, SpanAttributes, ResourceAttributes): it is the recommended choice. A schema using ClickHouse's JSON type exists in beta (enabled by a collector feature gate, clickhouse.json): keep it for trials with a small, stable set of attributes.
Throughput #
- ClickHouse prefers few inserts of large batches: keep the
batchprocessor (thousands of events, a few seconds). - Add
memory_limiterand, for spikes, a persistent queue (file_storageextension) so nothing is lost during an outage. - Filter out what has no value at the source (health probes, debug logs): every stored line costs disk.
Commands to know #
Commands to know
OTEL_EXPORTER_OTLP_ENDPOINT=http://clickstack:4318: collector addressOTEL_EXPORTER_OTLP_HEADERS=authorization=<clé>: ingestion keycurl -s localhost:8888/metrics | grep otelcol_exporter_sent: events sent by the collectorcurl -s localhost:8888/metrics | grep send_failed: failed sendsSELECT ServiceName, count() FROM otel_logs WHERE Timestamp > now() - INTERVAL 5 MINUTE GROUP BY ServiceName: check logs are arriving
Sources #
Checked in November 2026: ClickStack evolves fast (Managed ClickStack is in beta), check the ClickHouse documentation before relying on a detail.
My progress
Sign in to track your progress and take notes. Sign in
💬 Questions about this lesson
No questions yet: be the first to ask for help or share your configuration.
Recommended Articles
Telemetry in ClickHouse: schema, SQL, materialized views and retention
Telemetry in ClickHouse: otel_logs, otel_traces, otel_metrics_* and hyperdx_sessions tables, sort...
OpenTelemetry Collector: exporters (sending telemetry to backends)
Configure OpenTelemetry Collector exporters: OTLP gRPC/HTTP, Prometheus, prometheusremotewrite, L...
Exploring with the ClickStack UI: sources, search, traces, sessions and SQL
Using the ClickStack UI (HyperDX): data sources, property and full-text search syntax, SQL mode, ...
ClickStack: architecture, components and offerings (ClickHouse, HyperDX, OpenTelemetry)
ClickStack, ClickHouse's official observability stack: role of ClickHouse, the UI (HyperDX), the ...
Sending logs, metrics and traces to OpenObserve
OpenObserve receiving endpoints: JSON, bulk, OTLP with the OpenTelemetry Collector, Prometheus re...
SigNoz, ClickStack and ClickHouse best practices for observability
Best practices for observability on ClickHouse with SigNoz or ClickStack: OpenTelemetry instrumen...
Observability on ClickHouse: why a columnar database changes the game
Why more and more observability platforms store logs, traces and metrics in ClickHouse: columnar ...
Grafana Alloy: collecting and transforming telemetry
Learn how to use Grafana Alloy to collect, transform and route logs, metrics and traces. Discover...
Alerts and dashboards in ClickStack
Building charts and dashboards in ClickStack, creating alerts on a search or a chart, sending the...