package main

import "github.com/grafana/pyroscope-go"

func main() {
  // These 2 lines are only required if you're using mutex or block profiling
  // Read the explanation below for how to set these rates:
  runtime.SetMutexProfileFraction(5)
  runtime.SetBlockProfileRate(5)

  pyroscope.Start(pyroscope.Config{
    ApplicationName: "simple.golang.app",

    // replace this with the address of pyroscope server
    ServerAddress:   "http://pyroscope-server:4040",

    // you can disable logging by setting this to nil
    Logger:          pyroscope.StandardLogger,

    // you can provide static tags via a map:
    Tags:            map[string]string{"hostname": os.Getenv("HOSTNAME")},

    ProfileTypes: []pyroscope.ProfileType{
      // these profile types are enabled by default:
      pyroscope.ProfileCPU,
      pyroscope.ProfileAllocObjects,
      pyroscope.ProfileAllocSpace,
      pyroscope.ProfileInuseObjects,
      pyroscope.ProfileInuseSpace,

      // these profile types are optional:
      pyroscope.ProfileGoroutines,
      pyroscope.ProfileMutexCount,
      pyroscope.ProfileMutexDuration,
      pyroscope.ProfileBlockCount,
      pyroscope.ProfileBlockDuration,
    },
  })

  // your code goes here
}

为您的应用程序添加性能分析标签

您可以为性能分析数据添加标签（标签）。这些标签可用于在 UI 中过滤数据。有一个与 go-native pprof API 兼容的自定义 API

// these two ways of adding tags are equivalent:
pyroscope.TagWrapper(context.Background(), pyroscope.Labels("controller", "slow_controller"), func(c context.Context) {
  slowCode()
})

pprof.Do(context.Background(), pprof.Labels("controller", "slow_controller"), func(c context.Context) {
  slowCode()
})

互斥锁性能分析

互斥锁性能分析对于查找应用程序中的竞争源很有用。它帮助您找出哪些互斥锁被哪些 goroutines 所持有。

要启用互斥锁性能分析，您需要将以下代码添加到您的应用程序

runtime.SetMutexProfileFraction(rate)

rate 参数控制报告在互斥锁配置文件中的互斥锁竞争事件的分数。平均而言，报告 1/rate 事件。

阻塞性能分析

阻塞性能分析允许您分析程序在等待阻塞操作（例如）上花费的时间

select
channel 发送/接收
semacquire
notifyListWait

要启用阻塞性能分析，您需要将以下代码添加到您的应用程序

runtime.SetBlockProfileRate(rate)

rate 参数控制报告在阻塞配置文件中的 goroutine 阻塞事件的分数。分析器旨在在每个 rate 纳秒内采样一个阻塞事件。

将数据发送到 Pyroscope OSS 或 Grafana Cloud Profiles

要将 Golang SDK 配置为向 Pyroscope 发送数据，请将 <URL> 占位符替换为适当的服务器 URL。这可能是 Grafana Cloud URL 或您自己的自定义 Pyroscope 服务器 URL。

如果您需要将数据发送到 Grafana Cloud，您将需要配置 HTTP Basic 身份验证。将 <User> 替换为您的 Grafana Cloud 堆栈用户，将 <Password> 替换为您的 Grafana Cloud API 密钥。

如果您的 Pyroscope 服务器启用了多租户，您将需要配置一个租户 ID。将 <TenantID> 替换为您的 Pyroscope 租户 ID。

pyroscope.Start(pyroscope.Config{
  ApplicationName:   "example.golang.app",
  ServerAddress:     "<URL>",
  // Optional HTTP Basic authentication
  BasicAuthUser:     "<User>",
  BasicAuthPassword: "<Password>",
  // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
  // TenantID:          "<TenantID>",
  ProfileTypes: []pyroscope.ProfileType{
    pyroscope.ProfileCPU,
    pyroscope.ProfileInuseObjects,
    pyroscope.ProfileAllocObjects,
    pyroscope.ProfileInuseSpace,
    pyroscope.ProfileAllocSpace,
  },
})

选项：使用 `DisableGCRuns` 来处理增加的内存使用

当跟踪大量对象时，Pyroscope 可能需要额外的资源。例如，索引大量数据的 Go 服务需要更多的内存。这种跟踪可能导致更高的 CPU 使用率和潜在的 CPU 节流。

您可以在 Go 配置中使用 DisableGCRuns 来禁用自动运行时。如果此标志被激活，GC 运行较少，因此 CPU 资源消耗较少。然而，堆配置文件可能不够精确。

背景

在 Go 的 pprof 堆配置文件中，强制垃圾回收（GC）通过删除未收集的对象来确保准确的内存使用快照。如果没有此步骤，堆配置文件可能包括已分配但不再使用的内存——仅仅因为尚未收集而留在内存中的对象。这可能会掩盖或模仿内存泄漏，并将偏差引入配置文件，从而复杂化其分析。因此，Pyroscope 默认在收集堆配置文件时强制 GC。

然而，在某些情况下，强制执行垃圾回收（GC）可能会增加CPU使用率，尤其是在堆中有许多活动对象时。这个问题在CPU性能分析中通过出现 runtime.GC 函数得到反映。如果问题已经出现，并且堆性能分析中的一些不准确是可以接受的，那么建议禁用此选项以避免性能下降。

激活 `DisableGCRuns`

将 DisableGCRuns: true 添加到 pyroscope.Start(pyroscope.Config) 块中。

pyroscope.Start(pyroscope.Config{
  ApplicationName:   "example.golang.app",
  ServerAddress:     "<URL>",
  // Disable automatic runtime.GC runs between getting the heap profiles.
		DisableGCRuns:   true,