Pyroscope GitHub integration

The Grafana Pyroscope GitHub integration offers seamless integration between your 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 for the integration for code written in Go. For information on profile types and the profiles available with Go, refer to Understand profiling types and their uses in Cloud Profiles.

Note
This integration is available only in Grafana Cloud.

How it works

The Pyroscope GitHub integration uses labels configured in the application being profiled to associate profiles with source code. The integration is only available for Go applications. The Go profiler can map symbolic information, such as function names and line numbers, to source code.

The Pyroscope GitHub integration uses three labels, service_repository, service_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 integration for GitHub, you need an application that emits profiling data, a GitHub account, and a Grafana Cloud account with a Grafana Pyroscope data source.

Application with profiling data requirements

A Go application which is profiled by Pyroscope
- Applications in other languages aren’t supported
- eBPF profiled workloads aren’t supported

Your Go 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, you need to add at least the two mandatory labels when sending profiles: service_repository and service_ref. They should respectively be set to the full repository GitHub URL and the current git ref.

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
  })

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.

Grafana Cloud requirements

A Grafana Cloud account
A Grafana instance with a configured Pyroscope data source. Refer to Configure Pyroscope data source for information.

Enable the Pyroscope GitHub integration

During the private preview, contact Grafana Support to request access to this feature.

Enable this capability in Grafana from the Explore > Profiles > Settings.

Select the toggle for Enable function details to activate. The toggle appears blue with a check mark.

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 GitHub integration from your GitHub account

The Pyroscope GitHub integration 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 GitHub 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 integration, you see more details in the Function Details from flame graphs in Explore Profiles.

Open a browser to your Pyroscope instance.
Sign in to your account, if prompted.
After the Grafana instance loads, select Explore.
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 provide 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.