FluxCD

FluxCD Integration in Dash0

FluxCD is a set of continuous and progressive delivery solutions for Kubernetes, built on GitOps principles. It keeps your Kubernetes cluster in sync with sources of configuration such as Git repositories, Helm charts, and OCI artifacts, and automatically applies changes when the desired state evolves.

This Dash0 integration enables deep observability into FluxCD's GitOps Toolkit controllers — including the source, kustomize, helm, and notification controllers — so you can track reconciliation performance, detect drift, and respond to failures before they impact workloads.

For more information, visit the FluxCD Project Page.

Use Cases

Gain full visibility into your GitOps delivery pipeline with this integration:

• Monitor Reconciliation Cycles: Track the rate and duration of reconciliation runs across all Flux controllers to identify slow or stalled syncs.
• Detect Drift and Failures: Alert on failed reconciliations and resource drift before they affect running workloads.
• Analyze Controller Performance: Understand the internal health of the source, kustomize, helm, and notification controllers under load.
• Track Deployment Throughput: Measure how many Kubernetes resources Flux applies over time to gauge delivery velocity.
• Understand Dependency Chains: Correlate reconciliation events across multiple Flux resources to trace cascading failures.

Overview

This guide covers three observability signals for FluxCD:

• Metrics — The GitOps Toolkit controllers (source, kustomize, helm, and notification) each expose a Prometheus endpoint on port 8080. The OpenTelemetry Collector scrapes these and forwards them to Dash0 using the gotk_ metric prefix.
• Traces — FluxCD's notification controller can export distributed traces via its built-in OTel provider, correlating reconciliation events from source objects down through Kustomizations and HelmReleases.
• Logs — FluxCD controllers emit structured JSON logs that can be collected automatically by the Dash0 Operator or manually via the filelog receiver.

Prerequisites

Before setting up FluxCD monitoring, ensure:

• FluxCD is installed and running in your cluster (flux check reports healthy)
• You have access to the flux-system namespace
• You have an OpenTelemetry Collector deployed and reachable from the flux-system namespace

You'll need an OpenTelemetry Collector deployed. Consider using:

• Dash0 operator for Kubernetes (recommended)
• OpenTelemetry Operator for Kubernetes

• Helm Chart for The OpenTelemetry Collector

Collector Configuration

FluxCD controllers expose Prometheus metrics on port 8080 in the flux-system namespace.

Option 1: Static scrape config (OTel Operator or Helm Chart)

A standard FluxCD installation creates Kubernetes Services for source-controller and notification-controller, but those Services expose port 80 (the artifact/webhook port), not port 8080 (the metrics port). You need to create metrics Services for all four controllers:

Then configure the OpenTelemetry Collector's Prometheus receiver to scrape all four controllers:

Option 2: Dash0 Operator

First create a Dash0Monitoring resource in the flux-system namespace to enable Prometheus scraping. The instrumentWorkloads.mode: none setting is required because the flux-system namespace enforces a restricted PodSecurity policy that the operator's instrumentation init container does not satisfy. Then annotate the FluxCD controller deployments so the operator's collector discovers their pods:

For more options, see the Prometheus Receiver documentation.

Traces

FluxCD's notification controller can export distributed traces to an OpenTelemetry collector via its built-in otel provider. The controller converts Flux events into OTel spans that follow the Flux object dependency chain: source objects (GitRepository, HelmChart, OCIRepository, Bucket) produce root spans, and downstream objects (Kustomization, HelmRelease) become child spans within the same trace. Trace IDs use the format <AlertUID>:<revision>, so every span across a reconciliation cycle is correlated back to the originating source revision.

Create a Provider in the flux-system namespace pointing to your OpenTelemetry Collector's OpenTelemetry Protocol (OTLP) HTTP endpoint:

If you are using the Dash0 Operator, replace <otel-collector-endpoint> with its stable internal service address: dash0-operator-opentelemetry-collector-service.dash0-system.svc.cluster.local.

Then create an Alert that selects the Flux resources you want to trace:

If your collector requires authentication, create a Secret with the credentials:

Then add secretRef to your Provider spec:

For the full provider specification, see the FluxCD OTel Provider documentation.

Logs

FluxCD controllers write structured JSON logs to stderr. Each log line includes fields like controllerKind, name, namespace, reconcileID, level, and msg, making them easy to filter and correlate with metrics.

Dash0 Operator

If you applied a Dash0Monitoring resource to the flux-system namespace (as shown in the Collector Configuration section above), the Dash0 Operator automatically collects pod logs from all controllers in that namespace via the filelog receiver. No additional configuration is required.

OTel Operator or Helm Chart

To collect FluxCD controller logs manually, add a filelog receiver targeting the flux-system namespace to your OpenTelemetry Collector configuration:

Log and trace correlation

FluxCD logs and traces share the same dimensions — controllerKind, name, and namespace — so you can correlate them in Dash0 by filtering on those fields within the same time window. The reconcileID field in logs identifies a single reconciliation cycle and maps to the span hierarchy generated by the otel provider for the same resource. Note that reconcileID is not an OTel trace ID, so there is no automatic one-click correlation between a log line and its corresponding trace — use the resource name, kind, and timestamp to bridge them.

Verification

Metrics

1. Check collector logs for successful scrape of flux-system targets
2. Navigate to Metrics Explorer in Dash0
3. Search for metrics with prefix gotk_

gotk_reconcile_duration_seconds only appears after at least one Flux resource (e.g. a GitRepository or Kustomization) has been reconciled. If you see only gotk_token_cached_items initially, create a Flux resource and wait for the first reconciliation interval.

Key metrics to verify:

Traces

1. Trigger a reconciliation (e.g., push a commit to a watched Git repository)
2. Navigate to Traces in Dash0
3. Filter by service name <namespace>/<alert-name> — for example, flux-system/otel-alert

Logs

1. Navigate to Logs in Dash0
2. Filter by namespace: flux-system to see all controller logs
3. Use controllerKind and name fields to narrow down to a specific resource

References

• FluxCD Monitoring Documentation
• FluxCD Metrics Reference
• FluxCD OTel Provider Documentation
• FluxCD Logs Documentation
• OpenTelemetry Prometheus Receiver
• OpenTelemetry Filelog Receiver