OTEL (OpenTelemetry)

Deploys the OpenTelemetry Operator + Collector. Link an app to OTEL to auto-instrument it. Link OTEL to ClickHouse to store all telemetry.

How It Works

                App Pod ───OTLP(:4317/4318)───> Collector ───> ClickHouse (if linked)

                1. You link an app (image_base / external_source_code) to OTEL

                2. The app automatically gets a pod annotation + OTEL env vars

                3. OTEL Operator detects the annotation and injects instrumentation sidecar

                4. Instrumented app sends traces/metrics/logs to the Collector

                5. Collector processes and exports to ClickHouse (if linked)

Component Attributes

Attribute	Example	Description
`namespace`	`otel`	Kubernetes namespace for operator, collector, and instrumentation
`replicas`	`1`	Number of collector pod replicas
`cpu_request` / `cpu_limit`	`250m` / `500m`	Collector pod CPU resources
`mem_request` / `mem_limit`	`512Mi` / `1Gi`	Collector pod memory resources
`batch_timeout`	`5s`	How long the collector waits before flushing a batch
`batch_size`	`10000`	Max items per batch before the collector flushes
`memory_limit_mib`	`400`	Hard memory limit in MiB - collector starts dropping data above this
`memory_spike_limit_mib`	`100`	Spike allowance above the hard limit before OOM protection kicks in

Links

Link Type	Direction	What Gets Automated
`image_base-otel`	App → OTEL	Auto-instruments the app: generates pod annotation + OTEL env vars on the app
`external_source_code-otel`	App → OTEL	Same as above, for external_source_code apps
`otel-clickhouse_db`	OTEL → ClickHouse	Configures collector to export traces/metrics/logs to ClickHouse
`prometheus-otel`	Prometheus → OTEL	Prometheus scrapes OTEL operator metrics

App → OTEL Link (Auto-Instrumentation)

When you link an app (image_base or external_source_code) to OTEL, the automation happens on the app side - the app's deployment manifest and environment are automatically configured to send telemetry to the collector.

Link Attributes (you set these on the link)

Attribute	Values	Description
`otel_language` REQ	`java`, `python`, `nodejs`, `dotnet`, `go`	The programming language of the app. Determines which auto-instrumentation is injected.
`pythonpath`	`/usr/src/app`	Only needed for Python apps. Must match the Dockerfile WORKDIR.
`otel_language_custom`	custom annotation key	Overrides the standard instrumentation annotation. Use when a custom annotation key is needed instead of the default.

What Gets Auto-Generated on the App

Generated Item	Where	Example
Pod annotation	App deployment manifest	`instrumentation.opentelemetry.io/inject-python: "otel/otel-instrumentation"`
OTEL_EXPORTER_OTLP_ENDPOINT	App environment (cloud.env)	Collector HTTP endpoint on port 4318
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	App environment (cloud.env)	Collector traces endpoint (/v1/traces)
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	App environment (cloud.env)	Collector metrics endpoint (/v1/metrics)
OTEL_SERVICE_NAME	App environment (cloud.env)	Set to the app's component name
PYTHONPATH	App environment + deployment	Only if language=python and pythonpath is set

OTEL → ClickHouse Link (Telemetry Storage)

Links to a clickhouse_db sub-component. When linked, the collector image automatically switches to the contrib variant which includes the ClickHouse exporter. Auto-creates tables: otel_traces, otel_metrics, otel_logs.

Connection Logic (automatic)

                    if public_host is empty → Internal: TCP :9000 via svc.cluster.local

                    if public_host exists → External: HTTPS :443 + TLS skip verify

What Gets Configured from ClickHouse

From	Attribute	Used For
clickhouse_db sub-component	`database`	Target database name for telemetry tables
clickhouse_db sub-component	`ttl`	Data retention period for tables
ClickHouse parent component	`admin_user` / `admin_password`	Authentication credentials
Link attribute (external only)	`public_host`	External hostname for cross-cluster connection

Generated Files

File	Condition	Contains
`k8s/deploy/base/collector.yaml`	Always	OpenTelemetryCollector CR — receivers, processors, exporters (ClickHouse exporter added if linked)
`k8s/deploy/base/instrumentation.yaml`	Always	Instrumentation CR — defines auto-instrumentation images per language
`k8s/deploy/base/namespace.yaml`	Always	Namespace for OTEL resources
`k8s/deploy/base/kustomization.yaml`	Always	Kustomize config — resources, labels, registry secret
`helm/operator-values.yaml`	Always	Helm values for the OTEL Operator chart

Supported Auto-Instrumentation Languages

Language	Pod Annotation	Notes
java	`inject-java`	Full support
python	`inject-python`	Set `pythonpath` link attribute to match Dockerfile WORKDIR
nodejs	`inject-nodejs`	Full support
dotnet	`inject-dotnet`	Full support
go	`inject-go`	Annotation generated, but no auto-instrumentation image defined - requires manual setup