Skip to content

Commit 04186d8

Browse files
[DOC] Add doc for DisbleGCRuns (#3664)
* Add doc for DisbleGCRuns * Update docs/sources/configure-client/language-sdks/go_push.md * Add background info * Update docs/sources/configure-client/language-sdks/go_push.md
1 parent ebc732f commit 04186d8

File tree

1 file changed

+42
-6
lines changed
  • docs/sources/configure-client/language-sdks

1 file changed

+42
-6
lines changed

‎docs/sources/configure-client/language-sdks/go_push.md

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ go get github.com/grafana/pyroscope-go
3939
If you'd prefer to use Pull mode you can do so using [Grafana Alloy](https://grafana.com/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/grafana-alloy/).
4040
{{% /admonition %}}
4141

42-
Then add the following code to your application:
42+
Add the following code to your application:
4343

4444
```go
4545
package main
@@ -110,7 +110,7 @@ To enable mutex profiling, you need to add the following code to your applicatio
110110
runtime.SetMutexProfileFraction(rate)
111111
```
112112

113-
`rate` parameter controls the fraction of mutex contention events that are reported in the mutex profile. On average 1/rate events are reported.
113+
The `rate` parameter controls the fraction of mutex contention events that are reported in the mutex profile. On average, 1/rate events are reported.
114114

115115
### Block profiling
116116

@@ -127,10 +127,20 @@ To enable block profiling, you need to add the following code to your applicatio
127127
runtime.SetBlockProfileRate(rate)
128128
```
129129

130-
`rate` parameter controls the fraction of goroutine blocking events that are reported in the blocking profile. The profiler aims to sample an average of one blocking event per rate nanoseconds spent blocked.
130+
The `rate` parameter controls the fraction of goroutine blocking events that are reported in the blocking profile.
131+
The profiler aims to sample an average of one blocking event per rate nanoseconds spent blocked.
131132

132133
## Send data to Pyroscope OSS or Grafana Cloud Profiles
133134

135+
To configure the Golang SDK to send data to Pyroscope, replace the `<URL>` placeholder with the appropriate server URL.
136+
This could be the Grafana Cloud URL or your own custom Pyroscope server URL.
137+
138+
If you need to send data to Grafana Cloud, you'll have to configure HTTP Basic authentication.
139+
Replace `<User>` with your Grafana Cloud stack user and `<Password>` with your Grafana Cloud API key.
140+
141+
If your Pyroscope server has multi-tenancy enabled, you'll need to configure a tenant ID.
142+
Replace `<TenantID>` with your Pyroscope tenant ID.
143+
134144
```go
135145
pyroscope.Start(pyroscope.Config{
136146
ApplicationName: "example.golang.app",
@@ -150,11 +160,37 @@ pyroscope.Start(pyroscope.Config{
150160
})
151161
```
152162

153-
To configure the Golang SDK to send data to Pyroscope, replace the `<URL>` placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.
163+
### Option: Use `DisableGCRuns` for handling increased memory usage
164+
165+
Pyroscope may require additional resources when tracking a lot of objects. For example, a Go service that indexes large amounts of data requires more memory.
166+
This tracking can lead to higher CPU usage and potential CPU throttling.
167+
168+
You can use `DisableGCRuns` in your Go configuration to disable automatic runtimes.
169+
If this flag is activated, there is less GC running and therefore less CPU resources spent.
170+
However, the heap profile may be less precise.
171+
172+
#### Background
173+
174+
In Go's pprof heap profiling, forcing garbage collection (GC) ensures accurate memory usage snapshots by removing uncollected objects.
175+
Without this step, the heap profile may include memory that has been allocated but is no longer in use--objects that stay in memory simply because they haven't been collected yet.
176+
This can mask or mimic memory leaks and introduce bias into the profiles, complicating their analysis.
177+
Therefore, Pyroscope defaults to forcing GC every time a heap profile is collected.
154178

155-
If you need to send data to Grafana Cloud, you'll have to configure HTTP Basic authentication. Replace `<User>` with your Grafana Cloud stack user and `<Password>` with your Grafana Cloud API key.
179+
However, in some cases, forcing GC can increase CPU usage, especially if there are many live objects in the heap.
180+
This issue is reflected by the appearance of the `runtime.GC` function in the CPU profile.
181+
If the problem has manifested, and some inaccuracy in the heap profile is acceptable, then it is advisable to disable this option to avoid performance degradation.
156182

157-
If your Pyroscope server has multi-tenancy enabled, you'll need to configure a tenant ID. Replace `<TenantID>` with your Pyroscope tenant ID.
183+
#### Activate `DisableGCRuns`
184+
185+
Add `DisableGCRuns: true` to the `pyroscope.Start(pyroscope.Config)` block.
186+
187+
```go
188+
pyroscope.Start(pyroscope.Config{
189+
ApplicationName: "example.golang.app",
190+
ServerAddress: "<URL>",
191+
// Disable automatic runtime.GC runs between getting the heap profiles.
192+
DisableGCRuns: true,
193+
```
158194
159195
## Golang profiling examples
160196

0 commit comments

Comments
 (0)