This page describes the properties available in the cluster-agent.yaml and the Helm values.yaml file that you can use to configure auto-instrumentation.

Configuration Structure for Auto-Instrumentation

The structure of the auto-instrumentation configuration is based on a set of default properties, which you can override by using properties defined in one or more instrumentationRules.

apiVersion: cluster.appdynamics.com/v1alpha1
kind: Clusteragent
metadata:
  name: k8s-cluster-agent
  namespace: appdynamics
spec:
  # cluster agent properties
  # ...
  # required to enable auto-instrumentation
  instrumentationMethod: Env 
  # default auto-instrumentation properties
  # may be overridden in an instrumentationRule
  nsToInstrumentRegex: dev|stage|prod
  image: "docker.io/appdynamics/java-agent:21.7.0"
  # ...
  # one or more instrumentationRules
  instrumentationRules:
    - nsToInstrumentRegex: dev
      imageInfo:
        image: "docker.io/appdynamics/java-agent:21.3.1"
        agentMountPath: /opt/appdynamics
        imagePullPolicy: Always
      # ...
    - nsToInstrumentRegex: stage
      imageInfo:
        image: "docker.io/appdynamics/java-agent:21.5.0"
        agentMountPath: /opt/appdynamics
        imagePullPolicy: Always
      # ...
YML 
deploymentMode: MASTER

# cluster agent properties
# ...
clusterAgent:
  nsToMonitorRegex: .*
# ...
# Instrumentation config
instrumentationConfig:
  enabled: true
  # required to enable auto-instrumentation
  instrumentationMethod: Env 
  # default auto-instrumentation properties
  # may be overridden in an instrumentationRule
  nsToInstrumentRegex: dev|stage|prod
  image: "docker.io/appdynamics/java-agent:21.7.0"
  # ...
  # one or more instrumentationRules
  instrumentationRules:
    - nsToInstrumentRegex: dev
      imageInfo:
        image: "docker.io/appdynamics/java-agent:21.3.1"
        agentMountPath: /opt/appdynamics
        imagePullPolicy: Always
      # ...
    - nsToInstrumentRegex: stage
      imageInfo:
        image: "docker.io/appdynamics/java-agent:21.5.0"
        agentMountPath: /opt/appdynamics
        imagePullPolicy: Always
      # ...
YML

Overriding Default Properties with InstrumentationRules

The Cluster Agent uses a combination of namespaceRegex, matchString, and labelMatch properties in an InstrumentationRule to target Deployments, DeploymentConfigs and StatefulSets in a namespace for auto-instrumentation. The first matching InstrumentationRule is used. If no matching rule is found, then the default properties are used to determine if auto-instrumentation should be applied:

  • nsToInstrumentRegex
  • defaultInstrumentationLabelMatch
  • defaultInstrumentMatchString

For example, the following InstrumentationRule with -matchString "<string>" is added to the Cluster Agent configuration file:

instrumentationRules:
    - matchString: "<string>"

You must have a deployment for auto-instrumentation to work.

If the deployment name matches this string, then the remaining properties under the matching instrumentationRule are applied and will override any default properties that are set. If the string does not match, then the Cluster Agent defaults to the properties nsToInstrumentRegex, defaultInstrumentationLabelMatch, and defaultInstrumentMatchString to determine the instrumentation rules.

Common Auto-Instrumentation Tasks

These properties are available to support common auto-instrumentation configuration tasks:

  • To set the namespaces that are in scope for auto-instrumentation:

    • nsToInstrument
    • nsToInstrumentRegex
  • (Optional) To filter and target the set of applications within a namespace that are in scope for auto-instrumentation:
    • instrumentationMatchString
    • labelMatch
  • To assign an application and tier name to an instrumented application:
  • To instrument which containers are in a multi-container application:
    • instrumentContainer
    • containerMatchString

      The instrumentContainer default is to instrument the first container based on the ordering returned by the Kubernetes API.
  • If transaction analytics is required for Node.js applications, then specify the analytics host and port:
    • analyticsHost
      analyticsPort

      See Deploy Analytics Without the Analytics Agent. Configuration of transaction analytics is not required for .NET and Java applications. You can deploy the Analytics Agent using the sidecar model where you add an Analytics Agent container to each application pod, and then start/stop with the application container. If you use the sidecar approach, the App Server Agent uses the default host localhost and port 9090 and connects automatically. No additional configuration is required. See Install Agent Side Components in Kubernetes.

Default Auto-Instrumentation Properties

This table describes the default properties available to configure auto-instrumentation, defined in the cluster-agent.yaml spec:

Parameter Name

Default Value

Description

appNameLabelN/AThe value of this label will be the AppDynamics application name. 
appNameStrategymanual

