Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Instrument and send databreadcrumb arrow Fleet Managementbreadcrumb arrow Manage your fleetbreadcrumb arrow Collectorsbreadcrumb arrow Check fleet status
Grafana Cloud

Check the status of your fleet

Grafana Fleet Management provides a health status indicator so you can see at a glance if your collectors are healthy. You can find a collector’s health status in the Status column on the Inventory tab in the Fleet Management interface.

The health status indicator reflects the current state of the collector:

  • Green circle (Healthy) means the collector is healthy.
  • Yellow circle (Warning) means the collector is potentially unhealthy.
  • Yellow triangle (Unresponsive) means a configuration change has stalled while rolling out to the collector.
  • Red circle (Error or Configuration Error) means the collector is unhealthy.
  • Gray circle (Unknown or Unavailable) means the collector is not reporting data.

You can filter your fleet by status by clicking on the Status dropdown on the Inventory tab. You can also click a section of the Collector health status chart on the Overview tab to open the Inventory tab pre-filtered to that status.

How health status is determined

The health status is controlled by the following factors:

  • Has the collector contacted Fleet Management in the last 30 minutes? Grafana Alloy collectors contact Fleet Management by making GetConfig API requests. OpenTelemetry Collectors contact Fleet Management by making AgentToServer API requests.
  • Does the collector have any active alerts?
  • If the collector reports remote configuration status, is it reporting any remote configuration status errors?
  • Has a remote configuration change stalled while rolling out to the collector?

Note

Detailed remote configuration status reporting requires Grafana Alloy v1.12 or later. OpenTelemetry Collector instances report that a remote configuration error occurred, but don’t provide detailed error information such as line or column numbers. For collectors that don’t report remote configuration status, Fleet Management doesn’t use remote configuration status errors to determine health status.

The Fleet Management service fetches active alerts from the Grafana Prometheus instance. You must create alerts in your stack’s Prometheus Alertmanager to make them discoverable by the health status check. Refer to Create new alerts for guidance on labeling alerts and the Alertmanager documentation for tips on using Mimirtool to configure Alertmanager.

The Inventory status indicator reflects the collector’s overall health. Remote configuration status is reported with more information in the collector details view. Refer to Troubleshoot remote configuration errors if the rollout experiences errors.

Green status

A green health status indicates that the collector is operational. At minimum, an operational collector:

  • Has no active alerts.
  • Contacted Fleet Management in the last 30 minutes.
  • Has no reported remote configuration status errors.

Note

A false-positive healthy status can result if the collector_id label in an alert doesn’t match the collector ID that Fleet Management uses for the collector. For Alloy collectors, this value must match the id argument in the remotecfg block. For OpenTelemetry Collectors, this value must match the OpAMP instance UID found in the Supervisor persistent_state.yaml file. If the labels do not match, the alerts cannot be attributed to the collector. When Fleet Management checks the state of a mismatched collector, the service finds no active alerts.

Yellow status (warning)

A yellow circle health status warns that there might be an issue with the collector. It can have several causes:

  • Warning: The collector is in one of the following states:

    • It has an active, non-critical alert.
    • It has not contacted Fleet Management in the last 30 minutes.
    • Both of the above conditions are true.

  • Warning (Inactive): The collector is inactive. A collector becomes inactive in one of two ways:

    • It was shut down gracefully, which immediately marks it as inactive regardless of its last contact time. This behavior was introduced in Grafana Alloy v1.13.0.
    • It has not contacted Fleet Management in the last 3 hours.

    The inactive collector might or might not also have an active, non-critical alert.

Yellow status (unresponsive)

A yellow triangle health status indicates that the collector hasn’t applied a new configuration within two minutes. Fleet Management flags the rollout as potentially stuck. Refer to Troubleshoot configuration rollout issues if the unresponsive state persists.

Red status

A red health status indicates one or more of the following:

  • Error: The collector has an active, critical alert.
  • Configuration Error: The collector reported an error for the latest remote configuration. For Alloy collectors, you can view detailed error information, including line and column numbers of the faulty pipeline, in the Configuration tab of the collector’s details view. For OpenTelemetry Collector instances, the Configuration tab indicates that an error occurred but doesn’t provide detailed error information. Refer to Troubleshoot remote configuration errors for more information.

Gray status

A gray health status indicates that the collector has not reported telemetry. It has never had a heartbeat and has no active alerts.

Inactive collectors

Fleet Management marks a collector inactive and assigns a timestamp to indicate when this determination was made. A collector becomes inactive in one of two ways:

  • Graceful shutdown (Alloy v1.13.0 and later): When the collector shuts down gracefully, it is immediately marked as inactive.
  • Timeout: If the collector has not contacted Fleet Management for 3 hours, Fleet Management marks it inactive.

Inactive collectors don’t count toward a stack’s collector limit. If an inactive collector is re-registered, its status is reset and the timestamp is voided. If an inactive collector contacts Fleet Management, its status is reset and the timestamp is voided.

The Inventory page of the Fleet Management application shows only active collectors by default. You can change this view using the Status dropdown filter. Collectors that remain inactive for 30 days from their timestamp are deleted automatically by the Fleet Management application.

Next steps

If your collector is unhealthy or potentially unhealthy, refer to Troubleshoot an unhealthy collector for help diagnosing the problem.