You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Sep 2, 2025. It is now read-only.
:description: A list of pre-checks for the user to complete before installing the .NET automatic instrumentation.
9
+
10
+
Before installing the .NET automatic instrumentation, complete the following pre-checks.
11
+
12
+
Verify platform compatibility
13
+
=============================
14
+
15
+
Make sure that your platform is compatible with the OpenTelemetry Collector. See the following table for action items corresponding to your platform:
16
+
17
+
.. list-table::
18
+
:widths: 25 75
19
+
:width: 100
20
+
:header-rows: 1
21
+
22
+
* - Platform
23
+
- Pre-checks
24
+
* - All platforms
25
+
- * Verify that you are using a supported processor architecture. See :ref:`dotnet-otel-requirements`.
26
+
* - Kubernetes
27
+
- * Verify that you are using a supported Kubernetes distribution. See :ref:`helm-chart-supported-distros`.
28
+
29
+
* Review the prerequisites and requirements for installing the instrumentation using the Helm chart. See :new-page:`Auto-instrumentation <https://github.com/signalfx/splunk-otel-collector-chart/blob/d08f989180bcb0e1ec79b63805d8951472b8d230/docs/auto-instrumentation-install.md#steps-for-setting-up-auto-instrumentation>` in the Splunk OpenTelemetry Collector for Kubernetes repository on GitHub.
30
+
31
+
Verify .NET runtime compatibility
32
+
=================================
33
+
34
+
Verify that you are using a supported version of .NET. See :ref:`dotnet-otel-versions`.
35
+
36
+
Verify automatic discovery compatibility
37
+
========================================
38
+
39
+
Make sure that your platform is compatible with automatic discovery. See the following table for details:
40
+
41
+
.. list-table::
42
+
:widths: 25 75
43
+
:width: 100
44
+
:header-rows: 1
45
+
46
+
* - Platform
47
+
- Pre-check
48
+
* - Kubernetes
49
+
- Verify automatic discovery compatibility for Kubernetes. See :ref:`Automatic discovery and configuration for back-end applications in Kubernetes <k8s-backend-requirements>`.
50
+
* - Linux
51
+
- Verify automatic discovery compatibility for Linux. See :ref:`linux-backend-auto-discovery`.
52
+
* - Windows
53
+
- Verify automatic discovery compatibility for Windows. See :ref:`windows-backend-auto-discovery`.
54
+
55
+
Review core dependencies
56
+
========================
57
+
58
+
Make sure that your application's dependencies are compatible with the .NET instrumentation.
59
+
60
+
#. Verify whether your target applications have the same dependencies as the automatic instrumentation. See :new-page:`OpenTelemetry.AutoInstrumentation <https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/src/OpenTelemetry.AutoInstrumentation/OpenTelemetry.AutoInstrumentation.csproj>` and :new-page:`OpenTelemetry.AutoInstrumentation.AdditionalDeps <https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/src/OpenTelemetry.AutoInstrumentation.AdditionalDeps/Directory.Build.props>`. If there are conflicts, consider installing using the NuGet packages. Otherwise, you must resolve all the dependencies before manually installing the instrumentation.
61
+
62
+
#. Verify whether your target applications have the same dependencies as the NuGet packages. See the :new-page:`NuGet dependencies <https://www.nuget.org/packages/OpenTelemetry.AutoInstrumentation/#dependencies-body-tab>` in the NuGet documentation. If there are conflicts, you must resolve them before installing the instrumentation using the NuGet packages.
63
+
64
+
Review supported libraries
65
+
==========================
66
+
67
+
Make sure that your target application uses supported libraries. Complete the following steps:
68
+
69
+
#. Review the list of automatically instrumented libraries supported by the Splunk distribution of the OpenTelemetry .NET instrumentation. See :ref:`supported-dotnet-otel-libraries`.
70
+
71
+
#. Review the community-supported extended list of automatically instrumented libraries in the OpenTelemetry Ecosystem. See the :new-page:`OpenTelemetry Registry <https://opentelemetry.io/ecosystem/registry/?language=dotnet&component=instrumentation>`.
72
+
73
+
Verify networking requirements
74
+
==============================
75
+
76
+
Verify that your platform is configured according to the following networking requirements:
77
+
78
+
.. list-table::
79
+
:widths: 25 75
80
+
:width: 100
81
+
:header-rows: 1
82
+
83
+
* - Platform
84
+
- Pre-check
85
+
* - All platforms
86
+
- Verify that your firewall rules allow for communication with the elected Splunk Observability Cloud instance.
87
+
* - Kubernetes
88
+
- Verify that the manager nodes have access to worker nodes on port ``9443/tcp``.
@@ -9,10 +9,124 @@ Instrument your .NET application for Splunk Observability Cloud (OpenTelemetry)
9
9
10
10
The Splunk Distribution of OpenTelemetry .NET automatically instruments .NET applications, Windows services running .NET applications, and ASP.NET applications deployed on IIS.
11
11
12
-
To get started, use the guided setup, follow the instructions manually, or automatically instrument your application. See :ref:`discovery_mode` for more information.
12
+
You can install the .NET instrumentation manually or using the NuGet packages. The manual instructions include the option to use a guided setup. The NuGet packages are the best method for avoiding dependency version conflicts, but are not well-suited for instrumenting multiple applications running on the same machine. Review the :ref:`pre-checks <dotnet-pre-checks>` and the various installation procedures on this page to identify the best installation method for your application environment.
13
+
14
+
.. _otel-dotnet-nuget-pkg:
15
+
16
+
Install the OpenTelemetry .NET instrumentation using the NuGet packages
You can deploy the Splunk Distribution of the OpenTelemetry .NET instrumentation automatically using the official NuGet packages. Your instrumented application project must support NuGet packages.
20
+
21
+
NuGet package installation considerations
22
+
-----------------------------------------
23
+
24
+
The following scenarios are ideal for using the NuGet packages:
25
+
26
+
* You control the application build but not the machine or container where the application is running.
27
+
* You're instrumenting a self-contained application. See :new-page:`Publish self-contained <https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained>` in the .NET documentation.
28
+
* You want to facilitate developer experimentation with automatic instrumentation through NuGet packages.
29
+
* You need to solve version conflicts between the dependencies used by the application and the automatic instrumentation.
30
+
31
+
Don't use the NuGet packages if any of the following apply to your environment:
32
+
33
+
* You're unable to add the NuGet packages to the application project. This can be the case when instrumenting a third-party application.
34
+
* You can't accommodate the increased disk use required by installing the NuGet packages separately for each instrumented application running on the same machine.
35
+
* You need to instrument a legacy application that can't be migrated to the SDK-style project. To verify whether your project is SDK style, see `Identify the project format <https://learn.microsoft.com/en-us/nuget/resources/check-project-format>`__ in the NuGet documentation.
36
+
37
+
If your scenario isn't compatible with NuGet package installation, install the distribution manually. See :ref:`otel-dotnet-manual-install`.
38
+
39
+
.. note::
40
+
41
+
For advanced configuration of the .NET automatic instrumentation, such as changing trace propagation formats or changing the endpoint URLs, see :ref:`advanced-dotnet-otel-configuration`.
42
+
43
+
Instrument your application using the NuGet packages
If the build fails and prompts you to add missing instrumentation packages, add the instrumentation package or skip the instrumentation of the listed package by adding it to the ``SkippedInstrumentation`` property. For example:
To distribute the appropriate native runtime components with your .NET application, specify a Runtime Identifier (RID) to build the application using ``dotnet build`` or ``dotnet publish``. For more information, see :new-page:`.NET RID Catalog <https://learn.microsoft.com/en-us/dotnet/core/rid-catalog>` in the .NET documentation.
71
+
72
+
Both self-contained and framework-dependent applications are compatible with automatic instrumentation. See :new-page:`.NET application publishing overview <https://learn.microsoft.com/en-us/dotnet/core/deploying/>` in the .NET documentation for more information.
73
+
74
+
Run the instrumented application
75
+
--------------------------------
76
+
77
+
The instrumentation procedure in the previous section produces launch scripts in the output folder of the build. The Windows script is ``splunk-launch.cmd`` and the Linux script is ``splunk-launch.sh``. The script passes all the command-line parameters that you provide to the application. Use the following steps to run your instrumented application:
78
+
79
+
#. Identify the launch script in your build output.
80
+
81
+
#. (Optional) If you want to verify that the instrumentation is working by viewing the telemetry data output in your console, set the following environment variables to ``true``:
You can deploy the Splunk Distribution of OpenTelemetry .NET instrumentation manually, using either the guided setup or the step-by-step instructions below.
105
+
106
+
Manual installation considerations
107
+
----------------------------------
108
+
109
+
The following scenarios are ideal for manually installing the .NET instrumentation:
110
+
111
+
* You're unable to add the NuGet packages to the application project. This can be the case when instrumenting a third-party application.
112
+
* You can't accommodate the increased disk use required by installing the NuGet packages separately for each instrumented application running on the same machine.
113
+
* You need to instrument a legacy application that can't be migrated to the SDK-style project. To verify whether your project is SDK style, see `Identify the project format <https://learn.microsoft.com/en-us/nuget/resources/check-project-format>`__ in the NuGet documentation.
114
+
115
+
Consider using the NuGet packages if any of the following apply to your environment:
116
+
117
+
* You control the application build but not the machine or container where the application is running.
118
+
* You're instrumenting a self-contained application. See :new-page:`Publish self-contained <https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained>` in the .NET documentation.
119
+
* You want to facilitate developer experimentation with automatic instrumentation through NuGet packages.
120
+
* You need to solve version conflicts between the dependencies used by the application and the automatic instrumentation.
121
+
122
+
To install the distribution using the official NuGet packages, see :ref:`otel-dotnet-nuget-pkg`.
123
+
124
+
.. note::
125
+
126
+
For advanced configuration of the .NET automatic instrumentation, such as changing trace propagation formats or changing the endpoint URLs, see :ref:`advanced-dotnet-otel-configuration`.
13
127
14
128
Generate customized instructions using the guided setup
To generate all the basic installation commands for your environment and application, use the .NET OpenTelemetry guided setup. To access the .NET OpenTelemetry guided setup, follow these steps:
18
132
@@ -25,21 +139,16 @@ To generate all the basic installation commands for your environment and applica
25
139
#. Select the :guilabel:`APM` product.
26
140
#. Select the :guilabel:`.NET (OpenTelemetry)` tile to open the .NET OpenTelemetry guided setup.
27
141
28
-
Install the Splunk Distribution of OpenTelemetry .NET manually
If you don't use the guided setup, follow these instructions to manually install the Splunk Distribution of OpenTelemetry .NET:
32
148
33
149
- :ref:`install-dotnet-otel-instrumentation`
34
150
- :ref:`configure-otel-dotnet`
35
151
36
-
To install the distribution using the official NuGet packages, see :ref:`otel-dotnet-nuget-pkg`.
37
-
38
-
.. _install-dotnet-otel-instrumentation:
39
-
40
-
Instrument your .NET application
41
-
---------------------------------------------
42
-
43
152
Use the following steps to automatically instrument your application.
44
153
45
154
.. warning::
@@ -52,7 +161,7 @@ Use the following steps to automatically instrument your application.
52
161
* ``DOTNET_EnableDiagnostics_Debugger=0``
53
162
54
163
Windows
55
-
^^^^^^^^^^^^
164
+
^^^^^^^
56
165
57
166
#. Check that you meet the requirements. See :ref:`dotnet-otel-requirements`.
58
167
@@ -180,7 +289,7 @@ If no data appears in APM, see :ref:`common-dotnet-otel-troubleshooting`.
180
289
.. note:: If you need to add custom attributes to spans or want to manually generate spans and metrics, instrument your .NET application or service manually. See :ref:`dotnet-otel-manual-instrumentation`.
181
290
182
291
Linux
183
-
^^^^^^^^^^^^^^^^^
292
+
^^^^^
184
293
185
294
#. Check that you meet the requirements. See :ref:`dotnet-otel-requirements`.
186
295
@@ -216,7 +325,7 @@ If no data appears in APM, see :ref:`common-dotnet-otel-troubleshooting`.
216
325
.. _activate-profiling-dotnet-otel:
217
326
218
327
Activate AlwaysOn Profiling
219
-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
328
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
220
329
221
330
To activate AlwaysOn Profiling, set the ``SPLUNK_PROFILER_ENABLED`` environment variable to ``true``.
222
331
@@ -238,64 +347,6 @@ Starting from version 1.4.0, the .NET OTel instrumentation collects database que
238
347
239
348
SQL statements might contain sensitive information. To configure this behavior, see ``OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT`` and ``OTEL_DOTNET_AUTO_ENTITYFRAMEWORKCORE_SET_DBSTATEMENT_FOR_TEXT`` in :ref:`dotnet-otel-instrumentation-settings`.
240
349
241
-
242
-
.. _otel-dotnet-nuget-pkg:
243
-
244
-
Install the OpenTelemetry .NET instrumentation using the NuGet packages
You can deploy the Splunk Distribution of OpenTelemetry .NET instrumentation automatically through the official NuGet packages. The project of your instrumented application must support NuGet packages.
248
-
249
-
Use the NuGet package in the following scenarios:
250
-
251
-
1. You control the application build but not the machine or container where the application is running.
252
-
2. You're instrumenting a self-contained application. See :new-page:`Publish self-contained <https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained>` in the .NET documentation.
253
-
3. You want to facilitate developer experimentation with automatic instrumentation through NuGet packages.
254
-
4. You need to solve version conflicts between the dependencies used by the application and the automatic instrumentation.
255
-
256
-
Instrument your application using the NuGet packages
To automatically instrument your application using the NuGet packages, add the ``Splunk.OpenTelemetry.AutoInstrumentation`` package to your project. For example:
If the build fails and prompts you to add missing instrumentation packages, add the instrumentation package or skip the instrumentation of the listed package by adding it to the ``SkippedInstrumentation`` property. For example:
To distribute the appropriate native runtime components with your .NET application, specify a Runtime Identifier (RID) to build the application using ``dotnet build`` or ``dotnet publish``.
280
-
281
-
Both self-contained and framework-dependent applications are compatible with automatic instrumentation. See :new-page:`.NET application publishing overview <https://learn.microsoft.com/en-us/dotnet/core/deploying/>` in the .NET documentation for more information.
0 commit comments