Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Instrument and send databreadcrumb arrow Fleet Managementbreadcrumb arrow Introductionbreadcrumb arrow Glossary
Grafana Cloud

Fleet Management glossary

This topic explains the key terminology and concepts of Grafana Fleet Management.

Attribute, local
A key-value pair set by users in a collector’s local configuration. Local attributes are not unique identifiers. Attribute keys are limited to 100 characters, while attribute values are limited to 150 characters. When used as matchers, attributes are limited to 200 characters, including key, value, and operator. The same attribute can be assigned to multiple collectors. collector.ID is a virtual local attribute with a value equal to the collector’s ID and cannot be modified. Remote attributes set in the Fleet Management interface take precedence over local attributes. For Grafana Alloy collectors, local attributes are set in the remotecfg block. For OpenTelemetry Collectors, local attributes are configured in the supervisor.yaml file. To learn the benefits of organizing your fleet with custom local attributes, refer to the Inventory overview.
Attribute, matching
Also known as a matcher. Inspired by Alertmanager, this conditional determines which configuration pipelines are applied at collector runtime. A matching attribute has three parts:
  • An attribute name formatted as an unquoted literal or a double-quoted string.
  • An operator. There are 4 possibilities:
    • =: is equal to
    • !=: is not equal to
    • =~: matches the regular expression
    • !~: does not match the regular expression
  • An attribute value or regular expression formatted as an unquoted literal or a double-quoted string.

Note

Unquoted literals can contain all UTF-8 characters other than whitespace and the following reserved characters: {, }, !, =, ~, ", ', \.

The maximum length of a matching attribute is 200 characters, including key, value, and operator.

For example, the matching attribute collector.os!=windows applies a configuration pipeline to all collectors where the operating system is not Windows. Here are some additional examples of matching attributes:

  • namespace=~"dev|staging"
  • team!~"team-.*"
  • profiling_enabled=true
  • arch!=amd64
  • collector.version=~"v1.2.0|v1.3.0"
  • collector.os=~".+"

The last matching attribute, collector.os=~".+", is a useful regular expression that matches all collectors, as the regular expression matches non-empty collector.os attributes and collectors always report this reserved attribute

Matching attributes use AND logic, so all attributes must match for a collector to use a configuration pipeline. For example, if a configuration pipeline has matching attributes ["os=linux", "env=prod", "cluster=prod-us-east-0"], collectors must have os=linux AND env=prod AND cluster=prod-us-east-0 attributes to receive this pipeline. You can assign attributes to a collector without affecting the selection process. The collector-pipeline pairing is determined by the matching attributes assigned in a configuration pipeline.

Attribute, remote
Also known as an attribute override or a user-defined attribute. A key-value pair created by users and assigned to collectors through the Fleet Management user interface. Remote attributes are not unique identifiers. Attribute keys are limited to 100 characters, while attribute values are limited to 150 characters. When used as matchers, attributes are limited to 200 characters, including key, value, and operator. The same attribute can be assigned to multiple collectors. Remote attributes cannot begin with collector., which is a reserved namespace. Remote attributes take precedence over local attributes. If a remote attribute uses the same key as a local attribute, Fleet Management uses the remote attribute value. To learn the benefits of organizing your fleet with custom remote attributes, refer to the Inventory overview.
Attribute, reserved
A key-value pair set automatically by the Fleet Management service based on data reported by the collector. Users cannot create attribute keys beginning with collector. because it is a reserved namespace, which means the following attribute keys are reserved for all collector types:
  • collector.os
  • collector.version
  • collector.ID

In addition to collector.* keys, the OpAMP Supervisor also sets the following attribute keys automatically for OpenTelemetry Collectors. You can modify the default values but only from your local environment.

  • service.name
  • service.namespace
  • service.version
  • service.instance.id
  • os.type
  • os.description
  • host.*
  • cloud.*
