Menu

This is documentation for the next version of Grafana Tempo documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Tempobreadcrumb arrow Set up for tracingbreadcrumb arrow Instrument for tracingbreadcrumb arrow Set up instrumentation
Open source

Set up instrumentation

Client instrumentation is the first building block to a functioning distributed tracing visualization pipeline. Client instrumentation is the process of adding instrumentation points in the application that create and offload spans.

When you set up instrumentation, you:

  1. Choose an instrumentation method to use with your application
  2. Instrument your application to generate traces

After you set up instrumentation, you can set up a collector to receive traces from your application. Refer to About instrumentation for more information about instrumentation and how it works.

Choose an instrumentation method

When sending traces to Tempo, you can choose between four methods:

  • Auto-instrumentation applies instrumentation automatically using agents or middleware, without code changes.
  • Zero-code instrumentation, which uses eBPF technology to instrument applications without code changes. Grafana Beyla is an example of a zero-code instrumentation tool.
  • Manual instrumentation involves adding code to create spans and traces, giving full control over collected data.
  • Hybrid instrumentation, which combines auto and manual instrumentation, using automatic for most code and manual for custom tracing logic.

Refer to About instrumentation for more information.

If you are using OTel or Alloy, refer to Instrument an application with OpenTelemetry for more information. These instructions are specific to Grafana Cloud, but can be adapted for self-hosted Tempo.

Instrument your app

Most of the popular client instrumentation frameworks have SDKs in the most commonly used programming languages. You should pick one according to your application needs.

OpenTelemetry has the most active development in the community and may be a better long-term choice.

Popular instrumentation frameworks include:

Instrument using OpenTelemetry

A collection of tools, APIs, and SDKs, OpenTelemetry helps engineers instrument, generate, collect, and export telemetry data such as metrics, logs, and traces, to analyze software performance and behavior. For more information refer to OpenTelemetry overview.

If you are using OTel with Grafana Cloud, refer to Instrument an application with OpenTelemetry for more information.

Use OpenTelemetry auto-instrumentation frameworks

OpenTelemetry provides auto-instrumentation agents and libraries of Java, .NET, Python, Go, and JavaScript applications, among others. For more information, refer for the OpenTelemetry Instrumentation documentation.

These libraries capture telemetry information from a client application with minimal manual instrumentation of the codebase.

Note

Jaeger client libraries have been deprecated. For more information, refer to the Deprecating Jaeger clients article. Jaeger recommends using OpenTelemetry SDKs.

Additional OTel resources

Instrument with Zipkin auto-instrumentation

Zipkin is a distributed tracing system that helps gather timing data needed to troubleshoot latency problems in microservice architectures.

Refer to the Zipkin Language Specific Instrumentation documentation for more information.

If you are using Zipkin with Alloy, refer to the Zipkin receiver, otelcol.receiver.zipkin documentation.

In addition, you can use Zipkin to instrument a library, refer to Instrumenting a library with Zipkin

Within Grafana, you can also use these Zipkin specific features:

Instrument with Grafana Beyla

Grafana Beyla is an eBPF-based application zero-code instrumentation tool to easily get started with Application Observability. Beyla uses eBPF to automatically inspect application executables and the OS networking layer, and capture trace spans related to web transactions and Rate Errors Duration (RED) metrics for Linux HTTP/S and gRPC services. All data capture occurs without any modifications to application code or configuration.

Refer to Set up Beyla for information about how to instrument using Beyla.

Community resources

Next steps

After you set up instrumentation, you can set up a collector to receive traces from your application.