Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: language SDK page updates #2851

Merged
merged 11 commits into from
Dec 15, 2023
Merged

docs: language SDK page updates #2851

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
090fe9e
docs changes
petethepig Dec 14, 2023
a49e208
improvements
petethepig Dec 15, 2023
618af88
wip
petethepig Dec 15, 2023
80fb225
fixes
petethepig Dec 15, 2023
1042954
fixes
petethepig Dec 15, 2023
7b8fc80
fixes
petethepig Dec 15, 2023
f7e72f7
Update docs/sources/configure-client/language-sdks/go_push.md
knylander-grafana Dec 15, 2023
bda9d7e
Merge branch 'main' into sdk-docs
knylander-grafana Dec 15, 2023
6a1b6d5
Update docs/sources/configure-client/language-sdks/go_push.md
knylander-grafana Dec 15, 2023
0871062
Apply suggestions from code review
knylander-grafana Dec 15, 2023
fbd69e0
Update Before you begin sections
knylander-grafana Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions docs/sources/configure-client/language-sdks/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,46 +13,46 @@ The following languages SDKs provide support for sending profiles from your appl

<table>
<tr>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/go_push"><img src="https://user-images.githubusercontent.com/23323466/178160549-2d69a325-56ec-4e19-bca7-d460d400b163.png" width="100px;" alt=""/><br />
<td align="center"><a href="./go_push"><img src="https://user-images.githubusercontent.com/23323466/178160549-2d69a325-56ec-4e19-bca7-d460d400b163.png" width="100px;" alt=""/><br />
<b>Golang</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/go_push" title="Documentation">Documentation</a><br />
<a href="./go_push" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/golang-push" title="golang-examples">Examples</a>
</td>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/java"><img src="https://user-images.githubusercontent.com/23323466/178160550-2b5a623a-0f4c-4911-923f-2c825784d45d.png" width="100px;" alt=""/><br />
<td align="center"><a href="./java"><img src="https://user-images.githubusercontent.com/23323466/178160550-2b5a623a-0f4c-4911-923f-2c825784d45d.png" width="100px;" alt=""/><br />
<b>Java</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/java" title="Documentation">Documentation</a><br />
<a href="./java" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/java/rideshare" title="java-examples">Examples</a>
</td>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/python"><img src="https://user-images.githubusercontent.com/23323466/178160553-c78b8c15-99b4-43f3-a2a0-252b6c4862b1.png" width="100px;" alt=""/><br />
<td align="center"><a href="./python"><img src="https://user-images.githubusercontent.com/23323466/178160553-c78b8c15-99b4-43f3-a2a0-252b6c4862b1.png" width="100px;" alt=""/><br />
<b>Python</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/python" title="Documentation">Documentation</a><br />
<a href="./python" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/python" title="python-examples">Examples</a>
</td>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/ruby"><img src="https://user-images.githubusercontent.com/23323466/178160554-b0be2bc5-8574-4881-ac4c-7977c0b2c195.png" width="100px;" alt=""/><br />
<td align="center"><a href="./ruby"><img src="https://user-images.githubusercontent.com/23323466/178160554-b0be2bc5-8574-4881-ac4c-7977c0b2c195.png" width="100px;" alt=""/><br />
<b>Ruby</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/ruby" title="Documentation">Documentation</a><br />
<a href="./ruby" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/ruby" title="ruby-examples">Examples</a>
</td>
</tr>
<tr>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/nodejs"><img src="https://user-images.githubusercontent.com/23323466/178160551-a79ee6ff-a5d6-419e-89e6-39047cb08126.png" width="100px;" alt=""/><br />
<td align="center"><a href="./nodejs"><img src="https://user-images.githubusercontent.com/23323466/178160551-a79ee6ff-a5d6-419e-89e6-39047cb08126.png" width="100px;" alt=""/><br />
<b>NodeJS</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/nodejs" title="Documentation">Documentation</a><br />
<a href="./nodejs" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/nodejs/express" title="examples">Examples</a>
</td>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/dotnet"><img src="https://user-images.githubusercontent.com/23323466/178160544-d2e189c6-a521-482c-a7dc-5375c1985e24.png" width="100px;" alt=""/><br />
<td align="center"><a href="./dotnet"><img src="https://user-images.githubusercontent.com/23323466/178160544-d2e189c6-a521-482c-a7dc-5375c1985e24.png" width="100px;" alt=""/><br />
<b>Dotnet</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/dotnet" title="Documentation">Documentation</a><br />
<a href="./dotnet" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/dotnet" title="examples">Examples</a>
</td>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/ebpf/"><img src="https://user-images.githubusercontent.com/23323466/178160548-e974c080-808d-4c5d-be9b-c983a319b037.png" width="100px;" alt=""/><br />
<b>eBPF</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/ebpf/" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/ebpf" title="examples">Examples</a>
</td>
<td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/rust"><img src="https://user-images.githubusercontent.com/23323466/178160555-fb6aeee7-5d31-4bcb-9e3e-41e9f2f7d5b4.png" width="100px;" alt=""/><br />
<td align="center"><a href="./rust"><img src="https://user-images.githubusercontent.com/23323466/178160555-fb6aeee7-5d31-4bcb-9e3e-41e9f2f7d5b4.png" width="100px;" alt=""/><br />
<b>Rust</b></a><br />
<a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/rust" title="Documentation">Documentation</a><br />
<a href="./rust" title="Documentation">Documentation</a><br />
<a href="https://github.com/grafana/pyroscope/tree/main/examples/rust/rideshare" title="examples">Examples</a>
</td>
</tr>
Expand Down
79 changes: 59 additions & 20 deletions docs/sources/configure-client/language-sdks/dotnet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,53 @@ aliases:

