菜单
文档breadcrumb arrow Grafana Pyroscopebreadcrumb arrow 配置客户端以发送配置文件breadcrumb arrow 语言 SDKbreadcrumb arrow .NET
开源

.NET

我们的 .NET 分析器是一款强大的工具，旨在增强 .NET 应用程序的性能分析和优化。它无缝集成到 Pyroscope 中，为您提供对 .NET 代码库内资源使用和瓶颈的实时洞察。这种集成使开发者能够定位低效之处，提高应用程序速度，并确保资源高效运行。

注意

有关每个语言支持的配置文件类型列表，请参阅可用配置文件类型。

支持的配置文件类型

.NET 分析器支持以下配置文件类型

  • CPU
  • 墙时
  • 分配
  • 锁争用
  • 异常
  • 活动堆（需要 .NET 7+）

兼容性

我们的 .NET 分析器与以下 .NET 版本兼容

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

开始之前

要捕获和分析配置文件数据，您需要一个托管的 Pyroscope OSS 服务器或一个托管的 Pyroscope 实例与 Grafana Cloud Profiles（需要免费 Grafana Cloud 账户）。

Pyroscope 服务器可以是开发用的本地服务器或生产用的远程服务器。

配置 Dotnet 客户端

  1. 从最新版本压缩包中获取 Pyroscope.Profiler.Native.so 和 Pyroscope.Linux.ApiWrapper.x64.so
bash 
curl -s -L https://github.com/grafana/pyroscope-dotnet/releases/download/v0.9.0-pyroscope/pyroscope.0.9.0-glibc-x86_64.tar.gz  | tar xvz -C .

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

Dockerfile 
COPY --from=pyroscope/pyroscope-dotnet:0.9.0-glibc /Pyroscope.Profiler.Native.so ./Pyroscope.Profiler.Native.so
COPY --from=pyroscope/pyroscope-dotnet:0.9.0-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 分析器 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();
});

标签可以嵌套。要嵌套 LabelSets，请在非空集合上使用 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 分析器日志的目录。默认为 /var/log/pyroscope/。
PYROSCOPE_LABELS字符串静态标签，应用于上传的配置文件。必须是逗号分隔的键：值列表，例如：layer:api 或 team:intake。
PYROSCOPE_SERVER_ADDRESS字符串Pyroscope 服务器的地址
PYROSCOPE_PROFILING_ENABLED布尔值如果设置为 true，则启用 .NET 分析器。默认为 false。
PYROSCOPE_PROFILING_WALLTIME_ENABLED布尔值如果设置为 false，则禁用 Wall time 分析。默认为 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，则启用 Live 堆分析。需要 .NET 7+。默认为 false。
PYROSCOPE_BASIC_AUTH_USER字符串对于HTTP基本认证，使用以下方法向认证服务器发送配置文件，例如Grafana Cloud。
PYROSCOPE_BASIC_AUTH_PASSWORD字符串对于HTTP基本认证，使用以下方法向认证服务器发送配置文件，例如Grafana Cloud。
PYROSCOPE_TENANT_ID字符串仅在Pyroscope中使用多租户时需要。

向Pyroscope OSS或Grafana Cloud配置文件发送数据

要从.NET应用程序发送分析数据，请按照以下步骤配置环境以使用Pyroscope OSS或Grafana Cloud配置文件

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配置文件或Pyroscope发送数据，将<URL>占位符替换为相应的服务器URL。这可以是Grafana Cloud URL或您自己的自定义Pyroscope服务器URL。

如果您需要向Grafana Cloud发送数据，您将必须配置HTTP基本认证。将<User>替换为您的Grafana Cloud堆栈用户，将<Password>替换为您的Grafana Cloud API密钥。

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