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.

  1. 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.

    1. Open Windows PowerShell as Administrator.
    2. Navigate to the destination directory where the APM agent was provisioned.
    3. Run the following command in PowerShell console:
      Import-Module ./OpenTelemetry.DotNet.Auto.psm1
  2. 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.

  3. 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
  4. Deploy the APM Dotnet agent.

    Deploy the APM Dotnet agent on the following applications:

Deploy on IIS Server

Run the following command on the PowerShell console:
Register-OpenTelemetryForIIS

Deploy on Windows Service

Run the following command on the PowerShell console:
Register-OpenTelemetryForWindowsService -WindowsServiceName <WindowsServiceName>

Deploy on Console Application

Here's information on how to deploy the APM Dotnet agent on Console Application.

  1. 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.

  2. Run the Console Application.
    1. Open a command prompt.

    2. Set the environment variables from step 1 in the command prompt.

    3. 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.

  1. 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.

  2. Configure additional environment variables by running the following script:
    . $OTEL_DOTNET_AUTO_HOME/instrument.sh
  3. Run the application.
    1. Open a shell session.
    2. Set environmental variables from step 1 and step 2 in the shell session.
    3. 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.

  1. Add helm chart repository.
    helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
    helm repo update
  2. Create Kubernetes namespace for OpenTelemetry operator.
    kubectl create namespace opentelemetry-operator-system
  3. 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.

To install the cert manager, run the following:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.1/cert-manager.yaml
To install the OpenTelemetry operator, run the following:
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:

  1. 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:
    The created CR can be queried by running the following command:
    kubectl get otelinst -n opentelemetry-operator-system
    All endpoints and environment variables required to be correct for auto-instrumentation to work properly.
  2. 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:
  3. 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>
  4. 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.