Documentation Grafana Cloud Instrument and send data Traces Set up and use tracing Set up traces with Grafana Agent

Set up Grafana Cloud Traces using Grafana Agent

Grafana Cloud Hosted traces provides a convenient configuration guide for sending trace data via Grafana Agent to your Grafana Cloud Traces instance.

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

1. Add Hosted traces to your Grafana stack
2. Install 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:

• A Grafana Cloud account (documentation)
• A Grafana Cloud stack, with an active Grafana instance (documentation)
• Elevated privileges on the host or hosts where Grafana Agent is installed
• An app instrumented for tracing (documentation)

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 Agent needs to be installed on a 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 Grafana Agent installation instructions provides additional benefits, such as adding Grafana Agent package repository to your system for easier updates.

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

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

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 Grafana Agent configuration file, refer to Create a configuration file documentation.

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 doesn’t exist, you need to create it.

   Operating system	File location
   Linux	/etc/grafana-agent.yaml
   macOS (M1/M2)	/opt/homebrew/etc/grafana-agent/config.yml
   macOS (Intel)	/use/local/etc/grafana-agent/config.yml
   Windows	C:\\Program Files\\Grafana Agent\\agent-config.yaml
   Docker	Refer 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.

   yaml Copy

   # Configure trace receiving.
   traces:
     # Define a single trace configuration (each being a Tempo instance), named `tempo`.
     configs:
       - name: tempo
         receivers:
           jaeger:
             protocols:
               grpc:
               thrift_binary:
               thrift_compact:
               thrift_http:
           zipkin:
           otlp:
             protocols:
               http:
               grpc:
           opencensus:
         remote_write:
           - endpoint: ${GRAFANA_TRACES_HOST}
             basic_auth:
               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 for details.

Verify traces are received using Search

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 Query tracing data.

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.