How to Monitor ArgoCD Deployment Sync Status and Health

ArgoCD continuously compares what is in your Git repository with what is actually running in your Kubernetes cluster. When something drifts, a sync fails, or a pod enters CrashLoopBackOff, you need to know before your users do.

This guide walks through four practical approaches to ArgoCD monitoring: the built-in dashboard, the CLI, Prometheus metrics with alerting, and the Notifications controller. By the end you will have Prometheus alert rules ready to fire, and notification triggers that send messages to Slack or Teams the moment a deployment goes wrong. 

1. Understanding Sync Status vs Health Status

Before writing a single PromQL query, you need to understand what ArgoCD is actually measuring. These two dimensions are independent, and each answers a different question.

Sync Status

Sync Status answers: “Does the cluster match what is in Git?” ArgoCD renders the manifests from your repository and compares them field by field against live resources in Kubernetes. The three possible values are:

• Synced: every resource in Git exists in the cluster with the same configuration.
• OutOfSync: at least one resource differs, whether because of a new commit, a manual kubectl edit, an HPA scaling event, or a partial sync failure.
• Unknown: ArgoCD cannot render the manifests, usually due to a bad repo URL, missing credentials, or a Helm/Kustomize template error.

Health Status

Health Status answers: “Is the application actually working?” ArgoCD evaluates built-in health checks for standard Kubernetes resource types (Deployments, StatefulSets, DaemonSets, Services, Ingresses, PVCs, Jobs, CronJobs) and rolls up the worst status across all child resources.

• Healthy: all resources with health checks are in their desired operational state.
• Progressing: resources are moving toward healthy but have not arrived yet. Normal during rolling updates.
• Degraded: something is wrong. Common causes include CrashLoopBackOff, ImagePullBackOff, Deployment progress deadline exceeded, or StatefulSet pods stuck waiting.
• Suspended: the resource is intentionally paused (spec.paused: true on a Deployment, or spec.suspend: true on a CronJob).
• Missing: a resource defined in Git does not exist in the cluster at all.
• Unknown: ArgoCD cannot determine health, often because no health check is defined for that resource type.

An application can be Synced but Degraded (Git matches the cluster, but the pods are crashing) or OutOfSync but Healthy (a new commit has not been applied yet, but everything running is fine). You need both dimensions to understand the full picture.

2. Using the ArgoCD Dashboard and CLI

The Web Dashboard

The ArgoCD web UI gives you an instant overview. Every application tile shows both sync and health status with colour-coded badges. Click any application to drill into individual resource trees, view live manifests, compare desired vs live state, and inspect sync history.

For OutOfSync applications, the Diff View presents an inline or split comparison of exactly which fields have changed. This is the fastest way to identify whether drift came from an accidental kubectl patch or an HPA scaling event.

The ArgoCD CLI

The CLI is the most direct way to query ArgoCD status from scripts and CI pipelines. Install it by downloading the binary from the releases page or via your package manager.

Common commands for monitoring:

# List all applications with their current sync and health status

argocd app list

# List all applications with their current sync and health status

argocd app list

# Get a detailed status report for a specific application

argocd app get <application-name>

# Get a detailed status report for a specific application

argocd app get <application-name>

# Filter degraded applications using jq

argocd app list -o json | jq -r '.[] | select(.status.health.status == "Degraded") | .metadata.name'

# Filter degraded applications using jq

argocd app list -o json | jq -r '.[] | select(.status.health.status == "Degraded") | .metadata.name'

# Filter OutOfSync applications

argocd app list -o json | jq -r '.[] | select(.status.sync.status == "OutOfSync") | .metadata.name'

# Filter OutOfSync applications

argocd app list -o json | jq -r '.[] | select(.status.sync.status == "OutOfSync") | .metadata.name'

# Review sync history for a specific application

argocd app history <application-name>

# Review sync history for a specific application

argocd app history <application-name>

# Check cluster connectivity

argocd cluster list

# Check cluster connectivity

argocd cluster list

3. Monitoring ArgoCD with Prometheus Metrics

ArgoCD exposes Prometheus metrics out of the box on port 8082 via the argocd-metrics service. No additional configuration is needed to enable them.

