Skip to content

Commit dbdcd4e

Browse files
simonswinesimonswine
authored
Add OSS documentation on the Source Code GitHub integration (#4129)
* WIP: docs: Add OSS documentation on the GitHub integration * Adapt doc from grafana-cloud docs * Fix link to be without .md * Used outdated GitHub link * Now use the correct link * Add link to github and convert requirements into admonition
1 parent 5c45fd3 commit dbdcd4e

File tree

2 files changed

+267
-0
lines changed

2 files changed

+267
-0
lines changed

‎docs/sources/configure-server/configuring-github-integration.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
description: Learn how to configure the GitHub integration for Grafana Pyroscope.
3+
menuTitle: Configure GitHub integration
4+
title: Configure GitHub integration for Grafana Pyroscope
5+
weight: 550
6+
---
7+
8+
# Configuring GitHub Integration
9+
10+
This guide walks you through setting up the GitHub integration with minimal permissions for Grafana Pyroscope.
11+
12+
## Creating a GitHub App
13+
14+
1. Go to your GitHub account settings
15+
2. Navigate to **Developer settings** > **GitHub Apps**
16+
3. Click **New GitHub App**
17+
4. Configure the app with the following settings:
18+
#### **Basic Information**
19+
- **GitHub App name**: Choose a name for your app (e.g., "my-pyroscope")
20+
- **Homepage URL**: This is a required field, you can use any URL. (e.g., `https://grafana.com/oss/pyroscope/`)
21+
- **Callback URL**: Set this to your Grafana installation URL with the GitHub callback path. (e.g., `https://grafana.your-domain.com/a/grafana-pyroscope-app/github/callback`)
22+
23+
#### Permissions
24+
25+
The GitHub App works without any extra permissions for public repositories. If you want to access private repositories, you need to add these permissions:
26+
27+
- **Repository permissions**:
28+
- **Metadata**: Read-only access
29+
- **Contents**: Read-only access
30+
31+
#### Where can this GitHub App be installed?
32+
- Select **Any account** if you want to allow installation on any GitHub account
33+
- Select **Only on this account** if you want to restrict installation to your account only
34+
5. Click **Create GitHub App**
35+
6. After creating the GitHub App, you should end up in the GitHub App settings, find the **Client ID** and take a note of it.
36+
7. Now scroll down to the **Client secrets** section and click **Generate a new client secret**
37+
8. **Important**: Copy the generated client secret immediately - you won't be able to see it again after closing the dialog
38+
39+
For anything not covered in this guide, you can refer to the GitHub docs: [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
40+
41+
42+
## Configuring Pyroscope
43+
44+
This section explains how to configure the GitHub integration in Grafana Pyroscope. The integration requires three environment variables to be set:
45+
46+
| Variable | Description | Required |
47+
|----------|-------------|----------|
48+
| `GITHUB_CLIENT_ID` | The Client ID of your GitHub App | Yes |
49+
| `GITHUB_CLIENT_SECRET` | The Client Secret of your GitHub App | Yes |
50+
| `GITHUB_SESSION_SECRET` | A random string used to encrypt the session | Yes |
51+
52+
### Using the Helm Chart
53+
54+
If you're using the official Helm chart, follow these steps to configure the GitHub integration:
55+
56+
1. Create a Kubernetes secret containing the required values, this will also generate a new random session secret:
57+
58+
```bash
59+
kubectl create secret generic pyroscope-github \
60+
"--from-literal=client_id=<The Client ID from the 6. step>" \
61+
"--from-literal=client_secret=<The Client secret from the 8. step>" \
62+
"--from-literal=session_secret=$(openssl rand -base64 48)"
63+
```
64+
65+
2. Update your `values.yaml` to expose these secrets as environment variables:
66+
67+
```yaml
68+
pyroscope:
69+
extraEnvVars:
70+
GITHUB_CLIENT_ID:
71+
valueFrom:
72+
secretKeyRef:
73+
secret: pyroscope-github
74+
key: client_id
75+
GITHUB_CLIENT_SECRET:
76+
valueFrom:
77+
secretKeyRef:
78+
secret: pyroscope-github
79+
key: client_secret
80+
GITHUB_SESSION_SECRET:
81+
valueFrom:
82+
secretKeyRef:
83+
secret: pyroscope-github
84+
key: session_secret
85+
```
86+
87+
3. Apply the changes using helm upgrade:
88+
89+
90+
### Other Deployment Methods
91+
92+
For other deployment methods, ensure the same environment variables are set in your deployment configuration.
93+
94+
## Verifying the Integration
95+
96+
The configuration of the GitHub integration is now completed. In order to verify everything works as expected follow the user guide: [Integrate your source code on GitHub with Pyroscope profiling data](../../view-and-analyze-profile-data/line-by-line/).

‎docs/sources/view-and-analyze-profile-data/line-by-line.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
description: Integrate your source code on GitHub with Pyroscope profiling data.
3+
keywords:
4+
- GitHub
5+
- continuous profiling
6+
- flame graphs
7+
menuTitle: Show usage line by line
8+
title: Integrate your source code on GitHub with Pyroscope profiling data.
9+
weight: 550
10+
---
11+
12+
# Integrate your source code on GitHub with Pyroscope profiling data.
13+
14+
The Grafana Pyroscope GitHub integration offers seamless integration between your code repositories and Grafana.
15+
Using this app, you can map your code directly within Grafana and visualize resource performance line by line.
16+
With these powerful capabilities, you can gain deep insights into your code's execution and identify performance bottlenecks.
17+
18+
Every profile type works for the integration for code written in Go.
19+
For information on profile types and the profiles available with Go, refer to [Profiling types and their uses](../introduction/profiling-types/).
20+
21+
![Example of a flame graph with the function details populated](/media/docs/grafana-cloud/profiles/screenshot-profiles-github-integration.png)
22+
23+
## How it works
24+
25+
The Pyroscope GitHub integration uses labels configured in the application being profiled to associate profiles with source code.
26+
The integration is only available for Go applications.
27+
The Go profiler can map symbolic information, such as function names and line numbers, to source code.
28+
29+
The Pyroscope GitHub 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.
30+
31+
{{< admonition type="note" >}}
32+
The source code mapping is only available to people who have access to the source code in GitHub.
33+
{{< /admonition >}}
34+
35+
## Before you begin
36+
37+
To use the Pyroscope integration for GitHub, you need an application that emits profiling data, a GitHub account, and a Grafana instance with a Grafana Pyroscope backend.
38+
39+
### Application with profiling data requirements
40+
41+
{{< admonition type="warning" >}}
42+
- Applications in other languages aren't supported
43+
- eBPF profiled Go workloads aren't supported
44+
{{< /admonition >}}
45+
46+
- A Go application which is profiled by Grafana Alloy's `pyroscope.scrape` or using the [Go Push SDK](../../configure-client/language-sdks/go_push/).
47+
48+
49+
Your Go application provides the following labels (tags):
50+
51+
- `service_git_ref` points to the Git commit or [reference](https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28#about-git-references) from which the binary was built
52+
- `service_repository` is the GitHub repository that hosts the source code
53+
- `service_root_path` (Optional) is the path where the code lives inside the repository
54+
55+
To activate this integration, you need to add at least the two mandatory labels when sending profiles:
56+
`service_repository` and `service_git_ref`.
57+
They should respectively be set to the full repository GitHub URL and the current
58+
[`git ref`](https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28#about-git-references).
59+
60+
```go
61+
pyroscope.Start(pyroscope.Config{
62+
Tags: map[string]string{
63+
"service_git_ref": "<GIT_REF>",
64+
"service_repository": "https://github.com/<YOUR_ORG>/<YOUR_REPOSITORY>",
65+
"service_root_path": "<PATH_TO_SERVICE_ROOT>", // optional
66+
},
67+
// Other configuration
68+
})
69+
```
70+
71+
### GitHub requirements
72+
73+
- A GitHub account
74+
- Source code hosted on GitHub
75+
76+
{{< admonition type="note" >}}
77+
Data from your GitHub repository may be limited if your GitHub organization or repository restricts third-party applications.
78+
For example, the organization may need to add this app to an allowlist to access organizational resources.
79+
Contact your organization administrator for assistance.
80+
Refer to [Requesting a GitHub App from your organization owner](https://docs.github.com/en/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner).
81+
{{< /admonition >}}
82+
83+
### Ensure the GitHub integration is configued in Grafana Pyroscope
84+
85+
Refer to [Configure GitHub integration](../configure-server/configuring-github-integration/) on the steps required.
86+
87+
### Ensure the Grafana Pyroscope data source is configued correctly
88+
89+
In order to make use of the GitHub integration, the Pyroscope data source needs to be configured to pass a particular cookie through.
90+
91+
To configure cookie passthrough in Grafana:
92+
93+
1. Navigate to **Configuration** > **Data sources** in Grafana.
94+
1. Select your Pyroscope data source.
95+
1. Under **Additional settings** > **Advanced HTTP settings** , locate **Allowed cookies**.
96+
1. Add `pyroscope_git_session` to the list of cookies to forward.
97+
1. Click **Save & test** to apply the changes.
98+
99+
100+
![Additional data source settings for Pyroscope GitHub integration](/media/docs/pyroscope/pyroscope-data-source-additional-settings.png)
101+
102+
{{< admonition type="note" >}}
103+
Cookie forwarding must be enabled for the GitHub integration to work properly. Without it, you won't be able to connect to GitHub repositories from within Grafana Profiles Drilldown.
104+
{{< /admonition >}}
105+
106+
107+
## Authorize access to GitHub
108+
109+
You can authorize with GitHub using the **Connect to GitHub** in the **Function Details** panel.
110+
111+
1. From within **Single view** with a configured Pyroscope app plugin.
112+
1. Select **Pyroscope service**. For this example, select `cpu_profile`.
113+
1. Click in the flame graph on a function you want to explore. Select **Function details**.
114+
1. 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.
115+
1. If prompted, log in to GitHub.
116+
1. After Grafana connects to your GitHub account, review the permissions and select **Authorize Grafana Pyroscope**.
117+
118+
{{< admonition type="note" >}}
119+
Organization owners may disallow third-party apps for the entire organization or specific organization resources, like repositories.
120+
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.
121+
{{< /admonition >}}
122+
123+
### Modify or remove the Pyroscope GitHub integration from your GitHub account
124+
125+
The Pyroscope GitHub integration uses a GitHub app called "Grafana Pyroscope" to connect to GitHub.
126+
This application authorizes Grafana Cloud to access source code and commit information.
127+
128+
After authorizing the app, your GitHub account, **GitHub** > **Settings** > **Applications** lists the Grafana Pyroscope app.
129+
130+
You can change the repositories the Pyroscope GitHub integration can access on the **Applications** page.
131+
132+
You can use also remove the app's permissions by selecting **Revoke**.
133+
Revoking the permissions disables the integration in your Grafana Cloud account.
134+
135+
For more information about GitHub applications:
136+
137+
- [Using GitHub apps](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps)
138+
- [Authorizing GitHub apps](https://docs.github.com/en/apps/using-github-apps/authorizing-github-apps)
139+
- [Differences between installing and authorizing apps](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party#difference-between-installation-and-authorization)
140+
141+
## How your GitHub code shows up in profile data queries
142+
143+
After authorizing the Pyroscope Grafana integration, you see more details in the **Function Details** from flame graphs in Profiles Drilldown.
144+
145+
1. Open a browser to your Pyroscope instance.
146+
1. Sign in to your account, if prompted.
147+
1. After the Grafana instance loads, select **Drilldown**.
148+
1. Next, select **Profiles** > **Single view** from the left-side menu.
149+
1. Optional: Select a **Service** and **Profile**.
150+
1. Click in the flame graph and select **Function details** from the pop-up menu.
151+
152+
### Function Details
153+
154+
The Function Details section provide information about the function you selected from the flame graph.
155+
156+
{{< figure max-width="80%" class="center" caption-align="center" src="/media/docs/grafana-cloud/profiles/screenshot-profiles-github-funct-details-v3.png" caption="Function Details panel from a connected Pyroscope GitHub integration." >}}
157+
158+
The table explains the main fields in the table.
159+
The values for some of the fields, such as Self and Total, change depending whether a profile uses time or memory amount.
160+
Refer to [Understand Self versus Total metrics in profiling with Pyroscope](https://grafana.com/docs/pyroscope/latest/view-and-analyze-profile-data/self-vs-total/) for more information.
161+
162+
| Field | Meaning | Notes |
163+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
164+
| Function name | The name of the selected function | |
165+
| Start time | The line where the function definition starts | |
166+
| File | Path where the function is defined | You can use the clipboard icon to copy the path. |
167+
| Repository | The repository configured for the selected service | |
168+
| 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. |
169+
| Breakdown per line (table) | Provides the function location in the code and self and total values. | |
170+
| 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. |
171+
| 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. |

0 commit comments

Comments
 (0)