github.com/grafana/pyroscope@v1.18.0/docs/sources/configure-client/trace-span-profiles/go-span-profiles.md (about)

     1  ---
     2  title: Span profiles with Traces to profiles for Go
     3  menuTitle: Span profiles with Traces to profiles (Go)
     4  description: Learn about and configure Span profiles with Traces to profiles in Grafana for the Go language.
     5  aliases:
     6    - /docs/pyroscope/next/configure-client/go-span-profiles/
     7    - /docs/pyroscope/latest/configure-client/go-span-profiles/
     8  weight: 100
     9  ---
    10  
    11  # Span profiles with Traces to profiles for Go
    12  
    13  Span Profiles represent a major shift in profiling methodology, enabling deeper analysis of both tracing and profiling data.
    14  Traditional continuous profiling provides an application-wide view over fixed intervals.
    15  In contrast, Span Profiles delivers focused, dynamic analysis on specific execution scopes within applications, such as individual requests or specific trace spans.
    16  
    17  This shift enables a more granular view of performance, enhancing the utility of profiles by linking them directly with traces for a comprehensive understanding of application behavior. As a result, engineering teams can more efficiently identify and address performance bottlenecks.
    18  
    19  To learn more about Span Profiles, refer to [Combining tracing and profiling for enhanced observability: Introducing Span Profiles](/blog/2024/02/06/combining-tracing-and-profiling-for-enhanced-observability-introducing-span-profiles/).
    20  
    21  ![span-profiles screenshot](https://grafana.com/static/img/docs/tempo/profiles/tempo-profiles-Span-link-profile-data-source.png)
    22  
    23  Pyroscope can integrate with distributed tracing systems supporting the [**OpenTelemetry**](https://opentelemetry.io/docs/instrumentation/go/getting-started/) standard.
    24  This integration lets you link traces with the profiling data and find resource usage for specific lines of code for your trace spans.
    25  
    26  {{% admonition type="note"%}}
    27  * Only CPU profiling is supported.
    28  * Because of how sampling profilers work, spans shorter than the sample interval may not be captured. Go CPU profiler probes stack traces 100 times per second, meaning that spans shorter than 10ms may not be captured.
    29  {{% /admonition %}}
    30  
    31  To use Span Profiles, you need to:
    32  
    33  * [Configure Pyroscope to send profiling data](../../)
    34  * Configure a client-side package to link traces and profiles: [Go](https://github.com/grafana/otel-profiling-go)
    35  * [Configure the Tempo data source in Grafana or Grafana Cloud to discover linked traces and profiles](/docs/grafana-cloud/connect-externally-hosted/data-sources/tempo/configure-tempo-data-source/)
    36  
    37  ## Before you begin
    38  
    39  Your applications must be instrumented for profiling and tracing before you can use span profiles.
    40  
    41  * Profiling: Your application must be instrumented with Pyroscope's Go SDK. If you haven't done this yet, please refer to the [Go (push mode)](../../language-sdks/go_push/) guide.
    42  * Tracing: Your application must be instrumented with OpenTelemetry traces. If you haven't done this yet, please refer to the [OpenTelemetry](https://opentelemetry.io/docs/languages/go/getting-started/) guide.
    43  
    44  ## Configure the `otel-profiling-go` package
    45  
    46  To start collecting Span Profiles for your Go application, you need to include the [`otel-profiling-go`](https://github.com/pyroscope-io/otel-profiling-go) package in your code.
    47  
    48  This package is a `TracerProvider` implementation that labels profiling data with span IDs. This makes it possible to query for span-specific profiling data with a Tempo data source configured in Grafana or Grafana Cloud.
    49  
    50  ```shell
    51  # Make sure you also upgrade pyroscope server to version 0.14.0 or higher.
    52  go get github.com/grafana/otel-profiling-go
    53  ```
    54  
    55  Next, you need to create and configure the tracer provider:
    56  
    57  ```go
    58  package main
    59  
    60  import (
    61  	otelpyroscope "github.com/grafana/otel-profiling-go"
    62  	"github.com/grafana/pyroscope-go"
    63  )
    64  
    65  func main() {
    66  	// Initialize your tracer provider as usual.
    67  	tp := initTracer()
    68  
    69  	// Wrap it with otelpyroscope tracer provider.
    70  	otel.SetTracerProvider(otelpyroscope.NewTracerProvider(tp))
    71  
    72  	// If you're using Pyroscope Go SDK, initialize pyroscope profiler.
    73  	_, _ = pyroscope.Start(pyroscope.Config{
    74  		ApplicationName: "my-service",
    75  		ServerAddress:   "http://localhost:4040",
    76  	})
    77  
    78  	// Your code goes here.
    79  }
    80  ```
    81  
    82  Now that you set up the tracer, you can create a new trace from anywhere and the profiler automatically captures profiles for it.
    83  ```go
    84  ctx, span := otel.Tracer("tracerName").Start(ctx, "ExampleSpan")
    85  defer span.End()
    86  
    87  // Your code goes here.
    88  ```
    89  
    90  ## View the span profiles in Grafana or Grafana Cloud
    91  
    92  To view the span profiles in Grafana Tempo, you need to have a Grafana instance with a Tempo data source configured to link trace spans and profiles.
    93  Refer to the configuration documentation for [Grafana](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/configure-tempo-data-source) or [Grafana Cloud](/docs/grafana-cloud/connect-externally-hosted/data-sources/tempo/configure-tempo-data-source).
    94  
    95  To learn how to set up Traces to profiles and view the span profiles, refer to [Traces to profiles](../../../view-and-analyze-profile-data/traces-to-profiles/).
    96  
    97  
    98  ## Examples
    99  
   100  Check out the [examples](https://github.com/grafana/pyroscope/tree/main/examples/tracing/golang-push) directory for a complete demo application that shows tracing integration features.
   101  
   102  <!-- ## Using tracing exemplars manually
   103  
   104  If you're not using open telemetry integration you can still use exemplars storage to store profiles associated with some execution context (e.g. individual HTTP / GRPC request). To create exemplars you need to tag specific parts of your code with a special `profile_id` tag, for example, in golang you could do this:
   105  ```golang
   106  pprof.Do(ctx, pprof.Labels("profile_id", "8474e98b95013e4f"), func(ctx context.Context) {
   107    slowRequest()
   108  })
   109  ```
   110  
   111  `"8474e98b95013e4f"` can be any ID that you use to identify execution contexts (individual HTTP / GRPC requests). -->