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
Operating an observability platform on ClickHouse and choosing a tool
Operate ClickHouse for telemetry (replication, disks, merges, object storage, monitoring) and com...
Installing and deploying ClickStack: all-in-one, Docker Compose, Helm and Managed ClickStack
Deploying ClickStack to fit the need: all-in-one container with persistence, Docker Compose and i...
Sending traces to Tempo: OpenTelemetry instrumentation and Alloy
Produce and route traces to Tempo: Python/Java/Node auto-instrumentation, the manual SDK, OTEL en...
Operating ClickHouse for ClickStack: sizing, replication, monitoring, security and backup
Running ClickHouse in production for observability: estimating volume and disk, replicating with ...
OpenTelemetry Collector, Grafana Alloy and Bindplane: comparing three approaches to telemetry pipelines
Detailed comparison of three ways to manage telemetry pipelines: the OpenTelemetry Collector in Y...
OTLP explained: understanding the OpenTelemetry protocol
The OTLP protocol explained simply. Understand the differences between gRPC and HTTP for exportin...
Grafana Alloy vs OpenTelemetry Collector: Which One Should You Choose?
A detailed comparison between Grafana Alloy and the OpenTelemetry Collector. Discover the strengt...
OpenTelemetry Collector: processors (transforming, filtering and protecting telemetry)
Master OpenTelemetry Collector processors: batch, memory_limiter, attributes, resource, filter, t...
Collecting logs into Loki: Alloy, Promtail, Docker and OpenTelemetry
Send logs to Loki: Grafana Alloy, Promtail, the Docker driver, OTLP, good labels, parsing and enr...