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. Create otel-values.yaml to make the collector node-local and wire the API-key Secret into its exporter:

opentelemetry-collector:
  hostNetwork: true
  dnsPolicy: ClusterFirstWithHostNet
  extraEnvs:
    - name: OTEL_API_KEY
      valueFrom:
        secretKeyRef:
          name: otel-api-key
          key: api-key
  config:
    exporters:
      otlphttp/server:
        headers:
          x-api-key: ${env:OTEL_API_KEY}

Create the namespace and API-key Secret before installing the chart:

kubectl create namespace midaz --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret generic otel-api-key \
  --from-literal=api-key=<your-api-key> \
  -n midaz \
  --dry-run=client -o yaml | kubectl apply -f -

Install the collector as a separate release:

helm install otel-collector-lerian \
  oci://registry-1.docker.io/lerianstudio/otel-collector-lerian \
  --version <version> \
  -n midaz \
  -f otel-values.yaml

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. Legacy keys such as external, extraEnvs, exporters, and opentelemetry-collector are rejected 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