Grafana Phlare Configure the Client Language SDKs .NET

.NET

In March 2023, Grafana Labs acquired Pyroscope, the company behind the eponymous open source continuous profiling project. As a result, the Pyroscope and Grafana Phlare projects will be merged under the new name Grafana Pyroscope. To learn more, read our recent blog post about the news.

How to add .NET profiling to your application

1. Download Pyroscope.Profiler.Native.so and Pyroscope.Linux.ApiWrapper.x64.so from latest release

2. Set the following required environment variables to enable profiler

PYROSCOPE_APPLICATION_NAME=rideshare.dotnet.app
PYROSCOPE_SERVER_ADDRESS=http://localhost:4040
PYROSCOPE_AUTH_TOKEN="psx-..." # optional auth token
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

Managed helper

With a managed helper you can interact with pyroscope profiler from .Net.

First, add dependency:

dotnet add package Pyroscope

How to add profiling labels to .NET applications

It is possible to add labels to the profiling data. These labels can be used to filter the data in the UI.

Create a LabelSet and wrap a piece of code with Pyroscope.LabelsWrapper.

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

Labels can be nested. For nesting LabelSets use LabelSet.BuildUpon on non-empty set.

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();
});

Dynamic profiling control

It is possible to dynamically enable/disable specific profiling types. Profiling types have to be configured prior.

// 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_CONTENTION_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);

It is possible to dynamically change auth tokens.

// Set Authorization Bearer token. Clear any previously set Authorization tokens.
Pyroscope.Profiler.Instance.SetAuthToken(token);
// Set Authorization Basic username and password. Clear any previously set Authorization tokens.
Pyroscope.Profiler.Instance.SetBasicAuth(basicAuthUser, BasicAuthPassword);

Here is a simple example exposing this APIs as an http endpoint.

Configuration

Sending data into Pyroscope Cloud

1. Set PYROSCOPE_SERVER_ADDRESS to PYROSCOPE_SERVER_ADDRESS=https://ingest.pyroscope.cloud
2. Go to Pyroscope Cloud API Keys page
3. Copy one of the keys
4. Add it to your .NET profiler configuration: PYROSCOPE_AUTH_TOKEN="psx-..."

Sending data to Phlare with Pyroscope .NET integration

Starting with weekly-f8 you can ingest pyroscope profiles directly to phlare.

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=phlare.dotnet.app
export PYROSCOPE_SERVER_ADDRESS=<URL>
export PYROSCOPE_BASIC_AUTH_USER=<User>
export PYROSCOPE_BASIC_AUTH_PASSWORD=<Password>
export PYROSCOPE_TENANT_ID=<TenantID>

To configure .NET integration to send data to Phlare, replace the <URL> placeholder with the appropriate server URL. This could be the grafana.com Phlare URL or your own custom Phlare server URL.

If you need to send data to grafana.com, you’ll have to configure HTTP Basic authentication. Replace <User> with your grafana.com stack user and <Password> with your grafana.com API key.

If your Phlare server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace <TenantID> with your Phlare tenant ID.