View and analyze profile data on Grafana Labs

Use Profiles Drilldown to investigate issues

Wed, 08 Apr 2026 14:38:28 +0000

Use Profiles Drilldown to investigate issues

Note
Profiles Drilldown is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

Grafana Profiles Drilldown is designed to make it easy to visualize and analyze profiling data. There are several different modes for viewing, analyzing, and comparing profiling data.

The main use cases are the following:

Proactive: Cutting costs, addressing latency issues, or optimizing memory usage for applications
Reactive: Resolving incidents with line-level accuracy or debugging active latency/memory issues

Profiles Drilldown provides an intuitive interface to specifically support these use cases. You get a holistic view of all of your services and how they’re functioning, but also the ability to drill down for more targeted root cause analysis.

Profiles Drilldown offers a convenient platform to analyze profiles and get insights that are impossible to get from using other traditional signals like logs, metrics, or tracing.

Give it a try using Grafana Play

With Grafana Play, you can explore and see how it works, learning from practical examples to accelerate your development. This feature can be seen on the Grafana Play site.

Try it

Continuous profiling

While code profiling has been a long-standing practice, continuous profiling represents a modern and more advanced approach to performance monitoring.

This technique adds two critical dimensions to traditional profiles:

Time: Profiling data is collected continuously, providing a time-centric view that allows querying performance data from any point in the past.
Metadata: Metadata enriches profiling data, adding contextual depth to the performance data.

These dimensions, coupled with the detailed nature of performance profiles, make continuous profiling a uniquely valuable tool.

Flame graphs

Flame graphs help you visualize resource allocation and performance bottlenecks, and you even get suggested recommendations and performance fixes via AI-driven flame graph analysis, as well as line-level insights from our GitHub integration.

On views with a flame graph, you can use Explain flame graph to provide an AI flame graph analysis that explains the performance bottleneck, root cause, and recommended fix. For more information, refer to Flame graph AI.

Use the Pyroscope UI to explore profiling data

Wed, 08 Apr 2026 14:38:28 +0000

Use the Pyroscope UI to explore profiling data

Pyroscope’s UI is designed to make it easy to visualize and analyze profiling data. There are several different modes for viewing, analyzing, uploading, and comparing profiling data.

The Pyroscope UI is only available with Pyroscope open source. In Grafana and Grafana Cloud, you can use Profiles Drilldown to inspect your profiling data.

While code profiling has been a long-standing practice, continuous profiling represents a modern and more advanced approach to performance monitoring. This technique adds two critical dimensions to traditional profiles:

Time: Profiling data is collected continuously, providing a time-centric view that allows querying performance data from any point in the past.
Metadata: Profiles are enriched with metadata, adding contextual depth to the performance data.

These dimensions, coupled with the detailed nature of performance profiles, make continuous profiling a uniquely valuable tool. Pyroscope’s UI enhances this further by offering a convenient platform to analyze profiles and get insights that are impossible to get from using other traditional signals like logs, metrics, or tracing.

In this UI reference, you’ll learn how Pyroscope parallels these other modern observability tools by providing a Prometheus-like querying experience. More importantly, you’ll learn how to use Pyroscope’s extensive UI features for a deeper insight into your application’s performance.

Key features of the Pyroscope UI

The following sections describe Pyroscope UI capabilities.

Tag Explorer

The Tag Explorer page lets you navigate and analyze performance data through tags and labels. This feature is crucial for identifying performance anomalies and understanding the behavior of different application segments under various conditions. Pyroscope intentionally doesn’t include a query language on this page.

To use the Tag Explorer:

Select a tag to view the corresponding profiling data.
Analyze the pie chart and the table of descriptive statistics to determine which tags if any are behaving abnormally.
Select a tag to view the corresponding profiling data.
Make use of the shortcuts to the Single, Comparison, and Diff View pages to further identify the root cause of the performance issue.

Single view

The Single View page in Pyroscope’s UI is built for in-depth profile analysis. Here, you can explore a single flame graph with multiple viewing options and functionalities:

Table view: Breaks down the profiling data into a sortable table format. Selecting Top Table displays the table and hides the flame graph.
Sandwich view: Displays both the callers and callees for a selected function, offering a comprehensive view of function interactions. Access by clicking in the flame graph and selecting Sandwhich view.
Flame Graph view: Visualizes profiling data in a flame graph format, allowing easy identification of resource-intensive functions. Selecting Flame Graph displays the flame graph and hides the table.
Both view: Displays both the table and the flame graph. This is the default view for Single View.
Export Data: Options to export the flame graph for offline analysis or share it via a flamegraph.com link for collaborative review.

This screenshot shows a spike in CPU usage. Without profiling, you would go from a spike CPU usage metric to digging through code or guessing the cause. However, with profiling, you can use the flame graph and table to see exactly which function is most responsible for the spike. Often, this shows up as a single node taking up a noticeably disproportionate width in the flame graph as seen below with the checkDriverAvailability function.

