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:
- Add Hosted traces to your Grafana stack
- Install the Grafana Agent
- Configure Grafana Agent to send traces to hosted traces in Grafana Cloud
- Verify traces are received using visualizations
Before you begin
To set up Cloud Traces, you will need:
- A Grafana Cloud account (see documentation)
- A Grafana Cloud stack, with an active Grafana instance (see documentation)
- Elevated privileges on the host(s) where Grafana Agent will be installed
- An app instrumented for tracing (see the Tempo instrumentation page)
Add Hosted traces to your Grafana instance
To start your Grafana instance and add Hosted traces:
- Sign in to your Grafana Cloud account in the Grafana Cloud Portal.
- Verify that your Organization is selected in the Organization drop-down in the upper left.
- Select Launch on the Grafana tile to access your instance.
- From the home page, select Connect data.
- Search for hosted traces. Select the Hosted traces tile.
Install Grafana Agent
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.
Note: 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 |
---|
Linux |
macOS |
Windows |
Docker |
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:
Return to the Hosted traces page in your Grafana instance.
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.
Copy and paste the configuration snippet displayed in 3. Set the Configuration.
Return to your console where you installed the Agent.
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 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) Copy and paste the following configuration block into the bottom of your Grafana Agent configuration file.
yaml# 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}
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.
Save the changes to your configuration file.
Stop and restart the service. Refer to the installation page for your operating system linked above for details.
Verify traces are received using Search
Once you are sending data to Grafana Cloud, you can perform a search to verify that the data is received and accessible. For information on search, see Perform a Search.
To check that data is received, use these steps to search for duration values between 5 and 100 milliseconds in the tracing data:
- Select Explore > Query type and choose Search.
- 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 enter100ms
. - Select Run query to search for tracing data.
The results should display a list of trace IDs with start time, name, and durations.
Was this page helpful?
Related resources from Grafana Labs