# .NET

## Supported platforms
Our .NET Profiler is a powerful tool designed to enhance the performance analysis and optimization of .NET applications. It seamlessly integrates with Pyroscope, offering real-time insights into the resource usage and bottlenecks within your .NET codebase. This integration empowers developers to pinpoint inefficiencies, improve application speed, and ensure resource-efficient operation.

| Spy Name | Type | Linux | macOS | Windows | Docker |
|:------------:|:------------:|:-----:|:-----:|:-------:|:------:|
| dotnetspy | `embedded` | ✅ | | | |
### Supported Profiling Types

## Supported .NET versions:
- .NET 6.0
- .NET 7.0
The .NET Profiler supports the following profiling types:

## How to add .NET profiling to your application
* CPU
* Wall time
* Allocations
* Lock contention
* Exceptions

### Compatibility

Our .NET profiler works with the following .NET versions:
* .NET 6
* .NET 7
* .NET 8


## Before you Begin

### Set Up a Pyroscope Server

To capture and analyze profiling data, set up a Pyroscope server. This can be:

* A **local server** for development, or
* A **remote server** for production use.

For installation instructions, see our [Get Started]({{< relref "../../get-started/" >}}) guide.


### Using Grafana Cloud Profiles

Grafana Cloud Profiles is a hosted Pyroscope service. It provides a fully managed Pyroscope server, so you don't have to worry about installing and maintaining your own server. It also provides a hosted Grafana instance for visualizing your profiling data. For more information, see [Grafana Cloud Profiles](/products/cloud/profiles-for-continuous-profiling/).

<!-- TODO: add a section like "Learn more about reading flamegraphs and using our product" once it's ready -->

## Configure the Dotnet client