However, in some instances it may be a function that’s called many times and is taking up a large amount of space in the flame graph. In this case, you can use the sandwich view to see that a logging function called throughout many functions in the codebase is the culprit.

Comparison view

The Comparison view facilitates side-by-side comparison of profiles either based on different label sets, different time periods, or both. This feature is valuable for understanding the impact of changes or differences between two distinct queries of your application.

You can use Comparison view to compare different time ranges whether or not the labels are the same. For example, in investigating the cause of a memory leak, the timeline might show a steadily increasing amount of memory allocations over time. You can use the Comparison view to compare the memory allocations between two different time periods where allocations were low and where allocations were high. This information helps you identify the function that’s causing the memory leak.

To run a comparison:

Select two different sets of labels (for example, env:production vs. env:development) and or time periods, reflected by the sub-timelines above each flame graph.
View the resulting flame graphs side by side to identify disparities in performance.

There are many practical use cases for comparison for companies using Pyroscope. Some examples of labels below expressed as label:value are:

Feature flags: Compare application performance with feature_flag:a vs. feature_flag:b
Deployment environments: Contrast env:production vs. env:development
Release analysis: Examine commit:release-1 vs. commit:release-2
Region: Compare region:us-east-1 vs. region:us-west-1

Diff page: Identify changes with differential analysis

The Diff page is an extension of the comparison page, crucial for more easily visually showing the differences between two profiling data sets. It normalizes the data by comparing the percentage of total time spent in each function so that the resulting flame graph is comparing the share of time spent in each function rather than the absolute amount of time spent in each function. This is important because it allows you to compare two different queries that may have different total amounts of time spent in each function.

Similar to a git diff, it takes the flame graphs from the comparison page and highlights the differences between the two flame graphs where red represents an increase in CPU usage from the baseline to the comparison and green represents a decrease.

Understand 'self' vs. 'total' metrics in profiling with Pyroscope

Wed, 08 Apr 2026 14:38:28 +0000

Understand ‘self’ vs. ’total’ metrics in profiling with Pyroscope

Profiling in Pyroscope provides many different ways of analyzing your profiling data. One of the key pieces of this analysis are the metrics ‘self’ and ’total’, whose understanding is key for accurate interpretation of profiling data in both CPU and memory contexts. These metrics can be seen both within the table and the flame graph view of the UI.

Self

‘Self’ refers to the resource usage (CPU time, memory allocation, etc.) directly attributed to a specific function or a code segment, excluding the resources used by its sub-functions or calls

This metric helps isolate the direct impact of a specific code block, making it crucial for pinpointing primary resource consumers

Total

‘Total’ encompasses the combined resource usage of a function along with all the functions it calls

It provides a holistic view of a function’s overall resource consumption, essential for understanding cumulative impacts

‘Self’ and ‘Total’ in CPU profiling

In CPU profiling, ‘self’ indicates the CPU time consumed directly by the function, crucial for identifying functions with high CPU demand.

The ’total’ CPU time includes time spent in the function itself plus time in all called functions, highlighting comprehensive CPU usage

The example below demonstrates a simplified pseudocode representation of a CPU-intensive process. This illustrates how ‘self’ and ’total’ time would be calculated for different functions in a typical application. The following diagram provides a visual representation of these concepts.

def handle_request():
    # Root function representing the total request handling process
    parse_json()
    process_data()

def parse_json():
    # Function for parsing JSON data
    validate()

def validate():
    # Function for validating the parsed JSON schema
    # Schema validation logic

def process_data():
    # Function for processing data
    apply()

def apply():
    # Function for applying transformations to data
    # Transformation logic

# Simulate a request handling
handle_request()

‘Self’ and ‘Total’ in memory profiling

Self in Memory: For memory profiling, ‘self’ measures the memory allocated by the function itself, vital for detecting direct memory allocation issues.
Total in Memory: ‘Total’ memory includes allocations by the function and it’s called functions, essential for assessing overall memory footprint.

The same example from the CPU profiling section can be used to illustrate the concepts of ‘self’ and ’total’ in memory profiling, just with memory units instead of CPU.

Conclusion

Grasping the distinction between ‘self’ and ’total’ metrics is fundamental for effective performance analysis in Pyroscope. Whether in CPU or memory profiling (or any other type), these metrics provide value insights for optimizing applications and enhancing their efficiency and reliability.

Profile CLI

Wed, 08 Apr 2026 14:38:28 +0000

Profile CLI

Pyroscope provides a command-line interface (CLI), profilecli. This utility enables various productivity flows such as:

Interacting with a running Pyroscope server to upload profiles, query data, and more
Inspecting Parquet files

Tip
Use the help command (profilecli help) for a full list of capabilities and help information.

Install Profile CLI

You can install Profile CLI using a package or by compiling the code.

