菜单
文档breadcrumb arrow Grafana Pyroscopebreadcrumb arrow 配置客户端以发送性能分析数据breadcrumb arrow 语言 SDKbreadcrumb arrow .NET
开源

.NET

我们的 .NET Profiler 是一个强大的工具，旨在增强 .NET 应用程序的性能分析和优化。它与 Pyroscope 无缝集成，提供对 .NET 代码库中资源使用情况和瓶颈的实时洞察。这种集成使开发人员能够精确定位效率低下的问题，提高应用程序速度，并确保资源高效运行。

注意

请参阅可用的性能分析类型，查看每种语言支持的性能分析类型列表。

支持的性能分析类型

.NET Profiler 支持以下性能分析类型

  • CPU
  • 墙钟时间
  • 内存分配
  • 锁竞争
  • 异常
  • 实时堆 (需要 .NET 7+)

兼容性

我们的 .NET 性能分析器适用于以下 .NET 版本

  • .NET 6
  • .NET 7
  • .NET 8

开始之前

要捕获和分析性能分析数据，您需要托管的 Pyroscope OSS 服务器或托管的 带有 Grafana Cloud Profiles 的 Pyroscope 实例（需要免费的 Grafana Cloud 帐户）。

Pyroscope 服务器可以是用于开发的本地服务器，也可以是用于生产环境的远程服务器。

配置 Dotnet 客户端

  1. 从最新的 tarball中获取 Pyroscope.Profiler.Native.so 和 Pyroscope.Linux.ApiWrapper.x64.so
bash 
curl -s -L https://github.com/grafana/pyroscope-dotnet/releases/download/v0.9.2-pyroscope/pyroscope.0.9.2-glibc-x86_64.tar.gz  | tar xvz -C .

或者从最新的 Docker 镜像中复制它们。我们有 glibc 和 musl 版本

dockerfile 
COPY --from=pyroscope/pyroscope-dotnet:0.9.2-glibc /Pyroscope.Profiler.Native.so ./Pyroscope.Profiler.Native.so
COPY --from=pyroscope/pyroscope-dotnet:0.9.2-glibc /Pyroscope.Linux.ApiWrapper.x64.so ./Pyroscope.Linux.ApiWrapper.x64.so
  1. 设置以下必需的环境变量以启用性能分析器
shell 
PYROSCOPE_APPLICATION_NAME=rideshare.dotnet.app
PYROSCOPE_SERVER_ADDRESS=https://127.0.0.1:4040
PYROSCOPE_PROFILING_ENABLED=1
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={BD1A650D-AC5D-4896-B64F-D6FA25D6B26A}
CORECLR_PROFILER_PATH=Pyroscope.Profiler.Native.so
LD_PRELOAD=Pyroscope.Linux.ApiWrapper.x64.so

注意

由于 .NET 版本 8，环境变量 DOTNET_EnableDiagnostics=0（或其旧版等效项 COMPlus_EnableDiagnostics=0）也将禁用性能分析器。为了获得之前的行为（允许性能分析，但关闭 IPC 和调试），应改为设置以下环境变量

shell 
DOTNET_EnableDiagnostics=1
DOTNET_EnableDiagnostics_IPC=0
DOTNET_EnableDiagnostics_Debugger=0
DOTNET_EnableDiagnostics_Profiler=1

.NET Profiler API

借助托管的辅助程序，您可以从 .NET 运行时与 Pyroscope 性能分析器进行交互。您可以添加标签，打开/关闭性能分析类型等等。

要使用它，首先添加 Pyroscope 依赖项

shell 
dotnet add package Pyroscope

 

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

您可以将标签添加到性能分析数据，以便在 UI 中过滤数据。常用标签包括

  • 主机名
  • 区域
  • 团队
  • API 端点

创建一个 LabelSet 并使用 Pyroscope.LabelsWrapper 包裹一段代码。

cs 
var labels = Pyroscope.LabelSet.Empty.BuildUpon()
    .Add("key1", "value1")
    .Build();
Pyroscope.LabelsWrapper.Do(labels, () =>
{
  SlowCode();
});

标签可以嵌套。对于嵌套的 LabelSet，请在非空集合上使用 LabelSet.BuildUpon。

cs 
var labels = Pyroscope.LabelSet.Empty.BuildUpon()
    .Add("key1", "value1")
    .Build();
Pyroscope.LabelsWrapper.Do(labels, () =>
{
  var labels2 = labels.BuildUpon()
    .Add("key2", "value2")
    .Build();
  Pyroscope.LabelsWrapper.Do(labels2, () =>
  {
    SlowCode();
  });
  FastCode();
});