1. Obtain `Pyroscope.Profiler.Native.so` and `Pyroscope.Linux.ApiWrapper.x64.so` from the [latest tarball](https://github.com/pyroscope-io/pyroscope-dotnet/releases/):

```bash
curl -s -L https://github.com/grafana/pyroscope-dotnet/releases/download/v0.8.14-pyroscope/pyroscope.0.8.14-glibc-x86_64.tar.gz | tar xvz -C .
```
Or copy them from the [latest docker image](https://hub.docker.com/r/pyroscope/pyroscope-dotnet/tags):

Or copy them from the [latest docker image](https://hub.docker.com/r/pyroscope/pyroscope-dotnet/tags). We have `glibc` and `musl` versions:
```dockerfile
COPY --from=pyroscope/pyroscope-dotnet:0.8.14-glibc /Pyroscope.Profiler.Native.so ./Pyroscope.Profiler.Native.so
COPY --from=pyroscope/pyroscope-dotnet:0.8.14-glibc /Pyroscope.Linux.ApiWrapper.x64.so ./Pyroscope.Linux.ApiWrapper.x64.so
Expand All @@ -43,20 +72,27 @@ CORECLR_PROFILER_PATH=Pyroscope.Profiler.Native.so
LD_PRELOAD=Pyroscope.Linux.ApiWrapper.x64.so
```

&nbsp;

## Managed helper
### .NET Profiler API

With a managed helper you can interact with the Pyroscope profiler from .NET.
With a managed helper you can interact with the Pyroscope profiler from .NET runtime. You can add labels, turn on/off profiling types, and more.

First, add the Pyroscope dependency:
To use it, first, add the Pyroscope dependency:

```shell
dotnet add package Pyroscope
```

## How to add profiling labels to .NET applications
&nbsp;

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

It is possible to add labels to the profiling data. These labels can be used to filter the data in the UI. Common labels include things like:
* `hostname`
* `region`
* `team`
* `api_endpoint`

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

Expand Down Expand Up @@ -88,7 +124,7 @@ Pyroscope.LabelsWrapper.Do(labels, () =>
});
```

## Dynamic profiling control
### Dynamic control

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

Expand All @@ -112,7 +148,7 @@ Pyroscope.Profiler.Instance.SetContentionTrackingEnabled(enabled);
Pyroscope.Profiler.Instance.SetExceptionTrackingEnabled(enabled);
```

It is possible to dynamically change authorization credentials.
It is possible to dynamically change authorization credentials:

```cs
// Set Basic authorization username and password. Clears any previous authorization credentials.
Expand All @@ -121,7 +157,7 @@ Pyroscope.Profiler.Instance.SetBasicAuth(basicAuthUser, BasicAuthPassword);

Here is a simple [example](https://github.com/grafana/pyroscope/blob/main/examples/dotnet/rideshare/example/Program.cs) exposing this APIs as an http endpoint.

## Configuration
### Configuration Options

| ENVIRONMENT VARIABLE | Type | DESCRIPTION |
|----------------------------------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------|
Expand All @@ -138,7 +174,9 @@ Here is a simple [example](https://github.com/grafana/pyroscope/blob/main/exampl
| PYROSCOPE_BASIC_AUTH_PASSWORD | String | For HTTP Basic Authentication, use this to send profiles to authenticated server, for example Grafana Cloud |
| PYROSCOPE_TENANT_ID | String | Only needed if using multi-tenancy in Pyroscope. |

## Sending data to Pyroscope OSS or Grafana Cloud Profiles with .NET SDK
## Send data to Pyroscope OSS or Grafana Cloud Profiles

To send profiling data from your .NET application, configure your environment for either Pyroscope OSS or Grafana Cloud Profiles using the following steps:

```bash
export CORECLR_ENABLE_PROFILING=1
Expand All @@ -148,6 +186,7 @@ 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.
Expand All @@ -156,6 +195,6 @@ export PYROSCOPE_BASIC_AUTH_PASSWORD=<Password>

To configure the .NET SDK to send data to Grafana Cloud Profiles or Pyroscope, replace the `<URL>` placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you'll have to configure HTTP Basic authentication. Replace `<User>` with your Grafana Cloud stack user and `<Password>` with your Grafan Cloud API key.
If you need to send data to Grafana Cloud, you'll have to configure HTTP Basic authentication. Replace `<User>` with your Grafana Cloud stack user and `<Password>` with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you'll need to configure a tenant ID. Replace `<TenantID>` with your Pyroscope tenant ID.
If your open source Pyroscope server has multi-tenancy enabled, you'll need to specify a tenant ID. Replace `<TenantID>` with your Pyroscope tenant ID.
37 changes: 29 additions & 8 deletions docs/sources/configure-client/language-sdks/go_push.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,39 @@ aliases:

# Go (push mode)

Pyroscope uses the standard `runtime/pprof` package to collect profiling data. Refer to
[the official documentation](https://golang.org/doc/diagnostics#profiling) for details.
Our Go Profiler is a cutting-edge tool designed to optimize Golang applications. By integrating with Pyroscope, it offers developers an in-depth view of their Go codebase, enabling real-time performance analysis. This powerful tool is crucial for pinpointing inefficiencies, streamlining code execution, and ensuring peak performance in Go applications.

## How to add Golang profiling to your application
Pyroscope uses the standard `runtime/pprof` package to collect profiling data. Refer to [the official documentation](https://golang.org/doc/diagnostics#profiling) for details.


## Before you Begin

### Set Up a Pyroscope Server

To capture and analyze profiling data, set up a Pyroscope server. This can be:

* A **local server** for development, or
* A **remote server** for production use.

For installation instructions, see our [Get Started]({{< relref "../../get-started/" >}}) guide.


### Using Grafana Cloud Profiles

Grafana Cloud Profiles is a hosted Pyroscope service. It provides a fully managed Pyroscope server, so you don't have to worry about installing and maintaining your own server. It also provides a hosted Grafana instance for visualizing your profiling data. For more information, see [Grafana Cloud Profiles](/products/cloud/profiles-for-continuous-profiling/).

<!-- TODO: add a section like "Learn more about reading flamegraphs and using our product" once it's ready -->


## Configure the Go client

To start profiling a Go application, you need to include our go module in your app:

```
go get github.com/grafana/pyroscope-go
```

Note: If you'd prefer to use Pull mode you can do so using the Grafana Agent.
Note: If you'd prefer to use Pull mode you can do so using the [Grafana Agent](../grafana-agent/).

Then add the following code to your application:

Expand Down Expand Up @@ -68,7 +89,7 @@ func main() {
}
```

## How to add profiling labels to Golang applications
### Add profiling labels to your application

It is possible to add tags (labels) to the profiling data. These tags can be used to filter the data in the UI. We have a custom API that's in line with the go-native pprof api:

Expand All @@ -83,7 +104,7 @@ pprof.Do(context.Background(), pprof.Labels("controller", "slow_controller"), fu
})
```

## Mutex Profiling
### Mutex Profiling

Mutex profiling is useful for finding sources of contention within your application. It helps you to find out which mutexes are being held by which goroutines.

Expand All @@ -95,7 +116,7 @@ runtime.SetMutexProfileFraction(rate)

`rate` parameter controls the fraction of mutex contention events that are reported in the mutex profile. On average 1/rate events are reported.

## Block Profiling
### Block Profiling

Block profiling lets you analyze how much time your program spends waiting on the blocking operations such as:

Expand All @@ -112,7 +133,7 @@ runtime.SetBlockProfileRate(rate)

`rate` parameter controls the fraction of goroutine blocking events that are reported in the blocking profile. The profiler aims to sample an average of one blocking event per rate nanoseconds spent blocked.

## Sending data to Pyroscope OSS or Grafana Cloud Profiles using Golang SDK
## Send data to Pyroscope OSS or Grafana Cloud Profiles

```go
pyroscope.Start(pyroscope.Config{
Expand Down
Loading
Loading