The option to specify a name for the AppDynamics application. You can specify any of these values for this parameter:

  • manual
  • namespace
  • label

See See Application Naming Strategies.

defaultAnalyticsHostN/A

The hostname of the Analytics Agent.

This parameter is required if you require the Node.js Agent or the .NET Core Agent to send the default transaction data to the Analytics Agent.

The default value is applied to all the instrumented resources unless it is overwritten by the instrumentationRules configuration.

defaultAnalyticsPortN/A

The listening port for Analytics Agent.

For example, if the Analytics Agent is listening on port 9090, then the value of this parameter is 9090.

The default value is applied to all the instrumented resources unless it is overwritten by the instrumentationRules configuration.

This parameter is required along with defaultAnalyticsHost if you require the Node.js or the .NET Core Agent to send the default transaction data to the Analytics Agent.

defaultAnalyticsSslEnabledN/A

This value is based on whether the Analytics Agent port is SSL enabled. If the port is SSL enabled, specify the value as true; else, specify as false.

This parameter is required with defaultAnalyticsPort and defaultAnalyticsHost, if you require the Node.js or the .NET Core Agent, to send the default transaction data to the Analytics Agent.

The default value is applied to all the instrumented resources unless it is overwritten by the instrumentationRules configuration.

defaultAppName

""(Required) Application name used by the agent to report to the Controller.
defaultCustomConfigN/A

This parameter is specific to Java applications.

You can add any custom system property if your application framework requires any specific configuration for instrumentation.

This value is appended to the env or defaultEnv variable as configured with other Java Agent properties. 

When you upgrade your deployment using Helm, you can use this parameter instead of defaultEnv to avoid re-instrumentation issues. See Troubleshoot Re-instrumentation Issues for Upgraded Deployment under Validate Auto-Instrumentation.

defaultContainerMatchStringN/A

This is a regex value to choose the containers to instrument. This parameter requires you to use the select option within the instrumentContainer (specified in the instrumentation rules).

When the select option is used with this parameter, Cluster Agent instruments the containers that match the regex value.

defaultEnv

JAVA_TOOL_OPTIONS

This parameter is specific to Java applications.

Environment variable to which the -javaagent argument and App Agent system properties are added.

You can override this variable to use any other environment variable best suited for the deployment.

However, if you override this value for upgrading the deployment, Cluster Agent does not re-instrument. This happens because both Java Agent and the deployment uses JAVA_TOOL_OPTIONS environment variable. Therefore, when you override this during an upgrade, the annotations do not get updated and re-instrumentation fails.

For more information to troubleshoot, see Troubleshoot Re-instrumentation Issues for Upgraded Deployment under Validate Auto-Instrumentation.

defaultInstrumentationLabelMatch


[ ]

Specific deployment labels marked for instrumentation.

This parameter accepts a list of key-value pairs to instrument.

You must match a minimum of one label for instrumentation.

For example:

defaultInstrumentationLabelMatch:
- label1: value1

- label1: value2

- label2: value2

For example, if only label1: value2 matches, then the instrumentation works as expected.

defaultInstrumentMatchString

.*

Names of deployments targeted for instrumentation.

This parameter is used as the default value for the matchstring parameter that is specified within instrumentationRules. If matchstring is not specified, then Cluster Agent uses this parameter value.

This parameter accepts deployment names as a regular expression or regex.

If there are multiple deployments to instrument, you can separate names with a '|' without spaces.

By default, this parameter instruments all deployments configured by nsToInstrumentRegex. Therefore, if there is no value specified for matchString in the instrumentation rules and if you do not specify any value for this parameter, then Cluster Agent instruments every deployment.

imageInfo

java:
  image: "docker.io/appdynamics/java-      agent:latest"
  agentMountPath: "/opt/appdynamics"
  imagePullPolicy: "IfNotPresent"
CODE 
dotnetcore:
    image: "docker.io/appdynamics/dotnet-core-agent:latest"
    agentMountPath: /opt/appdynamics
    imagePullPolicy: "IfNotPresent"
CODE 
nodejs:
 image: "docker.io/appdynamics/nodejs-agent:20.8.0-stretch-slimv14"
 agentMountPath: /opt/appdynamics
 imagePullPolicy: "IfNotPresent"
CODE

The Docker repository from where the Node.js Agent, .NET Core for Linux, and Java Agent is pulled.

Supported values are:

  • image: Location of the agent image, along with its tag/version.
  • agentMountPath: Location of image artifacts in the image file system. The default is /opt/appdynamics. 
    You must change this configuration if the path is different.
    imagePullPolicy: The pull policy required for the agent's docker image. You can choose one of these pull policies based on your requirement:

      • Always

      • IfNotPresent

      • Never

    This parameter is used in the init containers that are added during auto-instrumentation.

