Upgrade the .NET Agent for Linux

This page describes how to upgrade the .NET Agent for Linux on VMs such as Docker and on hardware running Linux.

Upgrading the .NET Agent for Linux updates the agent files and maintains legacy configurations.

.NET Agent for Linux 21.5 

.NET Agent for Linux 21.5 incorporates significant architectural changes to accelerate the development of missing features in the Linux Agent relative to .NET Agent for Windows. 

These architectural changes do not affect .NET Agent for Windows (MSI and Microservices).

Generally, .NET Agent for Linux 21.5 maintains parity with existing features in .NET Agent for Linux < 21.5. However, due to architectural updates, there are differences between .NET Agent for Linux >= 21.5 and .NET Agent for Linux < 21.5. See the .NET Agent 21.5 release notes for a detailed explanation.

Before you upgrade to .NET Agent for Linux 21.5, please review the differences in this table:

Difference	.NET Agent for Linux >= 21.5	.NET Agent for Linux < 21.5
Pre-built Docker Image	The .NET Agent Docker image does not have an OS Layer after version 21.5. This allows copying agent binaries from shared volume for initContainer, Kubernetes. initContainer for Kubernetes does not need a base OS.	The .NET Agent Docker image does have an OS Layer before version 21.5.
HTTP URL backend for: Default naming	.NET Agent uses the full URL including http://host:port in the naming. Full URL address is used. For example, two calls to these addresses: http://service.cisco.com/api/add/12  http://service.cisco.com/api/add/32  Results with these two backend names: http://service.cisco.com/api/add/12 http://service.cisco.com/api/add/32	.NET Agent uses the URI path of the URL for the naming. It excludes http://host:port, but assumes the "/" prefix as the name. Uses the URI path prefixed with a "/". For example, two calls to these addresses: http://service.cisco.com/api/add/12  http://service.cisco.com/api/add/32  Results with these two backend names: /api/add/12 /api/add/32
HTTP URL backend for: Custom naming	.NET Agent uses the full URL including http://host:port in the naming. The URL address split by "/" counts http://host:port as the first three segments: "http:" "" "host:port" For example, two calls to these addresses with first five URL segments using "/" as the split and merge delimiter: http://service.cisco.com/api/add/12  http://service.cisco.com/api/add/32  Results with one backend name: http://service.cisco.com/api/add	.NET Agent uses the URI path of the URL for the naming. It excludes http://host:port, but assumes the "/" prefix as the name. The URL address split by "/" counts segments starting from the prefixed "/" in the URI path. For example, two calls to these addresses with first three URL segments using "/" as the split and merge delimiter: http://service.cisco.com/api/add/12  http://service.cisco.com/api/add/32  Results with one backend name: /api/add
Sensitive data filtering for environment variables	To filter sensitive data for environment variables: Add this sensitive data filter to the AppDynamicsConfig.json configuration file (located next to the Agent DLL file): { "applies-to": "environment-variables", "match-type": "CONTAINS", "match-pattern": "" } JSON To integrate this filter with the Agent configuration file, see Filter Sensitive Data with the .NET Agent.	Available using the APPDYNAMICS_AGENT_MASK_ENV_VARS environment variable with the Linux Agent.
Process identity	Not available	Available
In-process async call chain segments limit	5 per node (default)	10 per node (default)
POCO definitions for the generic format changes any existing generic method POCO definitions and must be re-defined using the new format. Similar to POCO definitions, the new format applies to any similar definitions for Custom Exits, Custom Data collectors, and so on because their support is enabled in the .NET Agent for Linux.	This shows the common format used to define generic POCO rules for all .NET Agents: Format class: GenericClass`2 method: GenericMethod<T1,T2>(T1,T2,T1,T2)	This shows the common format used to define generic POCO rules for all .NET Agents: Format class: GenericClass`2 method: GenericMethod(!T1,!T2,!!M1,!!M2)
Alpine 3.9 and 3.10	Not supported	Supported
Analytics Agent connection configuration through the AppDynamicsConfig.json configuration file or through the APPDYNAMICS_ANALYTICS_* environment variables.	Not supported Use the single environment variable appdynamics.analytics.agent.url to specify the full Analytics Agent URL, such as http://localhost:9090/v2/sinks/bt.	Supported
Analytics Agent SSL trust configuration in JSON or agent specific environment variables.	Not supported The SSL connection works if the certificate used by the Analytics Server is trusted by the operating system. As a workaround, you can configure the certificate using the SSL_CERT_FILE/SSL_CERT_DIR environment variable. This is a global setting that overrides your SSL configuration for all connections.	Supported with these environment variables: APPDYNAMICS_CONTROLLER_SSL_CERTFILE APPDYNAMICS_CONTROLLER_SSL_CERTDIR
Usage of multiple Base-64 encoded certificates (PEM) in a single file with APPDYNAMICS_CONTROLLER_SSL_CERTFILE.	Supported with these noted limitations: The multiple certificates (PEM) file cannot be greater than 1 Mb. You must format each certificate file with a decorated header and a footer, and the first line in the file should be the header of the first certificate. if any certificate fails to load, then the entire file is ignored and the feature is disabled.	Supported

