菜单
文档面包屑箭头 Grafana Pyroscope面包屑箭头 配置客户端以发送分析面包屑箭头 语言 SDK面包屑箭头 .NET
开源

.NET

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

注意

请参阅 可用的分析类型，以了解每种语言支持的分析类型列表。

支持的分析类型

.NET 分析器支持以下分析类型

  • CPU
  • 挂钟时间
  • 分配
  • 锁争用
  • 异常
  • 实时堆（需要 .NET 7+）

兼容性

我们的 .NET 分析器与以下 .NET 版本配合使用

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

开始之前

要捕获和分析分析数据，您需要一个托管的 Pyroscope OSS 服务器或一个托管的 带有 Grafana Cloud 分析的 Pyroscope 实例（需要免费的 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.8.19-pyroscope/pyroscope.0.8.19-glibc-x86_64.tar.gz  | tar xvz -C .

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

dockerfile 
COPY --from=pyroscope/pyroscope-dotnet:0.8.19-glibc /Pyroscope.Profiler.Native.so ./Pyroscope.Profiler.Native.so
COPY --from=pyroscope/pyroscope-dotnet:0.8.19-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，则禁用墙上时间分析。默认为 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 基本身份验证，使用此选项将配置文件发送到经过身份验证的服务器，例如 Grafana Cloud
PYROSCOPE_BASIC_AUTH_PASSWORD字符串对于 HTTP 基本身份验证，使用此选项将配置文件发送到经过身份验证的服务器，例如 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 基本身份验证。将 <User> 替换为您的 Grafana Cloud 堆栈用户，将 <Password> 替换为您的 Grafana Cloud API 密钥。

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