Install using a package

On macOS, you can install Profile CLI using HomeBrew:

brew install pyroscope-io/brew/profilecli

For other platforms, you can manually download the profilecli release asset for your operating system and architecture and make it executable.

For example, for Linux with the AMD64 architecture:

Download and extract the package (archive).

curl -fL https://github.com/grafana/pyroscope/releases/download/v1.13.2/profilecli_1.13.2_linux_amd64.tar.gz | tar xvz

Make profilecli executable:
Bash
```
chmod +x profilecli
```
Optional: Make profilecli reachable from anywhere:
Bash
```
sudo mv profilecli /usr/local/bin
```

Build from source code

To build from source code, you must have:

Go installed (> 1.19).
Either $GOPATH or $GOBIN configured and added to your PATH environment variable.

To build the source code:

Clone the repository.

git clone git@github.com:grafana/pyroscope.git

Run the Go install command to build and install the package.
Bash
```
cd pyroscope
go install ./cmd/profilecli
```
The command places the profilecli executable in $GOPATH/bin/ (or $GOBIN/) and make it available to use.

Common flags and environment variables

The profilecli commands that interact with a Pyroscope server require a server URL and optionally authentication details. These can be provided as command-line flags or environment variables.

Server URL

default: http://localhost:4040

The --url flag specifies the server against which the command will run. If using Grafana Cloud, an example URL could be https://profiles-prod-001.grafana.net. For local instances, the URL could look like http://localhost:4040.
Authentication details.

default: <empty>

If using Grafana Cloud or authentication is enabled on your Pyroscope server, you will need to provide a username and password using the --username and --password flags respectively. For Grafana Cloud, the username will be the Stack ID and the password the generated API token.

Environment variable naming

You can use environment variables to avoid passing flags to the command every time you use it, or to protect sensitive information. Environment variables have a PROFILECLI_ prefix. Here is an example of providing the server URL and credentials for the profilecli tool:

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>
# now we can run a profilecli command without specifying the url or credentials:
profilecli <command>