Available Metric Endpoints

ArgoCD exposes metrics from multiple services:

• argocd-metrics (port 8082): application controller metrics including sync and health status.
• argocd-server-metrics (port 8083): API server request latency and gRPC metrics.
• argocd-repo-server (port 8084): repository server metrics.

Verify the service is running:

kubectl get svc -n argocd | grep metrics

kubectl get svc -n argocd | grep metrics

Scraping Metrics with a ServiceMonitor (Prometheus Operator)

If you are running the Prometheus Operator, add a ServiceMonitor to scrape ArgoCD:

apiVersion: monitoring.coreos.com/v1

kind: ServiceMonitor

metadata:

  name: argocd-metrics

  namespace: argocd

spec:

  selector:

    matchLabels:

      app.kubernetes.io/name: argocd-metrics

  endpoints:

  - port: metrics

apiVersion: monitoring.coreos.com/v1

kind: ServiceMonitor

metadata:

  name: argocd-metrics

  namespace: argocd

spec:

  selector:

    matchLabels:

      app.kubernetes.io/name: argocd-metrics

  endpoints:

  - port: metrics

Key Metrics for Sync Status Monitoring

argocd_app_info is a gauge metric that always has a value of 1 and carries the current sync and health status as labels:

argocd_app_info{

  name="my-app",

  namespace="argocd",

  dest_namespace="production",

  health_status="Healthy",

  sync_status="Synced",

  project="default"

}

argocd_app_info{

  name="my-app",

  namespace="argocd",

  dest_namespace="production",

  health_status="Healthy",

  sync_status="Synced",

  project="default"

}

argocd_app_sync_total is a counter for sync operations. The phase label can be Succeeded, Failed, Error, Running, or Terminating:

argocd_app_sync_total{name="my-app", phase="Succeeded"}

argocd_app_sync_total{name="my-app", phase="Succeeded"}

Essential PromQL Queries

Track sync status across all applications:

# All applications currently OutOfSync

argocd_app_info{sync_status="OutOfSync"}

# All applications currently OutOfSync

argocd_app_info{sync_status="OutOfSync"}

# Count of OutOfSync applications

count(argocd_app_info{sync_status="OutOfSync"})

# Count of OutOfSync applications

count(argocd_app_info{sync_status="OutOfSync"})

# Sync status breakdown across all apps

count(argocd_app_info) by (sync_status)

# Sync status breakdown across all apps

count(argocd_app_info) by (sync_status)

Track health across all applications:

# All Degraded applications

argocd_app_info{health_status="Degraded"}

# All Degraded applications

argocd_app_info{health_status="Degraded"}

# Applications currently Progressing (potential stuck rollout)

argocd_app_info{health_status="Progressing"}

# Applications currently Progressing (potential stuck rollout)

argocd_app_info{health_status="Progressing"}

Sync success rate as a Service Level Indicator:

# Sync success rate over the last hour

sum(rate(argocd_app_sync_total{phase="Succeeded"}[1h]))

/ sum(rate(argocd_app_sync_total[1h]))

* 100

# Sync success rate over the last hour

sum(rate(argocd_app_sync_total{phase="Succeeded"}[1h]))

/ sum(rate(argocd_app_sync_total[1h]))

* 100

# Sync failure rate per minute

sum(rate(argocd_app_sync_total{phase="Failed"}[5m])) * 60

# Sync failure rate per minute

sum(rate(argocd_app_sync_total{phase="Failed"}[5m])) * 60

Cluster connectivity:

# Cluster connection status (1 = connected, 0 = failed)

argocd_cluster_connection_status{server!=""}

# Cluster connection status (1 = connected, 0 = failed)

argocd_cluster_connection_status{server!=""}

4. Prometheus Alerting Rules for ArgoCD

Prometheus alerting rules let you fire alerts when applications stay OutOfSync or Degraded for longer than a configurable threshold. Add these to your Prometheus configuration:

groups:

- name: argocd

groups:

- name: argocd

rules:

  - alert: ArgocdApplicationOutOfSync

    expr: argocd_app_info{sync_status="OutOfSync"} == 1

    for: 15m

    labels:

      severity: warning

    annotations:

      summary: "ArgoCD application {{ $labels.name }} is OutOfSync"

      description: "{{ $labels.name }} has been OutOfSync for 15 minutes."