动态控制

可以动态启用/禁用特定的性能分析类型。性能分析类型必须事先配置。

cs 
// Enables or disables CPU/wall profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_CPU_ENABLED and
// PYROSCOPE_PROFILING_WALLTIME_ENABLED environment variables. If CPU/wall profiling is not
// configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetCPUTrackingEnabled(enabled);
// Enables or disables allocation profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_ALLOCATION_ENABLED environment variable.
// If allocation profiling is not configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetAllocationTrackingEnabled(enabled);
// Enables or disables contention profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_LOCK_ENABLED environment variable.
// If contention profiling is not configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetContentionTrackingEnabled(enabled);
// Enables or disables exception profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_EXCEPTION_ENABLED environment variable.
// If exception profiling is not configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetExceptionTrackingEnabled(enabled);

可以动态更改授权凭据

cs 
// Set Basic authorization username and password. Clears any previous authorization credentials.
Pyroscope.Profiler.Instance.SetBasicAuth(basicAuthUser, BasicAuthPassword);

这是一个简单的 示例，展示了如何将这些 API 作为 HTTP 端点公开。

配置选项

环境变量类型描述
PYROSCOPE_PROFILING_LOG_DIR字符串设置 .NET Profiler 日志的目录。默认为 /var/log/pyroscope/。
PYROSCOPE_LABELS字符串应用于上传性能分析文件的静态标签。必须是以逗号分隔的键:值列表，例如：layer:api 或 team:intake。
PYROSCOPE_SERVER_ADDRESS字符串Pyroscope 服务器的地址
PYROSCOPE_PROFILING_ENABLED布尔值如果设置为 true，则启用 .NET Profiler。默认为 false。
PYROSCOPE_PROFILING_WALLTIME_ENABLED布尔值如果设置为 false，则禁用墙钟时间性能分析。默认为 false。
PYROSCOPE_PROFILING_CPU_ENABLED布尔值如果设置为 false，则禁用 CPU 性能分析。默认为 true。
PYROSCOPE_PROFILING_EXCEPTION_ENABLED布尔值如果设置为 true，则启用异常性能分析。默认为 false。
PYROSCOPE_PROFILING_ALLOCATION_ENABLED布尔值如果设置为 true，则启用内存分配性能分析。默认为 false。
PYROSCOPE_PROFILING_LOCK_ENABLED布尔值如果设置为 true，则启用锁竞争性能分析。默认为 false。
PYROSCOPE_PROFILING_HEAP_ENABLED布尔值如果设置为 true，则启用实时堆性能分析。需要 .NET 7+。默认为 false。
PYROSCOPE_BASIC_AUTH_USER字符串对于 HTTP Basic Authentication，使用此项将性能分析文件发送到已验证的服务器，例如 Grafana Cloud
PYROSCOPE_BASIC_AUTH_PASSWORD字符串对于 HTTP Basic Authentication，使用此项将性能分析文件发送到已验证的服务器，例如 Grafana Cloud
PYROSCOPE_TENANT_ID字符串仅在使用 Pyroscope 中的多租户时才需要。

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

要从 .NET 应用程序发送性能分析数据，请使用以下步骤为 Pyroscope OSS 或 Grafana Cloud Profiles 配置您的环境

bash 
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={BD1A650D-AC5D-4896-B64F-D6FA25D6B26A}
export CORECLR_PROFILER_PATH=/dotnet/Pyroscope.Profiler.Native.so
export LD_PRELOAD=/dotnet/Pyroscope.Linux.ApiWrapper.x64.so
export PYROSCOPE_PROFILING_ENABLED=1
export PYROSCOPE_APPLICATION_NAME=example.dotnet.app
export PYROSCOPE_SERVER_ADDRESS=<URL>
# Use these environment variables to send data to Grafana Cloud Profiles
export PYROSCOPE_BASIC_AUTH_USER=<User>
export PYROSCOPE_BASIC_AUTH_PASSWORD=<Password>
# Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
# export PYROSCOPE_TENANT_ID=<TenantID>

要配置 .NET SDK 以将数据发送到 Grafana Cloud Profiles 或 Pyroscope，请将 <URL> 占位符替换为相应的服务器 URL。这可以是 Grafana Cloud URL 或您自己的自定义 Pyroscope 服务器 URL。

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

如果您的开源 Pyroscope 服务器启用了多租户，您需要指定租户 ID。将 <TenantID> 替换为您的 Pyroscope 租户 ID。