instrumentationMethod

None

The instrumentation method used for instrumenting Apps.

Supported values are:

  • None: Instrumentation is disabled.
  • Env: Attach the instrumentation properties to the container environment variables. If a value is not set, the instrumentation will not start.

instrumentationRules

[ ]

Required. This parameter is used to enable auto-instrumentation.
This includes the list of specific instrumentation rules. You can apply the rules to one or more namespaces, and can filter on deployment names and labels. Instrumentation rules are granular to support targeting specific deployments.

See Cluster Agent Configuration for Instrumentation Rules.

nsToInstrumentRegex

""

Required. If you do not specify a value, auto-instrumentation will not work.

Specify the namespaces to be instrumented as a regex.

If there are multiple namespaces to instrument, separate namespaces using "|" without spaces.

By default, namespaces are not instrumented.

numberOfTaskWorkers2

To configure the rate limit for the number of deployments that are auto-instrumented at the same time.

Increasing this value may lead to a larger number of concurrent pod restarts in the cluster.

netvizInfo

bciEnabled: true

port: 3892


To configure the Network Visibility App Agent, netviz, you must deploy a Network Agent separately and set this parameter.
See Install Infrastructure Visibility with the Kubernetes CLI on how to install the Network Agent.

By default, netviz is enabled. In the absence of a Network Agent, this property does not have any impact.
You can enable or disable the netviz Agent.

Supported values are:

  1. bciEnabled: Boolean flag denoting whether netviz is enabled.
  2. port: The port the Network Agent is listening on (default is 3892). Override this value only when running the Network Agent on a port other than the default port.

runAsGroup

0

If you configured the application container as a non-root user, provide the group ID (GID) of the corresponding group.

runAsGroup is used to set the appropriate file permission on the agent artifacts.

The default runAsGroup value is applied to all the instrumented resources, unless it is overwritten by the instrumentationRules configuration.

runAsUser

0

If you configured the application container as a non-root user, provide the user ID (UID) of the corresponding user.

runAsUser is used to set the appropriate file permission on the agent artifacts.

The default runAsUser value is applied to all the instrumented resources unless it is overwritten by instrumentationRules configuration.

resourcesToInstrumentDeployment

Cluster Agent instruments the resources that are listed in this parameter. The supported values are:

  • Deployment
  • StatefulSet
  • DeploymentConfig

For example, to instrument Deployments and StatefulSets, configure:

resourcesToInstrument:

- Deployment
- StatefulSet

InstrumentationRule Properties

This table describes the properties available to configure auto-instrumentation in an InstrumentationRule.

Parameter Name

Default Value

Description

analyticsHostN/A

The hostname of the Analytics Agent.

This parameter is required if you require the Node.js Agent or the .NET Core Agent to send the default transaction data to the Analytics Agent.

analyticsPortN/A

The listening port for Analytics Agent.

For example, if the Analytics Agent is listening on port 9090, then the value of this parameter is 9090.

This parameter is required with defaultAnalyticsHost if you require the Node.js or the .NET Core Agent to send the default transaction data to the Analytics Agent.

analyticsSslEnabledN/A

This value is based on whether the Analytics Agent port is SSL enabled. If the port is not SSL enabled, specify the value as false.

This parameter is required with defaultAnalyticsPort and defaultAnalyticsHost if you require the Node.js or the .NET Core Agent to send the default transaction data to the Analytics Agent.

containerMatchStringN/A

This is a regex value to choose the containers with the name that satisfies the value. This parameter requires you to use the select option within defaultInstrumentContainer or instrumentContainer.

When the select option is used with this parameter, Cluster Agent instruments the containers that match the regex value.

This parameter overrides the default value specified for defaultContainerMatchString.

customAgentConfigSourceN/A

This parameter provides an option to use the custom configuration of the instrumenting agents through ConfigMaps. This parameter requires that you create the required ConfigMaps in the Cluster Agent namespace. This parameter is dynamically configurable from the Cluster Agent YAML file. The changes that you make in the YAML file are updated to all the instrumented agents without restarting the application. Similarly, the changes that you make to the configuration in the ConfigMap is updated to all the instrumented agents without restarting the application.

  • configMapName: Specify the name of the ConfigMap. This allows the agent to use the same custom ConfigMap to update all the instrumented agent namespace.
  • subDir: (Required for Java Agent) Specify the relative path where the ConfigMaps are mounted.
    For example: /ver20.8.0.3686/conf
    , where 20.8.0.3686 is the version of the Java Agent. This directory may differ based on the Java Agent version.
    See Example 6.
    The absolute mount path for the ConfigMap is <agent home path>/subDir
    This ConfigMap replaces any ConfigMap of the same name in the target application's namespace.