rules:

  - alert: ArgocdApplicationOutOfSync

    expr: argocd_app_info{sync_status="OutOfSync"} == 1

    for: 15m

    labels:

      severity: warning

    annotations:

      summary: "ArgoCD application {{ $labels.name }} is OutOfSync"

      description: "{{ $labels.name }} has been OutOfSync for 15 minutes."

- alert: ArgocdApplicationDegraded

    expr: argocd_app_info{health_status="Degraded"} == 1

    for: 5m

    labels:

      severity: critical

    annotations:

      summary: "ArgoCD application {{ $labels.name }} is Degraded"

- alert: ArgocdApplicationDegraded

    expr: argocd_app_info{health_status="Degraded"} == 1

    for: 5m

    labels:

      severity: critical

    annotations:

      summary: "ArgoCD application {{ $labels.name }} is Degraded"

- alert: ArgocdSyncFailed

    expr: increase(argocd_app_sync_total{phase="Failed"}[10m]) > 0

    labels:

      severity: warning

    annotations:

      summary: "ArgoCD sync failed for {{ $labels.name }}"

- alert: ArgocdSyncFailed

    expr: increase(argocd_app_sync_total{phase="Failed"}[10m]) > 0

    labels:

      severity: warning

    annotations:

      summary: "ArgoCD sync failed for {{ $labels.name }}"

- alert: ArgocdClusterNotConnected

    expr: argocd_cluster_connection_status == 0

    for: 2m

    labels:

      severity: critical

    annotations:

      summary: "ArgoCD cannot connect to cluster {{ $labels.server }}"

- alert: ArgocdClusterNotConnected

    expr: argocd_cluster_connection_status == 0

    for: 2m

    labels:

      severity: critical

    annotations:

      summary: "ArgoCD cannot connect to cluster {{ $labels.server }}"

5. ArgoCD Notifications for Real-Time Alerting

The ArgoCD Notifications controller sends alerts directly to Slack, Microsoft Teams, email, or any webhook the moment a trigger condition is met. It ships as part of ArgoCD from version 2.3 onwards.

Built-in Triggers

ArgoCD ships with default triggers configured in argocd-notifications-cm. The most useful ones are:

• on-sync-failed: fires when a sync operation transitions to Failed.
• on-sync-succeeded: fires when a sync completes successfully.
• on-health-degraded: fires when application health changes to Degraded.
• on-sync-status-unknown: fires when sync status becomes Unknown.

Configuring a Slack Notification

Subscribe an application to a trigger and service in the Application’s annotations:

apiVersion: argoproj.io/v1alpha1

kind: Application

metadata:

  name: my-app

  annotations:

    notifications.argoproj.io/subscribe.on-sync-failed.slack: my-deploy-alerts

    notifications.argoproj.io/subscribe.on-health-degraded.slack: my-deploy-alerts

apiVersion: argoproj.io/v1alpha1

kind: Application

metadata:

  name: my-app

  annotations:

    notifications.argoproj.io/subscribe.on-sync-failed.slack: my-deploy-alerts

    notifications.argoproj.io/subscribe.on-health-degraded.slack: my-deploy-alerts

Writing a Custom Trigger

Triggers are predicate expressions in argocd-notifications-cm. This example fires when an application has been Progressing for more than 10 minutes:

apiVersion: v1

kind: ConfigMap

metadata:

  name: argocd-notifications-cm

  namespace: argocd

data:

  trigger.on-long-progressing: |

    - when: app.status.health.status == 'Progressing'

      send: [app-sync-status]

apiVersion: v1

kind: ConfigMap

metadata:

  name: argocd-notifications-cm

  namespace: argocd

data:

  trigger.on-long-progressing: |

    - when: app.status.health.status == 'Progressing'

      send: [app-sync-status]

6. Custom Health Checks with Lua

ArgoCD uses built-in health checks for standard Kubernetes resource types. For custom resources (CRDs), you can write health checks in Lua and register them in the argocd-cm ConfigMap.

