Install the .NET Agent for Linux

Related pages:

Getting Started

Before you begin, review these prerequisites:

Confirm you have access to a compatible Controller. See Agent and Controller Compatibility.
Confirm the connection settings to the Controller where your agent will report data:
- If you use a SaaS Controller, AppDynamics sent you the Controller host in your Welcome Email. Use port 443 for HTTPS or port 80 for HTTP.
- If you use an on-premises Controller, you supplied the host and port during installation.
Verify you have access to the machine where the application runs as a user account with privileges to install the agent software and restart the application.
Verify that the machine where the application runs can connect to the Controller. Proxies or firewalls on the network between the agent and Controller may require additional configuration.
Verify that the application environment meets the requirements on prior to running the agent. See .NET Supported Environments.

Applications and Licenses Overview

Ensure you have these applications and licenses:

.NET Core application running on Linux
.NET license for each .NET Core application running on Linux. See Observe License Usage.

Binaries Overview

Download the agent binaries from the AppDynamics Download Site and then extract them from the zip file into the desired folder.

The archive contains these files:

AppDynamics.Agent.netstandard.dll
libappdprofiler.so
libappdprofiler_glibc.so
libappdprofiler_musl.so
README.md

You must extract all four of the agent binaries from the zip file.

Deployment

There are two options for starting your deployment using Docker:

Create Your Own Image, start your agent from scratch
Run an Existing Image, if you already have the .NET Agent enabled

Create Your Own Image

You can use the ASP.NET sample application from Microsoft and a Dockerfile to build your own image and get started:

Download the binaries.
Update the Dockerfile variables to configure the connection to the Controller and your application identity in AppDynamics.
Create the Docker image.

This is an example Dockerfile with commented instructions:

FROM mcr.microsoft.com/dotnet/core/samples:aspnetapp

####### Requirements
# Have the following files alongside the Dockerfile:
# * libappdprofiler.so
# * AppDynamics.Agent.netstandard.dll

####### Instructions
# Building image: docker build --rm -t appdynamicstest:latest .
# Running container: docker run --rm -p 8000:80 appdynamicstest:latest
# Open the application using http://localhost:8000/

# Copy agent binaries to the image from current folder
RUN mkdir -p /opt/appdynamics/dotnet
ADD libappdprofiler.so /opt/appdynamics/dotnet/
ADD libappdprofiler_glibc.so /opt/appdynamics/dotnet/
ADD libappdprofiler_musl.so /opt/appdynamics/dotnet/
ADD AppDynamics.Agent.netstandard.dll /opt/appdynamics/dotnet/

# Mandatory settings required to attach the agent to the .NET application
ENV CORECLR_PROFILER={57e1aa68-2229-41aa-9931-a6e93bbc64d8} \
    CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER_PATH=/opt/appdynamics/dotnet/libappdprofiler.so

# Configure connection to the controller
ENV APPDYNAMICS_CONTROLLER_HOST_NAME=controller.saas.appdynamics.com
ENV APPDYNAMICS_CONTROLLER_PORT=443
ENV APPDYNAMICS_CONTROLLER_SSL_ENABLED=true
ENV APPDYNAMICS_AGENT_ACCOUNT_NAME=account-name
ENV APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY=access-key

# Configure application identity in AppDynamics
ENV APPDYNAMICS_AGENT_APPLICATION_NAME="My Application"
ENV APPDYNAMICS_AGENT_TIER_NAME="Sample Tier"
ENV APPDYNAMICS_AGENT_REUSE_NODE_NAME=true
ENV APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX="Instance"

# It is possible to configure .NET agent using AppDynamicsConfig.json configuration file instead of environment variables
# ADD AppDynamicsConfig.json /opt/appdynamics/dotnet/

CODE

Alpine OS:

Applications running on Alpine require an additional mandatory environment variable, LD_LIBRARY_PATH, such as ENV LD_LIBRARY_PATH=/opt/appdynamics/dotnet.

Run an Existing Image

You can run an existing image with an agent enabled. This is the simplest way to start because it does not require building a new image:

Download the aforementioned binaries.
Update the Docker command variables to configure the connection to the Controller and your application identity in AppDynamics.
Run the command in the desired folder where you extracted the agent binaries from the zip file.
You can replace $(pwd) in the command with this folder.

This example runs the sample application. It assumes you have AppDynamics binaries in the current directory:

Example command to run existing image with .NET agent enabled

docker run \
-p 8000:80 \
-e CORECLR_PROFILER={57e1aa68-2229-41aa-9931-a6e93bbc64d8} \
-e CORECLR_ENABLE_PROFILING=1 \
-e CORECLR_PROFILER_PATH=/opt/appdynamics/dotnet/libappdprofiler.so \
-e APPDYNAMICS_CONTROLLER_HOST_NAME=controller.saas.appdynamics.com \
-e APPDYNAMICS_CONTROLLER_PORT=443 \
-e APPDYNAMICS_CONTROLLER_SSL_ENABLED=true \
-e APPDYNAMICS_AGENT_ACCOUNT_NAME=account-name \
-e APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY=access-key \
-e APPDYNAMICS_AGENT_APPLICATION_NAME="My Application" \
-e APPDYNAMICS_AGENT_TIER_NAME="Sample Tier" \
-e APPDYNAMICS_AGENT_REUSE_NODE_NAME=true \
-e APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX="Instance" \
-v "$(pwd)":/opt/appdynamics/dotnet/ \
mcr.microsoft.com/dotnet/core/samples:aspnetapp

BASH

On Alpine OS

Applications running on Alpine require an additional mandatory environment variable, LD_LIBRARY_PATH, such as -e LD_LIBRARY_PATH=/opt/appdynamics/dotnet \

The command mounts agent files as a volume and sets environment variables required for the agent to attach.

Startup Flow

During the application startup, the AppDynamics agent writes messages to the console as well as the application and .NET framework.

This .NET Agent startup console output indicates proper agent initialization:

appd.agent.profiler(Info): ...

CODE

See .NET Agent for Linux Troubleshooting.