Set up Grafana Cloud Traces using Grafana Alloy

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 working with 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:

Install Grafana Alloy
Configure Grafana Alloy to send traces to Grafana Cloud Traces
Verify traces are being received using visualizations

Before you begin

To set up Grafana Cloud Traces, you need:

A Grafana Cloud account (documentation
A Grafana Cloud stack, with an active Grafana instance ([documentation]https://grafana.com/docs/grafana-cloud/introduction/)
Elevated privileges on the host or hosts where Grafana Alloy is installed
An app instrumented for tracing (see the Tempo instrumentation page

Add 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 Alloy

You can send spans to Grafana Cloud using Grafana Alloy. Alloy uses configuration file written using River. Grafana Alloy supports consuming traces in a number of common formats. The example configuration can be used to start an OTLP receiver with default ports for both gRPC and HTTP. Only start the receivers you need.

Installing Grafana Alloy differs for each operating system. Using the Grafana Alloy installation instructions provides additional benefits, such as adding the Grafana Alloy package repository to your system for easier updates.

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

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

Configure Grafana Alloy to send traces to Grafana Cloud

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

For more information about Grafana Alloy configuration and syntax, refer to Alloy configuration syntax.

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

To configure Grafana Alloy to send traces to Grafana Cloud Traces:

Navigate to the Grafana Cloud stack you want to send traces to.
Select Details from the Tempo section.
Generate a new token for sending data by selecting Generate now in the Sending data to Grafana Cloud using Grafana Alloy section. Copy the token.
Copy the example configuration from the same section into your Grafana Alloy configuration file. This location varies depending on your operating system. If the file doesn’t exist, you need to create it. Refer to Configure Grafana Alloy for more information.
- Linux: /etc/alloy/config.alloy
- macOS: $(brew --prefix)/etc/alloy/config.alloy
- Windows: %ProgramFiles%\GrafanaLabs\Alloy\config.alloy
Replace <Your Grafana.com API Token> in the configuration file with the token you generated in step 3.
Save the changes to your configuration file.
Stop and restart the service. Refer to the installation page for your operating system for details.

Optional: Add receivers for other trace formats

You can include receivers for other trace formats than just OpenTelemetry OTLP, such as Zipkin, and Jaeger by modifying the configuration file. Add the following receivers to your configuration file:

otelcol.receiver.jaeger "jaeger_receiver" {
  protocols {
    grpc {}
    thrift_http {}
    thrift_binary {}
    thrift_compact {}
  }

  output {
    traces = [otelcol.exporter.otlp.grafanacloud.input,]
  }
}

otelcol.receiver.zipkin "zipkin_receiver" {
  output {
    traces = [otelcol.exporter.otlp.grafanacloud.input,]
  }
}

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:

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 enter 100ms.
Select Run query to search for tracing data.

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