The following example adds a health check for a hypothetical custom resource:

apiVersion: v1

kind: ConfigMap

metadata:

  name: argocd-cm

  namespace: argocd

data:

  resource.customizations.health.mygroup.io_MyResource: |

    hs = {}

    if obj.status ~= nil then

      if obj.status.phase == "Running" then

        hs.status = "Healthy"

        hs.message = "Resource is running"

        return hs

      end

      if obj.status.phase == "Failed" then

        hs.status = "Degraded"

        hs.message = obj.status.message

        return hs

      end

    end

    hs.status = "Progressing"

    hs.message = "Waiting for status"

    return hs

apiVersion: v1

kind: ConfigMap

metadata:

  name: argocd-cm

  namespace: argocd

data:

  resource.customizations.health.mygroup.io_MyResource: |

    hs = {}

    if obj.status ~= nil then

      if obj.status.phase == "Running" then

        hs.status = "Healthy"

        hs.message = "Resource is running"

        return hs

      end

      if obj.status.phase == "Failed" then

        hs.status = "Degraded"

        hs.message = obj.status.message

        return hs

      end

    end

    hs.status = "Progressing"

    hs.message = "Waiting for status"

    return hs

7. Monitoring ArgoCD from CI/CD Pipelines

In GitHub Actions or any CI system, you can poll ArgoCD directly after a push to track whether the deployment completed successfully:

- name: Wait for ArgoCD sync

  run: |

    argocd app wait my-app \

      --sync \

      --health \

      --timeout 300

- name: Wait for ArgoCD sync

  run: |

    argocd app wait my-app \

      --sync \

      --health \

      --timeout 300

This command blocks until the application is both Synced and Healthy, or returns a non-zero exit code on timeout. Combine it with the ArgoCD CLI login step using a service account token stored as a CI secret.

For environments where you cannot install the ArgoCD CLI, you can query the API server directly:

# Get application status via API

curl -H "Authorization: Bearer $ARGOCD_TOKEN" \

  https://<argocd-server>/api/v1/applications/my-app \

  | jq '{sync: .status.sync.status, health: .status.health.status}'

# Get application status via API

curl -H "Authorization: Bearer $ARGOCD_TOKEN" \

  https://<argocd-server>/api/v1/applications/my-app \

  | jq '{sync: .status.sync.status, health: .status.health.status}'

8. Grafana Dashboards for ArgoCD

Once ArgoCD metrics flow into Prometheus, you can build Grafana dashboards to visualise deployment health across all clusters. The ArgoCD community maintains a reference dashboard on Grafana’s dashboard registry. You can import it by its ID directly from the Grafana UI.

For a production setup, recommended panels include:

• Application count by sync_status (Synced, OutOfSync, Unknown) as a stat panel.
• Application count by health_status (Healthy, Degraded, Progressing) as a stat panel with thresholds.
• Sync operation rate over time (Succeeded vs Failed) as a time series.
• Sync success rate percentage as a gauge with alert thresholds.
• Top 10 applications by reconciliation duration as a bar chart.
• Cluster connection status as a table with per-server status.

Observability platforms like CubeAPM, Datadog, and New Relic also offer pre-built ArgoCD integration, letting you correlate deployment events with application performance traces in a single pane of glass.

9. Common Monitoring Scenarios and How to Debug Them

Conclusion

ArgoCD monitoring comes down to two questions asked in parallel: does the cluster match Git, and is the application actually running? The built-in dashboard and CLI give you immediate answers for individual applications. Prometheus metrics and alert rules extend that visibility to your entire fleet and integrate with your existing on-call workflows. The Notifications controller bridges the gap between metric-level observability and real-time team communication.

Start with argocd_app_info to track sync and health status, add argocd_app_sync_total for rate and success metrics, and wire up on-sync-failed and on-health-degraded notifications to keep your team informed without manual dashboard checking.

DisclaimerThe information in this article is provided for educational purposes only. ArgoCD API references, metric names, and YAML configurations are based on the ArgoCD documentation and community resources available at the time of writing. Always consult the official ArgoCD documentation (argo-cd.readthedocs.io) for the most current details, as APIs and metric labels may change between releases.

FAQs