Grafana Cloud

Set up Grafana Cloud Traces using Grafana Agent

Grafana Cloud provides a hosted traces connection that you can use to automatically gather tracing data emitted by your app, service, or process that has been instrumented to send traces. You have two options for using the Grafana Cloud Traces with your tracing data:

  • Grafana helps you collect, export, and store tracing data. This method uses the built-in capabilities in Grafana Cloud Traces.
  • You configure and store the tracing data and connect Grafana to the data store to visualize tracing data.

This getting started guide walks you through the first use case.

To set up and use tracing in Grafana Cloud, you need to:

  1. Add Hosted traces to your Grafana stack
  2. Install the Grafana Agent
  3. Configure Grafana Agent to send traces to hosted traces in Grafana Cloud
  4. Verify traces are received using visualizations

Before you begin

To set up Cloud Traces, you need:

Add Hosted traces to your Grafana instance

To start your Grafana instance and add Hosted traces:

  1. Sign in to your Grafana Cloud account in the Grafana Cloud Portal.
  2. Verify that your Organization is selected in the Organization drop-down in the upper left.
  3. Select Launch on the Grafana tile to access your instance.
  4. From the home page, select Connect data.
  5. Search for hosted traces. Select the Hosted traces tile.

Install Grafana Agent


Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

Grafana Agent needs to be installed on this system or instance to send the tracing data to Grafana Cloud.

Installing Grafana Agent differs for each operating system. For any operating system except macOS, you can either use the basic script provided to install a single binary or use the links to instructions specific for your operating system. Using the Grafana Agent installation instructions provides additional benefits, such as adding the Grafana Agent package repository to your system for easier updates.


If you are installing on macOS, you must use the macOS instructions and not the curl script on the Hosted traces > Configuration Details tab.

Select your OS from the links below and follow the installation instructions.

Return to this procedure when you are asked to customize the Grafana Agent configuration.

Operating system
Other systems

For more information about installation options, refer to Grafana Agent installation.

Configure Grafana Agent to send traces to Grafana Cloud

Next, you need to generate the API token and add it to your Grafana Agent configuration file. The API token is used by your Grafana instance to authenticate with the hosted traces instance.

For more information about the Grafana Agent configuration file, refer to Create a configuration file documentation.

For an example basic configuration file, refer to Set up and use tracing.

To configure Grafana Agent to send traces to Grafana Cloud:

  1. Return to the Hosted traces page in your Grafana instance.

  2. Under 3. Set the configuration, enter an API token name, using lowercase letters, numbers, and dashes. Select Create API token to generate your configuration, complete with your API token.

  3. Copy and paste the configuration snippet displayed in 3. Set the Configuration.

  4. Return to your console where you installed the Agent.

  5. Browse to and edit your configuration file. This location varies depending on your operating system. If the file does not exist, you will need to create it. \

    Operating systemFile location
    macOS (M1/M2)/opt/homebrew/etc/grafana-agent/config.yml
    macOS (Intel)/use/local/etc/grafana-agent/config.yml
    WindowsC:\Program Files\Grafana Agent\agent-config.yaml`
    DockerRefer to Create a configuration file
    Other systems(Depends upon default install locations)
  6. Copy and paste the following configuration block into the bottom of your Grafana Agent configuration file.

    # Configure trace receiving.
      # Define a single trace configuration (each being a Tempo instance), named `tempo`.
        - name: tempo
            - endpoint: ${GRAFANA_TRACES_HOST}
                username: ${GRAFANA_TRACES_USERNAME}
                password: ${GRAFANA_TRACES_API_TOKEN}
  7. Refer to the 3. Set the Configuration in the Configuration Details tab. Replace the placeholder text for endpoint, username, and password in your configuration file with the corresponding values from the Set the Configuration code block.

  8. Save the changes to your configuration file.

  9. Stop and restart the service. Refer to the installation page for your operating system linked above for details.

After you are sending data to Grafana Cloud, perform a search to verify that the data is received and accessible. For information on search, refer to Perform a Search.

Perform a search to check that data is received. For example, search for duration values between 5 and 100 milliseconds in the tracing data:

  1. Select Explore > Query type and choose Search.
  2. On the Duration fields, select > from the first drop-down, enter 5ms in the first text box, select < from the next drop-down, and then enter 100ms.
  3. Select Run query to search for tracing data.

The results should display a list of trace IDs with start time, name, and durations.