Merge pull request #14139 from DataDog/chrisnas/dotnet-beta-linux

[Profiler] Update .NET documentation for Beta
DataDog · Jun 9, 2022 · e1c200c · e1c200c
2 parents 6724aa3 + 5f64201
commit e1c200c
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 35 deletions.
diff --git a/content/en/tracing/profiler/connect_traces_and_profiles.md b/content/en/tracing/profiler/connect_traces_and_profiles.md
@@ -23,7 +23,7 @@ You can move directly from span information to profiling data on the Code Hotspo
 
 ### Prerequisites
 
-{{< programming-lang-wrapper langs="java,python,go,ruby" >}}
+{{< programming-lang-wrapper langs="java,python,go,ruby,.NET" >}}
 {{< programming-lang lang="java" >}}
 Code Hotspots identification is enabled by default when you [turn on profiling for your service][1]. For manually instrumented code, continuous profiler requires scope activation of spans:
 
@@ -86,6 +86,14 @@ To enable Code Hotspots identification for Go, [turn on profiling for your servi
 [10]: https://go-review.googlesource.com/c/go/+/369741/
 [11]: https://go-review.googlesource.com/c/go/+/369983/
 {{< /programming-lang >}}
+{{< programming-lang lang=".NET" >}}
+
+Code Hotspots identification is enabled by default when you [turn on profiling for your service][1].
+
+Requires tracing library version 2.7.0 or greater.
+
+[1]: /tracing/profiler/enabling/dotnet
+{{< /programming-lang >}}
 {{< /programming-lang-wrapper >}}
 
 ### Link from a span to profiling data

diff --git a/content/en/tracing/profiler/enabling/dotnet.md b/content/en/tracing/profiler/enabling/dotnet.md
@@ -20,49 +20,109 @@ further_reading:
 Datadog .NET Profiler is currently in public beta. Datadog recommends evaluating the profiler in a non-sensitive environment before deploying in production.
 </div>
 
-<br>
-
-## Requirements
+The following profiling features are available:
+- **Method durations** shows the overall time taken by each method from your code.
+- **CPU** shows the time taken executing CPU tasks (see Configuration section to enable it).
+- **Exceptions** shows the type and messages of thrown exceptions (see Configuration section to enable it).
 
-**Supported operating systems:**
 
-- Windows 10
-- Windows Server starting from version 2012
+## Requirements
 
-Continuous Profiler is not supported on serverless platforms, such as AWS Lambda.
+Supported operating systems for .NET Framework
+: Windows 10<br/>
+Windows Server starting from version 2012
 
-**Supported .NET runtimes:**
+Supported operating systems for .NET Core and .NET 5+
+: Linux with glibc 2.18+ (for example CentOS 7 is not supported)<br/>
+Windows 10<br/>
+Windows Server starting from version 2012
 
-64-bit applications running on:
-- .NET Framework 4.6.1+
-- .NET Core 2.1, 3.1
-- .NET 5
-- .NET 6
+Serverless
+: Continuous Profiler is not supported on serverless platforms, such as AWS Lambda.
 
-**Supported languages:**
+Supported .NET runtimes (64-bit applications)
+: .NET Framework 4.6.1+<br/>
+.NET Core 2.1, 3.1<br/>
+.NET 5<br/>
+.NET 6
 
-Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.
+Supported languages
+: Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.
 
 ## Installation
 
 <div class="alert alert-warning">
   <strong>Note:</strong> Datadog's .NET Tracer and Profiler rely on the .NET CLR Profiling API. This API allows only one subscriber (for example, APM). To ensure maximum visibility, run only one APM solution in your application environment.
 </div>
 
-1. If you are already using Datadog, upgrade your agent to version [7.20.2][1]+ or [6.20.2][2]+.
+If you are already using Datadog, upgrade your Agent to version [7.20.2][1]+ or [6.20.2][2]+. The profiler ships together with the tracer, so install it using the following steps, depending on your operating system.
+
+{{< tabs >}}
+
+{{% tab "Linux" %}}
+To install the .NET Profiler machine-wide:
+
+1. Download the latest [.NET Tracer package][1] that supports your operating system and architecture.
+
+2. Run one of the following commands to install the package and create the .NET log directory `/var/log/datadog/dotnet` with the appropriate permissions:
+
+   Debian or Ubuntu
+   : `sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb && /opt/datadog/createLogPath.sh`
 
-2. The profiler ships together with the tracer. Install or upgrade to the latest version, using the [.NET Monitoring MSI installer][3]. Continuous Profiler supports 64-bit Windows, so you need the file like `datadog-dotnet-apm-<VERSION>-x64.msi`.
+   CentOS 8+ or Fedora
+   : `sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && /opt/datadog/createLogPath.sh`
 
-   Run the installer with administrator privileges.
+   Alpine or other musl-based distributions
+   : `sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-musl.tar.gz && sh /opt/datadog/createLogPath.sh`
 
+   Other distributions
+   : `sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-tar.gz && /opt/datadog/createLogPath.sh`
+
+
+[1]: https://github.com/DataDog/dd-trace-dotnet/releases
+{{% /tab %}}
+
+{{% tab "Windows" %}}
+
+1. Install or upgrade to the latest version, using the [.NET Monitoring MSI installer][1]. Continuous Profiler supports 64-bit Windows, so you need the file like `datadog-dotnet-apm-<VERSION>-x64.msi`.
+
+2. Run the installer with administrator privileges.
+
+
+[1]: https://github.com/DataDog/dd-trace-dotnet/releases
+{{% /tab %}}
+
+{{< /tabs >}}
+
+<br>
 <div class="alert alert-warning">
   <strong>Note:</strong> The following steps include setting environment variables to enable the profiler. Datadog <strong>does not recommend</strong> setting those environment variables at machine-level. If set at machine-level, every .NET application running on the machine is profiled and this incurs a significant overhead on the CPU and memory of your machine.
 </div>
 
 {{< tabs >}}
 
+{{% tab "Linux" %}}
+3. Set the following required environment variables for automatic instrumentation to attach to your application:
+
+   ```
+   CORECLR_ENABLE_PROFILING=1
+   CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
+   CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
+   DD_DOTNET_TRACER_HOME=/opt/datadog
+   LD_PRELOAD=/opt/datadog/continuousprofiler/Datadog.Linux.ApiWrapper.x64.so
+   DD_PROFILING_ENABLED=1
+   DD_ENV=production
+   DD_VERSION=1.2.3
+   ```
+
+4. For standalone applications, manually restart the application as you normally would.
+
+5. A minute or two after starting your application, your profiles appear on the [Datadog APM > Profiler page][1].
+
+{{< /tabs >}}
+
 {{% tab "Internet Information Services (IIS)" %}}
-1. Set needed environment variables to configure and enable Profiler. To enable the Profiler for IIS applications, it is required to set the `DD_PROFILING_ENABLED`, `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables in the Registry under <code>HKLM\System\CurrentControlSet\Services\WAS</code> and <code>HKLM\System\CurrentControlSet\Services\W3SVC</code> nodes.
+3. Set needed environment variables to configure and enable Profiler. To enable the Profiler for IIS applications, it is required to set the `DD_PROFILING_ENABLED`, `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables in the Registry under `HKLM\System\CurrentControlSet\Services\WAS` and `HKLM\System\CurrentControlSet\Services\W3SVC` nodes.
 
    **With the Registry Editor:**
 
@@ -91,7 +151,7 @@ Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.
 
    <strong>Note</strong>: the environment variables are applied for <em>all</em> IIS applications. Starting with IIS 10, you can set environment variables for each IIS application in the <a href="https://docs.microsoft.com/en-us/iis/get-started/planning-your-iis-architecture/introduction-to-applicationhostconfig"><code>C:\Windows\System32\inetsrv\config\applicationhost.config</code> file</a>. Read the <a href="https://docs.microsoft.com/en-us/iis/configuration/system.applicationhost/applicationpools/add/environmentvariables/">Microsoft documentation</a> for more details.
 
-2. Completely stop and start IIS by running the following commands as an administrator:
+4. Completely stop and start IIS by running the following commands as an administrator:
 
    ```cmd
    net stop /y was
@@ -102,13 +162,13 @@ Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.
      <strong>Note:</strong> Use <code>stop</code> and <code>start</code> commands. A reset or restart does not always work.
    </div>
 
-3. A minute or two after starting your application, your profiles appear on the [Datadog APM > Profiler page][1].
+5. A minute or two after starting your application, your profiles appear on the [Datadog APM > Profiler page][1].
 
 [1]: https://app.datadoghq.com/profiling
 {{% /tab %}}
 
 {{% tab "Windows services" %}}
-1. Set needed environment variables to configure and enable Profiler. To enable the Profiler for your service, it is required to set the `DD_PROFILING_ENABLED`, `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables in the Registry key associated to the service.
+3. Set needed environment variables to configure and enable Profiler. To enable the Profiler for your service, it is required to set the `DD_PROFILING_ENABLED`, `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables in the Registry key associated to the service.
 
    **With the Registry Editor:**
 
@@ -164,13 +224,13 @@ Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.
    Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\MyService -Name Environment -Value $v
    ```
 
-2. A minute or two after you start your application, your profiles appear on the [Datadog APM > Profiler page][1].
+4. A minute or two after you start your application, your profiles appear on the [Datadog APM > Profiler page][1].
 
 [1]: https://app.datadoghq.com/profiling
 {{% /tab %}}
 
-{{% tab "Standalone applications" %}}
-1. Set needed environment variables to configure and enable Profiler for a non-service application, such as console, ASP.NET (Core), Windows Forms, or WPF. To enable the Profiler for Standalone applications, it is required to set the `DD_PROFILING_ENABLED`, `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables. The recommended approach is to create a batch file that sets these and starts the application, and run your application using the batch file.
+{{% tab "Windows Standalone applications" %}}
+3. Set needed environment variables to configure and enable Profiler for a non-service application, such as console, ASP.NET (Core), Windows Forms, or WPF. To enable the Profiler for Standalone applications, it is required to set the `DD_PROFILING_ENABLED`, `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables. The recommended approach is to create a batch file that sets these and starts the application, and run your application using the batch file.
 
    For .NET Core and .NET 5+:
    ```cmd
@@ -196,30 +256,31 @@ Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.
    REM start the application here
    ```
 
-2. A minute or two after you start your application, your profiles appear on the [Datadog APM > Profiler page][1].
+4. A minute or two after you start your application, your profiles appear on the [Datadog APM > Profiler page][1].
 
 [1]: https://app.datadoghq.com/profiling
 {{% /tab %}}
 {{< /tabs >}}
 
-<br>
 
 ## Configuration
 
 You can configure the profiler using the following environment variables. Note that most of these settings also apply to the Tracer configuration. Restart the application after any of these settings is changed.
 
 | Environment variable                             | Type          | Description                                                                                      |
 | ------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------ |
-| `DD_ENV`                   | String        | The [environment][4] name, for example, `production`. If not set, will be `unspecified-environment` |
-| `DD_SERVICE`               | String        | The [service][4] name, for example, `web-backend`. If this is not specified, the .NET Profiler tries to determine the service name automatically from the application name (process entry assembly or process name).    |
-| `DD_VERSION`               | String        | The [version][4] of your service. If not set, will be `unspecified-version` |
+| `DD_ENV`                   | String        | The [environment][3] name, for example, `production`. If not set, will be `unspecified-environment` |
+| `DD_SERVICE`               | String        | The [service][3] name, for example, `web-backend`. If this is not specified, the .NET Profiler tries to determine the service name automatically from the application name (process entry assembly or process name).    |
+| `DD_VERSION`               | String        | The [version][3] of your service. If not set, will be `unspecified-version` |
 | `DD_TAGS`                  | String        | Tags to apply to an uploaded profile. Must be a list of `<key>:<value>` separated by commas such as: `layer:api,team:intake`.   |
 | `DD_AGENT_HOST`            | String        | Sets the host where profiles are sent (the host running the Agent). Can be a hostname or an IP address. Ignored if `DD_TRACE_AGENT_URL` is set. Defaults to `localhost`.  |
 | `DD_TRACE_AGENT_PORT`      | String        | Sets the port where profiles are sent (the port where the Agent is listening for connections). Ignored if `DD_TRACE_AGENT_URL` is set. Defaults to`8126`.  |
 | `DD_TRACE_AGENT_URL`       | String        | Sets the URL endpoint where profiles are sent. Overrides `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT` if set. Defaults to `http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>`.  |
 | `DD_TRACE_DEBUG`           | Boolean        | Enables or disables debug logging (Could help in case of troubleshooting investigation). Valid values are: `true` or `false`. Defaults to `false`.  |
 | `DD_PROFILING_LOG_DIR`     | String        | Sets the directory for .NET Profiler logs. Defaults to `%ProgramData%\Datadog-APM\logs\`.  |
 | `DD_PROFILING_ENABLED`     | Boolean        | If set to `true`, enables the .NET Profiler. Defaults to `false`.  |
+| `DD_PROFILING_CPU_ENABLED` | Boolean        | If set to `true`, enables the CPU profiling. Defaults to `false`.  |
+| `DD_PROFILING_EXCEPTION_ENABLED` | Boolean        | If set to `true`, enables the Exceptions profiling. Defaults to `false`.  |
 
 <div class="alert alert-warning">
 <strong>Note</strong>: For IIS applications, you must set environment variables in the Registry (under <code>HKLM\System\CurrentControlSet\Services\WAS</code> and <code>HKLM\System\CurrentControlSet\Services\W3SVC</code> nodes) as shown in the <a href="?tab=windowsservices#installation">Windows Service tab, above</a>. The environment variables are applied for <em>all</em> IIS applications.
@@ -230,12 +291,11 @@ Starting with IIS 10, you can set environment variables for each IIS application
 
 ## Further Reading
 
-The [Getting Started with Profiler][5] guide takes a sample service with a performance problem and shows you how to use Continuous Profiler to understand and fix the problem.
+The [Getting Started with Profiler][4] guide takes a sample service with a performance problem and shows you how to use Continuous Profiler to understand and fix the problem.
 
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://app.datadoghq.com/account/settings#agent/overview
 [2]: https://app.datadoghq.com/account/settings?agent_version=6#agent
-[3]: https://github.com/DataDog/dd-trace-dotnet/releases/
-[4]: /getting_started/tagging/unified_service_tagging
-[5]: /getting_started/profiler/
+[3]: /getting_started/tagging/unified_service_tagging
+[4]: /getting_started/profiler/