Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Instrument and send databreadcrumb arrow Fleet Managementbreadcrumb arrow Set upbreadcrumb arrow Collector onboardingbreadcrumb arrow Standalone OpenTelemetry Collector installations
Grafana Cloud

Onboard standalone OpenTelemetry Collectors to Fleet Management

Learn how to register your existing OpenTelemetry Collectors in Grafana Fleet Management when they are installed outside of containers and directly on a host or virtual machine. If you’d like to use Fleet Management for self-managed collectors, refer to the set up instructions.

Before you begin

Before you get started with Fleet Management, make sure you have:

  • A Grafana Cloud account. To create an account, refer to Grafana Cloud.
  • Administrator privileges for Grafana Cloud or the Collector application and the ability to create and edit access policies.
  • Access to the host, virtual machine, or cluster where the collector runs.
  • Permission to set environment variables where the collector runs.
  • An understanding of the key terms and concepts of Fleet Management and how the service works.

For this OpenTelemetry Collector guide, you also need:

Note

You can monitor the health of Collectors connected to Fleet Management with the OpAMP extension only, but you won’t be able to configure them remotely. Use the Supervisor to enable remote configuration.

Create an access token

To begin the onboarding process, you must authorize Fleet Management to access your collectors.

  1. In your Grafana Cloud instance, navigate to Connections > Collector Setup.
  2. Select the collector type and operating system.
  3. Use the tool on this page to create a new token. Give the token a name and click Create token. You don’t need to complete the rest of the installation instructions if you’re not installing a new collector from this workflow.
  4. Copy the token and save it in a secure password file. You’ll need the token for the next step, but you won’t be able to view it again after you leave the page.

The generated token comes with the predefined scope set:otel-data-write, which includes scopes for reading remote configurations in Fleet Management and writing telemetry to Grafana Cloud databases. You can view the defined scopes by hovering over set:otel-data-write:

  • fleet-management:read
  • metrics:write
  • logs:write
  • traces:write
  • profiles:write

For more information about creating access policies, refer to Grafana Cloud access policies.

Note

If you create a policy using a different workflow or if you’re modifying an existing access policy, make sure to add the set:otel-data-write scope.

Configure the OpAMP Supervisor

Configure the OpAMP Supervisor to connect to Fleet Management and run the OpenTelemetry Collector. The Supervisor manages the Collector process and applies remote configuration that Fleet Management assigns to the Collector.

Note

You can shortcut these steps by following the Get started workflow to create a copyable Supervisor YAML configuration personalized to your Grafana Cloud stack.

  1. Set the following environment variables:

    • GCLOUD_FM_URL to the Fleet Management URL used by your Grafana Cloud stack. In your stack, navigate to Connections > Fleet Management, select the API tab, and scroll to the Base URLs section. Copy the base URL, making sure to remove any trailing slashes.
    • GCLOUD_INSTANCE_ID to your Grafana Cloud instance ID. On the same API tab in the Fleet Management application, scroll to the API Authentication section. Copy the instance ID.
    • GCLOUD_RW_API_KEY to the cloud access policy token that you created in Step 1.
    • GCLOUD_BASIC_AUTH_BASE64 to the base64-encoded representation of your authentication credentials in username:password format, where the username is your GCLOUD_INSTANCE_ID and the password is the GCLOUD_RW_API_KEY.

  2. Create a Supervisor configuration file named supervisor.yaml.

    YAML 
    server:
  endpoint: "${env:GCLOUD_FM_URL}/v1/opamp"
  headers:
    Authorization: "Basic ${env:GCLOUD_BASIC_AUTH_BASE64}"

capabilities:
  reports_effective_config: true
  accepts_remote_config: true
  reports_remote_config: true

agent:
  executable: "<OTELCOL_EXECUTABLE_PATH>"
  description:
    identifying_attributes:
      service.name: "<OTEL_COLLECTOR_NAME>"
    non_identifying_attributes:
      environment: "dev"
  args: [--feature-gates, service.AllowNoPipelines]

storage:
  directory: "<STORAGE_DIRECTORY>"

    Replace the placeholders as follows:

    • <OTELCOL_EXECUTABLE_PATH> with your local OpenTelemetry Collector executable path.
    • <OTEL_COLLECTOR_NAME> with a name of your choosing.
    • <STORAGE_DIRECTORY> with the path to a writable directory to use for persistent data storage, such as /var/lib/otelcol/supervisor for POSIX systems and %ProgramData%/Otelcol/Supervisor for Windows systems.

Run the Collector with the OpAMP Supervisor

Start the OpAMP Supervisor to run the Collector and register it with Fleet Management.

sh 
opampsupervisor --config=supervisor.yaml

Your Collector is up and running, and it’s registered with Fleet Management.

Add remote attributes

Collectors are configured remotely in Fleet Management when their attributes match the matching attributes of a configuration pipeline. If you haven’t specified local attributes in your collector configuration, or if you need additional attributes, add remote attributes through the Fleet Management interface. You have greater control over configurations when your collectors are well categorized with meaningful attributes.

Remote attributes can use the same key as local attributes. When this happens, the remote attribute value takes precedence for configuration matching, filtering, and attribute injection. You can see attribute overrides in the collector’s details view and remove them if you want to use the local attribute value.

To add remote attributes to collectors:

  1. In your Grafana Cloud stack, click Connections > Fleet Management.
  2. From the Inventory tab, select one or more collectors.
  3. Click the edit icon. The bulk edit tool appears.
  4. Click Add remote attributes.
  5. Follow the instructions to add remote attributes to the selected collectors.

Check the Attributes column on the Inventory tab to confirm that Fleet Management assigned the new attribute to the collectors you selected. Continue assigning remote attributes based on your configuration needs.

Note

You can’t add remote attributes with the following keys because they are reserved attributes:

  • service.name
  • service.namespace
  • service.version
  • service.instance.id
  • os.type
  • os.description
  • host.*
  • cloud.*
  • collector.*

Next steps

You have registered your collectors with Fleet Management and assigned attributes to them. Learn how to configure them remotely.