Caution
If you’re querying data from Cloud Profiles, be sure to use the url of your Cloud Profiles server in PROFILECLI_URL (e.g. https://profiles-prod-001.grafana.net) and not the url of your Grafana Cloud tenant (e.g. <your tenant>.grafana.net).

Upload a profile to a Pyroscope server using `profilecli`

Using profilecli streamlines the process of uploading profiles to Pyroscope, making it a convenient alternative to manual HTTP requests.

Before you begin

Ensure you have profilecli installed on your system by following the installation steps above.
Have a profile file ready for upload. Note that you can only upload pprof files at this time.

Upload steps

Identify the pprof file.
- Path to your pprof file: path/to/your/pprof-file.pprof
Optional: Specify any extra labels.
- You can add additional labels to your uploaded profile using the --extra-labels flag.
- You can provide the name of the application that the profile was captured from via the service_name label (defaults to profilecli-upload). This will be useful when querying the data via profilecli or the UI.
- You can use the flag multiple times to add several labels.

Construct and execute the Upload command.

Here’s a basic command template:

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>

profilecli upload --extra-labels=<label_name>=<label_value> <pprof_file_path>

Example command:

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli upload path/to/your/pprof-file.pprof

Example command with extra labels:

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli upload \
    --extra-labels=service_name=my_application_name \
    --extra-labels=cluster=us-east \
    path/to/your/pprof-file.pprof

Check for successful upload.
- After running the command, you should see a confirmation message indicating a successful upload. If there are any issues, profilecli provides error messages to help you troubleshoot.

Query a Pyroscope server using `profilecli`

You can use the profilecli query command to look up the available profiles on a Pyroscope server and read actual profile data. This can be useful for debugging purposes or for integrating profiling in CI pipelines (for example to facilitate profile-guided optimization).

Look up available profiles on a Pyroscope server

You can use the profilecli query series command to look up the available profiles on a Pyroscope server. By default, it queries the last hour of data, though this can be controlled with the --from and --to flags. You can narrow the results down with the --query flag. See profilecli help query series for more information.

Query series steps

Optional: Specify a query and a time range.
- You can provide a label selector using the --query flag, for example: --query='{service_name="my_application_name"}'.
- You can provide a custom time range using the --from and --to flags, for example, --from="now-3h" --to="now".

Construct and execute the Query Series command.

Here’s a basic command template:

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>

profilecli query series --query='{<label_name>="<label_value>"}'

Example command:

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli query series --query='{service_name="my_application_name"}'

Example output:

{
    "__name__":"memory",
    "__period_type__":"space",
    "__period_unit__":"bytes",
    "__profile_type__":"memory:inuse_objects:count:space:bytes",
    "__service_name__":"my_application_name",
    "__type__":"inuse_objects",
    "__unit__":"count",
    "cluster":"eu-west-1",
    "service_name":"my_application_name"
 }

Read a raw profile from a Pyroscope server

You can use the profilecli query profile command to retrieve a merged (aggregated) profile from a Pyroscope server. The command merges all samples found in the profile store for the specified query and time range. By default it looks for samples within the last hour, though this can be controlled with the --from and --to flags. The source data can be narrowed down with the --query flag in the same way as with the series command.

Query profile steps

Specify optional flags.
- You can provide a label selector using the --query flag, for example, --query='{service_name="my_application_name"}'.
- You can provide a custom time range using the --from and --to flags, for example, --from="now-3h" --to="now".
- You can specify the profile type via the --profile-type flag. The available profile types are listed in the output of the profilecli query series command.

Construct and execute the query profile command.

Here’s a basic command template:

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>

profilecli query profile \
    --profile-type=<profile_type> \
    --query='{<label_name>="<label_value>"}' \
    --from="<from>" --to="<to>"

Example command:

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli query profile \
    --profile-type=memory:inuse_space:bytes:space:bytes \
    --query='{service_name="my_application_name"}' \
    --from="now-1h" --to="now"

Example output:

level=info msg="query aggregated profile from profile store" url=http://localhost:4040 from=2023-12-11T13:38:33.115683-04:00 to=2023-12-11T14:38:33.115684-04:00 query={} type=memory:inuse_space:bytes:space:bytes
PeriodType: space bytes
Period: 524288
Time: 2023-12-11 13:59:59.999 -0400 AST
Duration: 59m5
Samples:
inuse_space/bytes[dflt]
  115366240: 107 13 14 15 16 17 1 2 3
...

Export a profile for Go PGO

You can use the profilecli query go-pgo command to retrieve an aggregated profile from a Pyroscope server for use with Go PGO. Profiles retrieved with profilecli query profile include all samples found in the profile store, resulting in a large profile size. The profile size may cause issues with network transfer and slow down the PGO process. In contrast, profiles retrieved with profilecli query go-pgo include only the information used in Go PGO, making them significantly smaller and more efficient to handle. By default, it looks for samples within the last hour, though this can be controlled with the --from and --to flags. The source data can be narrowed down with the --query flag in the same way as with the query command.

Specify optional flags.
- You can provide a label selector using the --query flag, for example, --query='{service_name="my_application_name"}'.
- You can provide a custom time range using the --from and --to flags, for example, --from="now-3h" --to="now".
- You can specify the profile type via the --profile-type flag. The available profile types are listed in the output of the profilecli query series command.
- You can specify the number of leaf locations to keep via the --keep-locations flag. The default value is 5. The Go compiler does not use the full stack trace. Reducing the number helps to minimize the profile size.
- You can control whether to use callee aggregation with the --aggregate-callees flag. By default, this option is enabled, meaning samples are aggregated based on the leaf location, disregarding the callee line number, which the Go compiler does not utilize. To disable aggregation, use the --no-aggregate-callees flag.

Construct and execute the command.

Example command:

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli query go-pgo \
    --query='{service_name="my_service"}' \
    --from="now-1h" --to="now"

Example output:

level=info msg="querying pprof profile for Go PGO" url=https://localhost:4040 query="{service_name=\"my_service\"}" from=2024-06-20T12:32:20+08:00 to=2024-06-20T15:24:40+08:00 type=process_cpu:cpu:nanoseconds:cpu:nanoseconds output="pprof=default.pgo" keep-locations=5 aggregate-callees=true
# By default, the profile is saved to the current directory as `default.pgo`

Traces to profiles

Wed, 08 Apr 2026 14:38:28 +0000

Traces to profiles

Note
Your application must be instrumented for profiles and traces. For more information, refer to Link traces to profiles.

Using Trace to profiles, you can use Grafana’s ability to correlate different signals by adding the functionality to link between traces and profiles.

Trace to profiles lets you link your Grafana Pyroscope data source to tracing data. When configured, this connection lets you run queries from a trace span into the profile data using Explore. Each span links to your queries. Clicking a link runs the query in a split panel. If tags are configured, Grafana dynamically inserts the span attribute values into the query. The query runs over the time range of the (span start time - 60) to (span end time + 60 seconds).

Embedded flame graphs are also inserted into each span details section that has a linked profile. This lets you see resource consumption in a flame graph visualization for each span without having to navigate away from the current view.

There are two ways to configure the trace to profiles feature:

Use a basic configuration with default query, or
Configure a custom query where you can use a template language to interpolate variables from the trace or span.

Before you begin

Traces to profile requires a Tempo data source with Traces to profiles configured and a Grafana Pyroscope data source.

As with traces, your application needs to be instrumented to emit profiling data. For more information, refer to Linking tracing and profiling with span profiles.

Use a basic configuration

To use a basic configuration, follow these steps:

In the left menu, select Connections > Data sources.
Select your configured Tempo data source from the Data source list.
Scroll down to the Traces to profiles section.
Select a Pyroscope data source in the Data source drop-down.
Optional: Add one or more tags to use in the query. If left blank, the default values of service.name and service.namespace are used.

The tags you configure must be present in the spans attributes or resources for a trace-to-profiles span link to appear.

You can optionally configure a new name for the tag. This is useful if the tag has dots in the name and the target data source doesn’t allow dots in labels. In that case, you can remap service.name to service_name.
Select one or more profile types to use in the query. Select the drop-down and choose options from the menu.

The profile type or app must be selected for the query to be valid. Grafana doesn’t show any data if the profile type or app isn’t selected when a query runs.
Select Save and Test.

If you have configured a Pyroscope data source and no profile data is available or the Profiles for this span button and the embedded flame graph isn’t visible, verify that the pyroscope.profile.id key-value pair exists in your span tags.

Configure a custom query

To use a custom query with the configuration, follow these steps:

In the left menu, select Connections > Data sources.
Select a configured Tempo data source from the Data source list.
Scroll down to the Traces to profiles section.
Select a Pyroscope data source in the Data source drop-down.
Optional: Choose any tags to use in the query. If left blank, the default values of service.name and service.namespace are used.

These tags can be used in the custom query with ${__tags} variable. This variable interpolates the mapped tags as list in an appropriate syntax for the data source. Only tags present in the span are included. Tags that aren’t present are omitted.

You can also configure a name for the tag. Tag names are useful where the tag has dots in the name and the target data source doesn’t allow using dots in labels. For example, you can remap service.name to service_name. If you don’t map any tags here, you can still use any tag in the query, for example: method="${__span.tags.method}". Learn more about custom query variables.
Select one or more profile types to use in the query. Select the drop-down and choose options from the menu.
Switch on Use custom query to enter a custom query.
Specify a custom query to be used to query profile data. You can use various variables to make that query relevant for current span. The link shows only if all the variables are interpolated with non-empty values to prevent creating an invalid query. You can interpolate the configured tags using the $__tags keyword.
Select Save and Test.

Configuration options

The following table describes options for configuring your Trace to profiles settings:

Setting name	Description
Data source	Defines the target data source. You can select a Pyroscope [profiling] data source.
Tags	Defines the tags to use in the profile query. Default: `cluster`, `hostname`, `namespace`, `pod`, `service.name`, `service.namespace`. You can change the tag name for example to remove dots from the name if they’re not allowed in the target data source. For example, map `http.status` to `http_status`.
Profile type	Defines the profile type that used in the query.
Use custom query	Toggles use of custom query with interpolation.
Query	Input to write custom query. Use variable interpolation to customize it with variables from span.

Integrate your source code on GitHub with Pyroscope profiling data.

Wed, 08 Apr 2026 14:38:28 +0000

Integrate your source code on GitHub with Pyroscope profiling data.

The Grafana Pyroscope source code integration offers seamless integration between your GitHub code repositories and Grafana. Using this app, you can map your code directly within Grafana and visualize resource performance line by line. With these powerful capabilities, you can gain deep insights into your code’s execution and identify performance bottlenecks.

Every profile type works with the integration for code written in Go, Java, and Python.

For information on profile types and the profiles available with Go, Java, and Python, refer to Profiling types and their uses.

How it works

The Pyroscope source code integration uses labels configured in the application being profiled to associate profiles with source code. The integration is available for Go, Java, and Python applications.

The Pyroscope source code integration uses three labels, service_repository, service_git_ref, and service_root_path, to add commit information, repository link, and an enhanced source code preview to the Function Details screen.

Note
The source code mapping is only available to people who have access to the source code in GitHub.

Before you begin

To use the Pyroscope source code integration with GitHub, you need an application that emits profiling data, a GitHub account, and a Grafana instance with a Grafana Pyroscope backend.

Application with profiling data requirements

Warning

Applications in other languages aren’t supported

A Go application which is profiled by Grafana Alloy’s pyroscope.scrape, pyroscope.ebpf (Alloy v1.11.0+), or using the Go Push SDK.
A Java application which is profiled by Grafana Alloy’s pyroscope.java, pyroscope.ebpf (Alloy v1.11.0+), or using the Java SDK. For Java applications, a committed .pyroscope.yaml file is required to map package names to source code locations (see Advanced source code mapping with .pyroscope.yaml).
A Python application which is profiled by Grafana Alloy’s pyroscope.ebpf (Alloy v1.11.0+) or using the Python SDK.

Your application provides the following labels (tags):

service_git_ref points to the Git commit or reference from which the binary was built
service_repository is the GitHub repository that hosts the source code
service_root_path (Optional) is the path where the code lives inside the repository

To activate this integration, add at least the two mandatory labels when sending profiles: service_repository and service_git_ref. Set them to the full repository GitHub URL and the current git ref respectively.

For example, using the Go SDK you can set these labels as tags in the configuration:

pyroscope.Start(pyroscope.Config{
    Tags: map[string]string{
      "service_git_ref":    "<GIT_REF>",
      "service_repository": "https://github.com/<YOUR_ORG>/<YOUR_REPOSITORY>",
      "service_root_path": "<PATH_TO_SERVICE_ROOT>", // optional
    },
    // Other configuration
  })

You can also override these values directly in the UI by clicking the edit button next to the repository information in the Function Details panel. This is useful for testing new configurations before deploying label changes, or for quickly setting up source code viewing during an incident.

GitHub requirements

A GitHub account
Source code hosted on GitHub

Note
Data from your GitHub repository may be limited if your GitHub organization or repository restricts third-party applications. For example, the organization may need to add this app to an allowlist to access organizational resources. Contact your organization administrator for assistance. Refer to Requesting a GitHub App from your organization owner.

Ensure the source code integration is configured in Grafana Pyroscope

Refer to Configure Pyroscope source code integration on the steps required.

Ensure the Grafana Pyroscope data source is configured correctly

In order to make use of the GitHub integration, the Pyroscope data source needs to be configured to pass a particular cookie through.

To configure cookie passthrough in Grafana:

Navigate to Configuration > Data sources in Grafana.
Select your Pyroscope data source.
Under Additional settings > Advanced HTTP settings , locate Allowed cookies.
Add pyroscope_git_session to the list of cookies to forward.
Click Save & test to apply the changes.

Note
Cookie forwarding must be enabled for the source code integration to work properly. Without it, you won’t be able to connect to GitHub repositories from within Grafana Profiles Drilldown.

Authorize access to GitHub

You can authorize with GitHub using the Connect to GitHub in the Function Details panel.

From within Single view with a configured Pyroscope app plugin.
Select Pyroscope service. For this example, select cpu_profile.
Click in the flame graph on a function you want to explore. Select Function details.
On Function Details, locate the Repository field and select Connect to <GITHUB REPOSITORY>, where <GITHUB REPOSITORY> is replaced with the repository name where the files reside. In this case, it’s connecting to the grafana/pyroscope repository.
If prompted, log in to GitHub.
After Grafana connects to your GitHub account, review the permissions and select Authorize Grafana Pyroscope.

Note
Organization owners may disallow third-party apps for the entire organization or specific organization resources, like repositories. If this is the case, you won’t be able authorize the Grafana Pyroscope GitHub integration to view source code or commit information for the protected resources.

Modify or remove the Pyroscope source code integration from your GitHub account

The Pyroscope source code integration for GitHub uses a GitHub app called “Grafana Pyroscope” to connect to GitHub. This application authorizes Grafana Cloud to access source code and commit information.

After authorizing the app, your GitHub account, GitHub > Settings > Applications lists the Grafana Pyroscope app.

You can change the repositories the Pyroscope source code integration can access on the Applications page.

You can use also remove the app’s permissions by selecting Revoke. Revoking the permissions disables the integration in your Grafana Cloud account.

For more information about GitHub applications:

How your GitHub code shows up in profile data queries

After authorizing the Pyroscope Grafana source code integration, you see more details in the Function Details from flame graphs in Profiles Drilldown.

Open a browser to your Pyroscope instance.
Sign in to your account, if prompted.
After the Grafana instance loads, select Drilldown.
Next, select Profiles > Single view from the left-side menu.
Optional: Select a Service and Profile.
Click in the flame graph and select Function details from the pop-up menu.

Function Details

The Function Details section provides information about the function you selected from the flame graph.

The table explains the main fields in the table. The values for some of the fields, such as Self and Total, change depending whether a profile uses time or memory amount. Refer to Understand Self versus Total metrics in profiling with Pyroscope for more information.

Field	Meaning	Notes
Function name	The name of the selected function
Start time	The line where the function definition starts
File	Path where the function is defined	You can use the clipboard icon to copy the path.
Repository	The repository configured for the selected service
Commit	The version of the application (commit) where the function is defined. Use the drop-down menu to target a specific commit.	Click the Commit ID to view the commit in the repository.
Breakdown per line (table)	Provides the function location in the code and self and total values.
Self	‘Self’ refers to the resource usage (CPU time, memory allocation, etc.) directly attributed to a specific function or a code segment, excluding the resources used by its sub-functions or calls	This value can be a time or memory amount depending on the profile selected.
Total	‘Total’ encompasses the combined resource usage of a function along with all the functions it calls.	This value can be a time or memory amount depending on the profile selected.

Advanced source code mapping with `.pyroscope.yaml`

For more complex applications with multiple dependencies and external libraries, you can configure custom source code mappings using a .pyroscope.yaml configuration file in your repository. This feature enables Pyroscope to resolve and display source code from:

Multiple GitHub repositories (for example, third-party dependencies)
Different versions and branches of dependencies
Standard library code (Go, Java)
Vendor directories and local paths

How source code mapping works

When you click on a function in the flame graph, Pyroscope performs the following steps to retrieve the source code:

Load configuration: Pyroscope checks for a .pyroscope.yaml file in your service’s root path. This is determined by labels on the profiling data as mentioned in How this works.
Match file location: If a configuration file exists, the system matches the file path or function name from the profiling data against the configured mappings using a longest-prefix-match algorithm.
Resolve matched source location: If a mapping matches, Pyroscope determines whether to fetch code from:
- A local path within your repository
- An external GitHub repository at a specific version
Automatic mapping: If no configuration file exists or no mappings matched, the system tries to find the related source code using heuristics:
- Go: Detect standard library functions and go.mod dependencies
- All languages: Resolve using the file path relative to the service root
Fetch and display: The source code is retrieved and displayed in the Function Details panel with line-by-line profiling data

Supported languages

Pyroscope’s source code integration supports the following languages:

Go: Full support including standard library, Go modules, and vendor directories. Works automatically without configuration, but can be customized with .pyroscope.yaml.
Python: Full support including standard library and installed packages. Works automatically without configuration, but can be customized with .pyroscope.yaml.
Java: Requires a .pyroscope.yaml file with explicit mappings for application code and dependencies.

Note
While Go and Python work automatically, you can use a .pyroscope.yaml file to customize source mappings for any language.

Configuration file format

Create a .pyroscope.yaml file in the root of your repository (or in the path specified by service_root_path if configured) with the following structure:

version: v1                    # Config format version (currently only v1 is supported)
source_code:
  mappings:                    # Array of source-to-repository mappings
    - path:                    # Match files by path prefix (optional if function_name is specified)
        - prefix: path/to/match
        - prefix: another/path
      function_name:           # Match by function name prefix (optional if path is specified)
        - prefix: function/prefix
      language: go             # Required: "go", "java", or "python"
      source:                  # Define where to fetch the source code
        local:
          path: src/main/java  # Path relative to the location of the .pyroscope.yaml file
        # OR
        github:
          owner: organization  # GitHub repository owner
          repo: repository     # GitHub repository name
          ref: v1.0.0         # Branch, tag, or commit SHA
          path: src            # Path within the external repository

Configuration rules

Each mapping must specify either a local or github source (not both)
Multiple path or function_name prefixes can be specified per mapping (they are OR’d together)
Mappings are evaluated using longest-prefix-match (more specific mappings take precedence)
If no mapping matches, Pyroscope falls back to language-specific default behavior (automatic resolution for Go; Java requires explicit mappings)

Example: Go standard library mapping

Map the Go standard library to a specific Go version:

version: v1
source_code:
  mappings:
    - path:
        - prefix: $GOROOT/src
      language: go
      source:
        github:
          owner: golang
          repo: go
          ref: go1.24.10
          path: src

This configuration ensures that when you view standard library functions like fmt.Println or net/http.Server, Pyroscope fetches the source code from the golang/go repository at version 1.24.10.

Example: Java application with dependencies

Configure mappings for a Java Spring application:

version: v1
source_code:
  mappings:
    # Local application code
    - function_name:
        - prefix: org/example/myapp
      language: java
      source:
        local:
          path: src/main/java

    # JDK standard library
    - function_name:
        - prefix: java
        - prefix: javax
      language: java
      source:
        github:
          owner: openjdk
          repo: jdk
          ref: jdk-17+0
          path: src/java.base/share/classes

    # Spring Framework dependencies
    - function_name:
        - prefix: org/springframework/web/servlet
      language: java
      source:
        github:
          owner: spring-projects
          repo: spring-framework
          ref: v5.3.20
          path: spring-webmvc/src/main/java

    - function_name:
        - prefix: org/springframework/web
        - prefix: org/springframework/http
      language: java
      source:
        github:
          owner: spring-projects
          repo: spring-framework
          ref: v5.3.20
          path: spring-web/src/main/java

This configuration demonstrates:

Longest-prefix matching: org/springframework/web/servlet matches the more specific mapping, while org/springframework/web/client matches the less specific one
Multiple prefixes: HTTP and web packages from Spring are grouped together
Mixed sources: Local application code and external dependencies

Example: Go application with vendor dependencies

Map vendored dependencies and modules:

version: v1
source_code:
  mappings:
    # Vendor directory (for dependencies copied into your repo)
    - path:
        - prefix: vendor/
      language: go
      source:
        local:
          path: vendor

    # External dependency at specific version
    - path:
        - prefix: github.com/prometheus/client_golang
      language: go
      source:
        github:
          owner: prometheus
          repo: client_golang
          ref: v1.19.0
          path: ""

Example: Python application with dependencies

Map Python application code and external dependencies:

version: v1
source_code:
  mappings:
    # Local application code
    - path:
        - prefix: /app/src
      language: python
      source:
        local:
          path: src

    # Python standard library
    - path:
        - prefix: /usr/lib/python3.12
        - prefix: /usr/local/lib/python3.12
      language: python
      source:
        github:
          owner: python
          repo: cpython
          ref: v3.12.0
          path: Lib

    # External package (requests)
    - path:
        - prefix: /usr/local/lib/python3.12/site-packages/requests
      language: python
      source:
        github:
          owner: psf
          repo: requests
          ref: v2.31.0
          path: src/requests

This configuration demonstrates:

Local application code: Maps your application’s source directory
Standard library: Maps Python standard library paths to the CPython repository
External packages: Maps third-party packages to their GitHub repositories

Language-specific behavior

Go

For Go applications, Pyroscope provides intelligent fallback behavior even without a .pyroscope.yaml file:

Standard library: Automatically detected and mapped to the appropriate golang/go repository version
Go modules: Parsed from go.mod in your repository, with automatic version resolution
Vanity URLs: Resolved to canonical repositories (for example, gopkg.in, google.golang.org)
Vendor directories: Files in vendor/ are searched relative to repository root

The system extracts Go version information from paths like /usr/local/go/go1.24.10/src/fmt/print.go.

Java

Java applications require explicit mappings in .pyroscope.yaml:

Function name conversion: Java function names like org/example/App$Inner.method are automatically converted to org/example/App.java
No fallback: Unlike Go and Python, Java files cannot be resolved without configuration
Inner classes: Automatically handled (inner class markers are stripped)

Python

For Python applications, Pyroscope provides intelligent fallback behavior similar to Go:

Standard library: Automatically detected and mapped to the appropriate python/cpython repository version
Installed packages: Resolved from virtual environments or system packages
File paths: Direct file paths are used when available from profiling data

The system extracts Python version information from paths to map to the correct CPython repository version.

Troubleshooting

No source code displayed

Verify the .pyroscope.yaml file is in your service’s configured root path and that the root path is configured as expected
Check that the path or function_name prefixes match your profiling data
For Java applications, ensure all dependencies have mappings configured
Confirm GitHub OAuth authorization is active and hasn’t expired

Wrong version displayed

Check the ref field in your mapping points to the correct branch, tag, or commit
For Go standard library, verify the Go version in your mapping matches your application’s Go version
Use explicit commit SHAs for reproducibility

Mapping precedence issues

Pyroscope uses longest-prefix-match. If a more specific mapping isn’t being used:

Verify the prefix exactly matches the beginning of the path or function name
Check that more specific mappings are listed in the configuration (order doesn’t matter, but clarity helps)
Test with exact prefixes from your profiling data

View and analyze profile data on Grafana Labs

Use Profiles Drilldown to investigate issues

Use Profiles Drilldown to investigate issues

Give it a try using Grafana Play

Continuous profiling

Flame graphs

Use the Pyroscope UI to explore profiling data

Use the Pyroscope UI to explore profiling data

Key features of the Pyroscope UI

Tag Explorer

Single view

Comparison view

Diff page: Identify changes with differential analysis

Understand 'self' vs. 'total' metrics in profiling with Pyroscope

Understand ‘self’ vs. ’total’ metrics in profiling with Pyroscope

Self

Total

‘Self’ and ‘Total’ in CPU profiling

‘Self’ and ‘Total’ in memory profiling

Conclusion

Profile CLI

Profile CLI

Install Profile CLI

Install using a package

Build from source code

Common flags and environment variables

Environment variable naming

Upload a profile to a Pyroscope server using profilecli

Before you begin

Upload steps

Query a Pyroscope server using profilecli

Look up available profiles on a Pyroscope server

Query series steps

Read a raw profile from a Pyroscope server

Query profile steps

Export a profile for Go PGO

Traces to profiles

Traces to profiles

Before you begin

Use a basic configuration

Configure a custom query

Configuration options

Integrate your source code on GitHub with Pyroscope profiling data.

Integrate your source code on GitHub with Pyroscope profiling data.

How it works

Before you begin

Application with profiling data requirements

GitHub requirements

Ensure the source code integration is configured in Grafana Pyroscope

Ensure the Grafana Pyroscope data source is configured correctly

Authorize access to GitHub

Modify or remove the Pyroscope source code integration from your GitHub account

How your GitHub code shows up in profile data queries

Function Details

Advanced source code mapping with .pyroscope.yaml

How source code mapping works

Supported languages

Configuration file format

Configuration rules

Example: Go standard library mapping

Example: Java application with dependencies

Example: Go application with vendor dependencies

Example: Python application with dependencies

Language-specific behavior

Go

Java

Python

Troubleshooting

Upload a profile to a Pyroscope server using `profilecli`

Query a Pyroscope server using `profilecli`

Advanced source code mapping with `.pyroscope.yaml`