Collector
Software that pulls or receives telemetry from your applications or infrastructure, processes the data, and sends it to a backend for analysis. Collectors are made up of components defined in a configuration file. Fleet Management supports Alloy (v1.7.2 or later) and the OpenTelemetry Collector.
Configuration pipeline
Also known as a pipeline. A piece of configuration created in Fleet Management and remotely assigned to collectors based on attribute matching. Configuration pipelines are made up of a unique name, a content body, and matching attributes. All configuration pipelines that match to a collector are merged on the server side to form the remote configuration for that collector. Configuration pipelines are highly customizable. You can turn them on or off with a switch, share components between them, and inject attributes with variable values. The following annotated example shows a configuration pipeline for the Nginx Linux integration after it’s been processed by the Fleet Management server. It includes the unique name of the pipeline as well as the content body, which configures logs and metrics collection. You can assign matching attributes to the pipeline using the Fleet Management interface or the Pipeline API.
Alloy 
// "nginx_linux" is the name of the pipeline as defined in Fleet Management
// Fleet Management applies the declare block automatically
declare "nginx_linux" {

// The first three components configure metrics collection
// This component creates a labeled list of metrics scrape targets
  discovery.relabel "metrics_integrations_integrations_nginx" {
    targets = [{
      __address__ = "localhost:9113",
    }]

    rule {
      target_label = "instance"
      replacement  = constants.hostname
    }
  }

// This component scrapes Prometheus-format metrics from targets
  prometheus.scrape "metrics_integrations_integrations_nginx" {
    targets    = discovery.relabel.metrics_integrations_integrations_nginx.output
    forward_to = [prometheus.remote_write.metrics_service.receiver]
    job_name   = "integrations/nginx"
  }

// This component sends metrics to Grafana Cloud
  prometheus.remote_write "metrics_service" {
    endpoint {
      url = "https://prometheus-prod-001-prod-us-east-0.grafana.net/api/prom/push"

      basic_auth {
        username = "1234567"
        password = sys.env("GCLOUD_RW_API_KEY")
      }
    }
  }

// The last three components configure logs collection
// This component sets the log file path and labels
  local.file_match "logs_integrations_integrations_nginx" {
    path_targets = [{
      __address__ = "localhost",
      __path__    = "<path to json nginx access log>",
      host        = "<http_hostname>",
      instance    = constants.hostname,
      job         = "integrations/nginx",
    }]
  }

// This component reads logs from targets
  loki.source.file "logs_integrations_integrations_nginx" {
    targets    = local.file_match.logs_integrations_integrations_nginx.targets
    forward_to = [loki.write.grafana_cloud_loki.receiver]
  }

// This component sends logs to Grafana Cloud
  loki.write "grafana_cloud_loki" {
    endpoint {
      url = "https://logs-prod-001.grafana.net/loki/api/v1/push"

      basic_auth {
        username = "1234567"
        password = sys.env("GCLOUD_RW_API_KEY")
      }
    }
  }
}
Effective configuration
The remote configuration that an Alloy collector is currently running. The effective configuration reflects the last successfully applied remote configuration and does not change until the collector polls and successfully applies a new update. You can view a collector’s effective configuration in the Configuration tab of the collector details view. When the effective configuration differs from the server configuration, Fleet Management displays a rollout status banner indicating whether the update is pending, has stalled, has been successfully applied, or has failed. Effective configuration reporting requires Alloy v1.12.0 or later. Older Alloy versions don’t report an effective configuration, so the Configuration tab shows only the server configuration, which might not be the configuration running on the collector.
Fleet
Aggregate term for multiple collector instances.
Inventory
The list view of your collector fleet.
OpAMP
Short for Open Agent Management Protocol. An open source protocol for remote management of telemetry agents over HTTP or WebSocket. Fleet Management implements an OpAMP server that communicates with OpenTelemetry Collectors using Supervisors to deliver remote configuration updates and collect health data. Refer to the OpAMP specification for more information.
Remote configuration
The set of one or more configuration pipelines matched to a collector’s attributes. Remote configurations are run in parallel with a collector’s local configuration.
remotecfg
A block of configuration added to an Alloy local configuration file that registers the collector with the Fleet Management service. Several arguments make up the remotecfg block, including one for attributes. For the complete list of supported arguments, refer to the documentation.
Server configuration
The latest version of a collector’s remote configuration, including all matched pipelines, on the Fleet Management server. When you update a configuration pipeline, the server configuration changes immediately, but the collector does not run the new configuration until it polls and successfully applies the update. If the server configuration differs from the effective configuration, Fleet Management shows both versions in the Configuration tab of the collector details view. This dual display means the collector has not yet picked up the change or the new configuration contains errors that prevent it from being applied.
Supervisor
Also known as the OpAMP Supervisor. A process that runs alongside an OpenTelemetry Collector and manages its connection to Fleet Management using the OpAMP protocol. The Supervisor registers the collector with Fleet Management, receives remote configuration updates, and restarts the collector when its configuration changes. It’s configured using a supervisor.yaml file.