If you need to remove a ConfigMap file (used in the rules) from your deployment, then you must first remove this parameter from the Cluster Agent YAML file, and then remove the ConfigMap from the Cluster Agent's namespace.

instrumentContainer

first

This parameter provides an option to choose the container that must be instrumented. You can specify any of these values:

  • first: This is the default value. When you specify this value, Cluster Agent instruments the first container in the pod.
  • all: When you specify this value, Cluster Agent instruments all the containers in the pod.
  • select: When you specify this value, Cluster Agent instruments only those containers with the name that matches a regex specified in the defaultContainerMatchString parameter or the containerMatchString parameter.
languageN/A

The language of the application to be instrumented.

These languages are supported:

  • dotnetcore
  • java
  • nodejs
matchStringN/A

Regular expression to match on deployment name on which the rule applies.

If you do not specify a value for this parameter, then the Cluster Agent uses the value specified in the defaultInstrumentMatchString, and instruments all the deployments that satisfy the value.

labelMatch{}A list of key-value pairs of labels to include in this rule. It is sufficient to match any one of the labels.

For example:
labelMatch:
-label1: value1
-label1: value2
-label2: value2
If only label1: value2 matches, then instrumentation works as expected.

appName<defaultAppName>

Application name used by the Java Agent to report to the Controller. This overrides defaultAppName.

If no value is provided, then the configured defaultAppName is used.

appNameLabelN/AThe value of this label is the AppDynamics application name. 
customAgentConfigN/A

This parameter is specific to Java applications.

You can add any custom system property if your application framework requires any specific configuration for instrumentation.
This value takes precedence over the default value specified in the defaultCustomConfig parameter.

This value is appended to the env or defaultEnv variable as configured with other Java Agent properties.

tierName""

Tier name used by the Java Agent to report to the Controller.

If no tier name is provided, then the deployment name is used as the default.

env""

This parameter is specific to Java applications.

Environment variable to which the App Agent system properties will be added. When specified, this overrides defaultEnv for the deployments matching this instrumentation rule.

If none are provided, it defaults to the defaultEnv (if configured), or to the default env JAVA_TOOL_OPTIONS (if not configured at the default cluster level).

imageInfo
image:  "docker.io/appdynamics/java-agent:latest"
agentMountPath: "/opt/appdynamics"
imagePullPolicy: "IfNotPresent"
CODE 
dotnetcore:
image: "docker.io/appdynamics/dotnet-core-agent:latest"
    agentMountPath: /opt/appdynamics
imagePullPolicy: "IfNotPresent"
CODE 
nodejs:
 image: "docker.io/appdynamics/nodejs-agent:20.8.0-stretch-slimv14"
 agentMountPath: /opt/appdynamics
imagePullPolicy: "IfNotPresent"
CODE

Location of the agent image. You can select one of these properties:

  • image: Location of the agent image, and its tag/version.
  • agentMountPath: Location of image artifacts in the image file system. The default is /opt/appdynamics. This configuration is required only if the path differs from the default path.
  • imagePullPolicy: The pull policy required for the agent's Docker image. The default is IfNotPresent. You can choose one of these pull policies based on your requirement:
    • Always
    • IfNotPresent
    • Never
    This parameter is used in the init containers that are added during auto-instrumentation.

The default value is IfNotPresent.

For the specific language mentioned in this rule, this overrides image-info for the deployments matching this instrumentation rule.

You must configure this if you want to override the default cluster-level configuration and use a custom agent version for this specific rule selection.

netvizInfo

bciEnabled: true

port: 3892


To configure the Network Visibility App Agent, netviz, you must deploy a Network Agent separately and set this parameter.
See Install Infrastructure Visibility with the Kubernetes CLI to install the Network Agent.

By default, netviz is enabled. This property has no impact without a Network Agent.
You can enable or disable the netviz Agent.

Supported values are:

  1. bciEnabled: Boolean flag denoting whether netviz is enabled or not.
  2. port: The port the Network Agent is listening on (default is 3892). Override this value only when running the Network Agent on a port other than the default port.

runAsGroup

0

If you configured the application container as a non-root user, provide the groupId of the corresponding group.

This sets the appropriate file permission on the agent artifacts.

This value is applied to all the instrumented resources.

Add this parameter, if you require to override the default value of runAsGroup that is configured for default instrumentation, or if you require a specific value for the resources that satisfy this rule.

runAsUser

0

If you configured the application container as a non-root user, it provides the userId of the corresponding user.

This sets the appropriate file permission on the agent artifacts.

This value is applied to all the instrumented resources.

Add this parameter, if you require to override the default value of runAsUser that is configured for default instrumentation, or if you require a specific value for the resources that satisfy this rule.