DocumentationGrafana CloudMonitor applicationsProfilesPyroscope GitHub integration

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.

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 two labels, service_repository and service_ref, to add commit information, repository link, and an enhanced source code preview to the Function Details screen.

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 are not supported
  • eBPF profiled workloads are not 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 the GitHub repository where the source code is hosted

To activate this integration, you need to add two new 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.

Go Copy

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

GitHub requirements

• A GitHub account
• Source code hosted on GitHub

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.

When this feature becomes generally available, you can enable it in Grafana from the Explore > Profiles > Settings.

Authorize access to GitHub

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

1. From within Single view with a configured Pyroscope app plugin.
2. Select Pyroscope service. For this example, select cpu_profile.
3. Click in the flame graph on a function you want to explore. Select Function details.
4. 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.
5. If prompted, log in to GitHub.
6. After Grafana connects to your GitHub account, review the permissions and select Authorize Grafana Pyroscope.

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 is used to authorize Grafana Cloud to access source code and commit information.

After authorizing the app, your GitHub account, GitHub > Settings > Applications now 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 (revoke) the app’s permissions by selecting Revoke. Revoking the permissions disables the integration in your Grafana Cloud account.

For more information about GitHub applications:

• Using GitHub apps
• Authorizing GitHub apps
• Differences between installing and authorizing apps

How your GitHub code shows up in profile data queries

After the Pyroscope Grafana integration is authorized, you see more details in the Function Details from flame graphs in Single view.

1. Open a browser to your Pyroscope instance.
2. Sign in to your account, if prompted.
3. After the Grafana instance loads, select Explore.
4. Next, select Profiles > Single view from the left-side menu.
5. Optional: Select a Service and Profile.
6. 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.