Skip to content
NOEMATA

Send telemetry

Noemata bundles an OpenTelemetry collector and starts it with the rest of the stack. It receives OTLP, writes it to ClickHouse, and the OpenTelemetry semantic-layer views turn those tables into something frames can query. Anything that speaks OTLP — an application SDK, another collector, a sidecar — can point at it.

OTLP endpoints

The collector listens for OTLP on two ports:

  • HTTP on 4318
  • gRPC on 4317

Both take the standard worktree offset when left on "auto", so parallel worktrees don’t collide — check noemata status or the startup logs for the resolved ports.

Point any OTLP exporter at the HTTP endpoint with the usual environment variable:

Terminal window
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

That’s all most SDKs need. An app instrumented with OpenTelemetry, started with that variable set, sends its traces, logs, and metrics straight into Noemata.

What lands in ClickHouse

The collector’s ClickHouse exporter writes to fixed tables:

  • otel_traces
  • otel_logs
  • otel_metrics_sum, otel_metrics_gauge, otel_metrics_histogram

The @opentelemetry/views/* base views read exactly these tables and name the OpenTelemetry semantic conventions on top — ServiceName, DurationP95, IsError, and the rest — so frames build on the vocabulary instead of the raw columns. See Views for how a frame consumes a base view with imports.

Configuring the collector

The collector is configured under collect.collector in noemata.json, and defaults to a managed binary Noemata runs for you:

{ "collect": { "collector": { "binary": {} } } }
  • http_port / grpc_port — a number, or "auto" (the default) for the offset-based ports above.
  • version — pin a collector release.

You rarely edit the pipeline by hand. Integrations configure the collector for you — adding receivers that tail log files, scrape database stats, or collect host metrics — and are reconciled on every noemata up.

Verifying ingestion

After pointing something at the collector, confirm data is flowing:

  • Open a dashboard the OpenTelemetry integration installed (services, traces, logs) and check that rows appear.
  • Query the tables directly in ClickHouse — a non-zero count() on otel_traces or otel_logs for a recent time window means the pipeline is writing.

If nothing arrives, the usual causes are an exporter pointed at the wrong port (the offset moved it) or an app that never had OTEL_EXPORTER_OTLP_ENDPOINT set.

Monitoring the collector

The managed collector reports on itself: its internal metrics and its own logs are routed back through its OTLP receiver into ClickHouse every 30 seconds. Enable the OTel Collector integration to install the @otel_collector dashboard over that stream — per-receiver and per-exporter throughput, refused and failed items, sending-queue saturation, process health, and the collector’s log stream. It is the first place to look when data seems to be missing: a climbing queue or a burst of exporter errors pins down where the pipeline is stuck. (The collector’s stderr also lands in .data/log/collector.log for the case where the pipeline itself is down.)