Requirements

• Before you begin, review the Release Notes for changes that affect your environment.

• AppDynamics requires an account access key for agent connections to single-tenant Controller accounts. AppDynamics < 4.1 only requires an account access key for multi-tenant Controller accounts.

  Single-tenant Controller customers can find the account access key in the Controller under Settings > License > Account. 

  

  You must be a member of a role with the View License account level permission. See Manage Custom Roles for Cisco AppDynamics.

Binaries Overview

After downloading the agent binaries, you must extract them from the zip file into the folder you want.

The folder should contain these files: 

• AppDynamics.Agent.netstandard.dll
• libappdprofiler.so
• libappdprofiler_glibc.so
• libappdprofiler_musl.so

Upgrade the .NET Agent for Linux

1. Unzip the .NET Agent for Linux installation package to a temporary directory.

2. Replace the existing agent binaries with their latest versions. The files to replace are: 

   • libappdprofiler.so 

   • AppDynamics.Agent.netstandard.dll

3. Copy these files to the same directory:

   • libappdprofiler_glibc.so


   • libappdprofiler_musl.so


4. Restart your application, or rebuild and then run your container image with the new versions of the agent binaries.

Upgrade the .NET Agent for Linux - Using Init Containers for Versions > 21.5.0

.NET core agent images do not have OS layer for version >= 21.5.0. The cp command used with older images will not work and the deployment spec needs to be updated. 

To update the deployment, see Add the Init Container to the Deployment Spec. 

Upgrade the .Net Agent for Linux - Using DockerFile with Prebuilt Agent Image for Versions > 21.5.0

.NET core agent images for versions >= 21.5.0  do not contain the OS Layer. 

To copy the agent Dynamic-link library (DLL), view the example Docker file: 

FROM mcr.microsoft.com/dotnet/core/sdk:3.1 AS build-env
WORKDIR /app

# Copy csproj and restore as distinct layers
COPY *.csproj ./
RUN dotnet restore

# Copy everything else and build
COPY . ./
RUN dotnet publish -c Release -o out

#  Appdynamics dotnet core agent image (same image can be used for Debian and Alpine distributions)
FROM appdynamics/dotnet-core-agent:21.5.1 AS agent

FROM mcr.microsoft.com/dotnet/core/aspnet:3.1
WORKDIR /app
COPY --from=build-env /app/out .
COPY --from=agent /opt/appdynamics /opt/appdynamics

# Mandatory settings required to attach the agent to the .NET application
ENV CORECLR_PROFILER={57e1aa68-2229-41aa-9931-a6e93bbc64d8}
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER_PATH=/opt/appdynamics/libappdprofiler.so
 
# Configure connection to the controller
ENV APPDYNAMICS_CONTROLLER_HOST_NAME=<<Controller Host>>
ENV APPDYNAMICS_CONTROLLER_PORT=80
ENV APPDYNAMICS_CONTROLLER_SSL_ENABLED=false
ENV APPDYNAMICS_AGENT_ACCOUNT_NAME=<<Account name>>
ENV APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY=<<Access Key>>
ENV APPDYNAMICS_PREVIEW_FEATURE_ENABLED=true

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

EXPOSE 80
ENTRYPOINT ["dotnet", "Sample.dll"]