Deploy the APM Dotnet Agent
On successfully provisioning the APM Dotnet agent, you can deploy the APM Dotnet agent in Windows or Linux.
Deploy the APM Dotnet Agent in Windows
On successfully provisioning the APM Dotnet agent, you can deploy the APM Dotnet agent in Windows.
To deploy the APM Dotnet agent on any application, you need to add a set of environment variables before starting the application.
- Prepare PowerShell.
Before deploying APM Dotnet agent on Windows, you need to prepare PowerShell.
Note
PowerShell version 5.1 or higher is supported.If you have PowerShell version 4.0, you need to update it to 5.1 to proceed.
- Open Windows PowerShell as Administrator.
- Navigate to the destination directory where the APM agent was provisioned.
- Run the following command in PowerShell console:
Import-Module ./OpenTelemetry.DotNet.Auto.psm1
- Prepare environmental variables on PowerShell.Review the following environmental variables that are needed for deploying APM Dotnet agent:
$env:OTEL_EXPORTER_OTLP_ENDPOINT="<data-upload-endpoint>/20200101/opentelemetry" $env:OTEL_EXPORTER_OTLP_HEADERS="Authorization=dataKey <private-data-key>" $env:OTEL_SERVICE_NAME="<service-name>"
Where:- <data-upload-endpoint>: DataUploadEndpoint URL that is generated when the APM domain is created. For information, see Obtain Data Upload Endpoint and Data Keys.
- <private-data-key>: The agent installation key used by APM Dotnet agents (private dataKey) which is generated when the APM domain is created. For information, see Obtain Data Upload Endpoint and Data Keys.
- <service-name>: The name of the service being monitored. This enables you to filter by service and view traces in the Trace Explorer user interface.
Example:$env:OTEL_EXPORTER_OTLP_ENDPOINT="https://aaaaaaaaaaaaaaaaaaaaaa.apm-agt.us-phoenix-1.oci.oraclecloud.com/20200101/opentelemetry" $env:OTEL_EXPORTER_OTLP_HEADERS="Authorization=dataKey CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCB" $env:OTEL_SERVICE_NAME="myservice"
You can add more environment variables if needed. For example, if you need to configure browser agent injection or abridged trace. The environment variable name should use the prefix
$env:
and the environment variable value should be quoted by double quotes""
.Best Practice: Run clear-history after deploying the APM .NET agent. This cleans up sensitive data such as private data key from the PowerShell history.
- Optional - Register .NET Framework DLLs in GAC.
This step is only required by .NET framework applications. If you do not have .NET framework application, skip this step.
To register .NET framework DLLs in GAC, do the following:Register-OpenTelemetryDllsToGac
- Deploy the APM Dotnet agent.
Deploy the APM Dotnet agent on the following applications:
Deploy on IIS Server
Register-OpenTelemetryForIIS
Deploy on Windows Service
Register-OpenTelemetryForWindowsService -WindowsServiceName <WindowsServiceName>
Deploy on Console Application
Here's information on how to deploy the APM Dotnet agent on Console Application.
- Prepare the environment variables to deploy the APM Dotnet agent.
Review the following environment variables that are needed for deploying APM Dotnet agent for console application:
set COR_ENABLE_PROFILING=1 set COR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318} set COR_PROFILER_PATH_64=<destination>\win-x64\OpenTelemetry.AutoInstrumentation.Native.dll set COR_PROFILER_PATH_32=<destination>\win-x86\OpenTelemetry.AutoInstrumentation.Native.dll set CORECLR_ENABLE_PROFILING=1 set CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318} set CORECLR_PROFILER_PATH_64=<destination>\win-x64\OpenTelemetry.AutoInstrumentation.Native.dll set CORECLR_PROFILER_PATH_32=<destination>\win-x86\OpenTelemetry.AutoInstrumentation.Native.dll set DOTNET_ADDITIONAL_DEPS=<destination>\AdditionalDeps set DOTNET_SHARED_STORE=<destination>\store set DOTNET_STARTUP_HOOKS=<destination>\net\OpenTelemetry.AutoInstrumentation.StartupHook.dll set ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=OpenTelemetry.AutoInstrumentation.AspNetCoreBootstrapper set OTEL_DOTNET_AUTO_HOME=<destination> set OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES=OpenTelemetry.ODP set OTEL_SERVICE_NAME=<service-name> set OTEL_LOGS_EXPORTER=none set OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES=dotnet.exe,dotnet set OTEL_EXPORTER_OTLP_ENDPOINT=<data-upload-endpoint>/20200101/opentelemetry set OTEL_EXPORTER_OTLP_HEADERS=Authorization=dataKey <private-data-key> set OTEL_DOTNET_ENABLE_BACKGROUND_ODP=true set OTEL_DOTNET_ENABLE_CONNECTION_ODP=true
The following must be replaced with the correct values:
Placeholder Description <destination> The destination directory in which the APM Dotnet Agent is provisioned. For example: C:\tracer-home
<service-name> The name of the service being monitored. This enables you to filter by service and view traces in the Trace Explorer user interface.
For example: apm_service
<data-upload-endpoint> The dataUploadEndpoint URL that is generated when the APM domain is created. For example: https://dataUploadEndpoint.com
<private-data-key> The agent installation key used by the APM Dotnet agent (private dataKey), which is generated when the APM domain is created. For example: IMWJ5UN2C
Note
For information about the data upload endpoint and private data keys, see Obtain Data Upload Endpoint and Data Keys.
- Run the Console Application.
-
Open a command prompt.
-
Set the environment variables from step 1 in the command prompt.
-
In the same command prompt, run your console application.
-
Deploy the APM Dotnet Agent in Linux
On successfully provisioning the APM Dotnet agent, you can deploy the APM Dotnet agent in Linux.
To deploy the APM Dotnet agent on any application, you need to add a set of environment variables before starting the application.
- Prepare Environmental Variables
To deploy the APM Dotnet agent on any application, you need to set and export variables.
Review and set the following environmental variables that are needed for deploying APM Dotnet agent:export OTEL_DOTNET_AUTO_HOME=<destination> export OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES=OpenTelemetry.ODP export OTEL_SERVICE_NAME=<service-name> export OTEL_LOGS_EXPORTER=none export OTEL_EXPORTER_OTLP_ENDPOINT=<data-upload-endpoint>/20200101/opentelemetry export OTEL_EXPORTER_OTLP_HEADERS="Authorization=dataKey <private-data-key>"
The following must be replaced with the correct values:
Placeholder Description <destination> The destination directory in which the APM Dotnet Agent is provisioned. <service-name> The name of the service being monitored. This enables you to filter by service and view traces in the Trace Explorer user interface.
For example: apm_service
<data-upload-endpoint> The dataUploadEndpoint URL that is generated when the APM domain is created. For example: https://dataUploadEndpoint.com
For information, see Obtain Data Upload Endpoint and Data Keys.
<private-data-key> The agent installation key used by the APM Dotnet agent (private dataKey) which is generated when the APM domain is created. For example: IMWJ5UN
For information, see Obtain Data Upload Endpoint and Data Keys.
- Configure additional environment variables by running the following script:
. $OTEL_DOTNET_AUTO_HOME/instrument.sh
- Run the application.
- Open a shell session.
- Set environmental variables from step 1 and step 2 in the shell session.
- In the same session, run your application.
Deploy the APM Dotnet Agent in Kubernetes using OpenTelemetry Operator
Here's information on how to deploy an APM Dotnet agent using the OpenTelemetry operator to automatically inject and configure the APM Dotnet agent into your Dotnet application pods on Kubernetes (K8s) clusters.
You can use the APM Dotnet agent to monitor Dotnet applications. The OpenTelemetry operator is used to deploy the APM Dotnet agent and is an implementation of a K8s operator providing an easy way to automatically inject Dotnet agents to Dotnet applications running on K8s pods.
Prerequisite
Install the OpenTelemetry Operator into the K8s cluster.
There are three different options available to choose from: Operator helm chart, Operator release manifest or Operator Hub.
In most cases, a cert-manager should be installed. If the helm chart option is used, there is an option to generate a self-signed cert instead.
Option 1: Operator helm chart
This option is to use helm chart to install OpenTelemetry operator.
- Add helm chart
repository.
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts helm repo update
- Create Kubernetes namespace for OpenTelemetry
operator.
kubectl create namespace opentelemetry-operator-system
- Install OpenTelemetry
operator.
helm install opentelemetry-operator open-telemetry/opentelemetry-operator \ --namespace opentelemetry-operator-system \ --set "manager.collectorImage.repository=otel/opentelemetry-collector-k8s"\ --set admissionWebhooks.certManager.enabled=false\ --set admissionWebhooks.autoGenerateCert.enabled=true
Option 2: Operator release manifest
This option is to use YAML files to install OpenTelemetry operator.
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.1/cert-manager.yaml
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
Deploy the APM Dotnet Agent
To deploy the APM Dotnet agent, follow these steps:
- Create a Kubernetes Custom Resource (CR).
To manage automatic instrumentation, the OpenTelemetry Operator needs to be provided with information about the APM Dotnet agent and its configuration which it's done using the Custom Resource Definition (CRD).
This Custom Resource will be used by the operator to copy the agent into the pod and add to it the required configuration.
Run the following command to create the CR on your Kubernetes cluster:
kubectl apply -f - <<EOF apiVersion: opentelemetry.io/v1alpha1 kind: Instrumentation metadata: name: inst-apm-dotnet namespace: opentelemetry-operator-system spec: dotnet: image: us-ashburn-1.ocir.io/idpyjkbcc9tk/apm-net-agent:latest env: - name: OTEL_EXPORTER_OTLP_ENDPOINT value: <data-upload-endpoint>/20200101/opentelemetry - name: OTEL_EXPORTER_OTLP_HEADERS value: "Authorization=dataKey <private-data-key>" - name: OTEL_LOGS_EXPORTER value: "none" - name: OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES value: "OpenTelemetry.ODP" EOF
Where:- <data-upload-endpoint> is the data upload endpoint URL that is generated when the APM domain is created. For information, see Obtain Data Upload Endpoint and Data Keys.
- <private-data-key> is the APM Dotnet agent installation private data key which is generated when the APM domain is created. For information, see Obtain Data Upload Endpoint and Data Keys.
The created CR can be queried by running the following command:
All endpoints and environment variables required to be correct for auto-instrumentation to work properly.kubectl get otelinst -n opentelemetry-operator-system
- Add the Kubernetes annotation.
The OpenTelemetry operator uses Kubernetes annotation to decide which pods should be auto-injected with the APM Dotnet agent.
The annotation can be added to a namespace. In that case, all the pods within that namespace will get injected. The annotation can also be added to individual PodSpec objects, available as part of Deployment, Statefulset, and other resources.
Annotation for x64 glibc:annotations: instrumentation.opentelemetry.io/inject-dotnet: opentelemetry-operator-system/inst-apm-dotnet
Annotation for x64 musl:annotations: instrumentation.opentelemetry.io/inject-dotnet: opentelemetry-operator-system/inst-apm-dotnet instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: linux-musl-x64
To start editing your namespace, do the following:- Run the command:
kubectl edit namespace <your-namespace-name>
- After running the above command, edit the namespace once the editor is
opened. For example, using the
vi
editor. - Add the annotation to the namespace. Keep in mind indentation is very important to make it as a valid YAML file.
See below an example of a namespace with the added annotation:apiVersion: v1 kind: Namespace metadata: labels: kubernetes.io/metadata.name: mynamespace annotations: instrumentation.opentelemetry.io/inject-dotnet: "opentelemetry-operator-system/inst-apm-dotnet" name: mynamespace spec:
- Run the command:
- Restart the Kubernetes pod.
To restart the pod where you want to auto-inject the APM Dotnet agent, run the following:
kubectl delete pod <your-pod-name> -n <your-namespace-name>
- Verify the Kubernetes pod.
To verify that your pod has been auto-injected with the APM Dotnet agent after it was restarted, run the following:
kubectl get pod <your-pod-name> -n <your-namespace-name> -o yaml
You can now go to the next step: Verify APM Dotnet Agent Deployment.