About Observability

Midaz exports telemetry through OpenTelemetry. Deploy a collector in your Kubernetes cluster, then configure Midaz workloads to send telemetry to it.

Deploy a collector

The Lerian OpenTelemetry Collector chart runs as a DaemonSet and receives OTLP telemetry on gRPC port 4317 and HTTP port 4318. It collects traces, logs, and metrics from Kubernetes workloads and exports them to Lerian’s central telemetry backend. The chart binds the collector to the node network and reads the export API key from a Secret named otel-api-key, key api-key, in the release namespace. Create the namespace and that Secret before you install the chart:

CHART_VERSION=replace-with-chart-version
read -rsp 'OpenTelemetry API key: ' OTEL_API_KEY; printf '\n'
kubectl create namespace midaz --dry-run=client -o yaml | kubectl apply -f -
printf '%s' "$OTEL_API_KEY" | kubectl -n midaz create secret generic otel-api-key \
  --from-file=api-key=/dev/stdin
unset OTEL_API_KEY

Install the collector as a separate release, with no values override:

helm install otel-collector-lerian \
  oci://registry-1.docker.io/lerianstudio/otel-collector-lerian \
  --version "$CHART_VERSION" -n midaz

Do not set opentelemetry-collector.extraEnvs in your own values to add the key. Helm replaces that list instead of merging it. The chart’s own entries, the API key and the node name that the kubelet receiver reads, disappear with it.

Connect Midaz workloads

In Midaz chart versions 8.4.0 and later, otel-collector-lerian is not a Midaz subchart. The setting below does not install a collector. It injects HOST_IP, POD_IP, OTEL_EXPORTER_OTLP_ENDPOINT=$(HOST_IP):4317, and OTEL_RESOURCE_ATTRIBUTES=k8s.pod.ip=$(POD_IP) into the Ledger and CRM deployments.

otel-collector-lerian:
  enabled: true

The default is true. It expects a node-local collector listening on port 4317 through hostNetwork or hostPort. To use another endpoint, disable this wiring and configure the endpoint directly for each workload:

otel-collector-lerian:
  enabled: false

ledger:
  configmap:
    OTEL_EXPORTER_OTLP_ENDPOINT: "https://your-collector.example.com:4317"
crm:
  configmap:
    OTEL_EXPORTER_OTLP_ENDPOINT: "https://your-collector.example.com:4317"

The Midaz chart accepts only enabled below otel-collector-lerian. The chart rejects legacy keys such as external, extraEnvs, exporters, and opentelemetry-collector during Helm installation or upgrade.

What the collector processes

The Lerian collector enriches telemetry with Kubernetes metadata and a client.id attribute. It applies memory limiting and batching, generates RED metrics from spans, masks sensitive payload data, and filters telemetry to the midaz and midaz-plugins namespaces before export. For chart parameters and production overrides, inspect the OpenTelemetry Collector chart metadata and values before deploying.

​Deploy a collector

​Connect Midaz workloads

​What the collector processes

Deploy a collector

Connect Midaz workloads

What the collector processes