Download PDF
Download page Auto-Instrumentation Configuration.
Auto-Instrumentation Configuration
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
# ...
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
# ...
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:
|
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:
appNameStrategy
tierName
(optional, will use deployment name by default)
See Application Naming Strategies.
- To instrument which containers are in a multi-container application:
instrumentContainer
containerMatchString
TheinstrumentContainer
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 hostlocalhost
and port9090
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 |
---|---|---|
appNameLabel | N/A | The value of this label will be the AppDynamics application name. |
appNameStrategy | manual | The option to specify a name for the AppDynamics application. You can specify any of these values for this parameter:
See See Application Naming Strategies. |
defaultAnalyticsHost | N/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 |
defaultAnalyticsPort | N/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 The default value is applied to all This parameter is required |
defaultAnalyticsSslEnabled | N/A | This value is based on whether the Analytics Agent port is SSL enabled. If the port is SSL enabled, specify the value as This parameter is required with The default value is applied to all |
| "" | (Required) Application name used by the agent to report to the Controller. |
defaultCustomConfig | N/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 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. |
defaultContainerMatchString | N/A | This is a regex value to choose the containers to instrument. This parameter requires you to use the When the |
| JAVA_TOOL_OPTIONS | This parameter is specific to Java applications. Environment variable to which the - 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 For more information to troubleshoot, see Troubleshoot Re-instrumentation Issues for Upgraded Deployment under Validate Auto-Instrumentation. |
| [ ] | Specific deployment labels marked for instrumentation. This parameter accepts a list of You must match a minimum of one label for instrumentation. For example:
For example, if only |
| .* | Names of deployments targeted for instrumentation. This parameter is used as the default value for the This parameter accepts deployment names as a regular expression or regex. If there are multiple deployments to instrument, you can separate names with a ' By default, this parameter instruments all deployments configured by |
|
CODE
CODE
CODE
| The Docker repository from where the Node.js Agent, .NET Core for Linux, and Java Agent is pulled. Supported values are:
|
| None | The instrumentation method used for instrumenting Apps. Supported values are:
|
|
| Required. This parameter is used to enable auto-instrumentation. |
| "" | 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. |
numberOfTaskWorkers | 2 | 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. |
|
| To configure the Network Visibility App Agent, By default, Supported values are:
|
| 0 | If you configured the application container as a non-root user, provide the group ID (GID) of the corresponding group.
The default |
| 0 | If you configured the application container as a non-root user, provide the user ID (UID) of the corresponding user.
The default |
resourcesToInstrument | Deployment | Cluster Agent instruments the resources that are listed in this parameter. The supported values are:
For example, to instrument
|
InstrumentationRule Properties
This table describes the properties available to configure auto-instrumentation in an InstrumentationRule
.
Parameter Name | Default Value | Description |
---|---|---|
analyticsHost | N/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. |
analyticsPort | N/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 This parameter is required with |
analyticsSslEnabled | N/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 This parameter is required with |
containerMatchString | N/A | This is a regex value to choose the containers with the name that satisfies the value. This parameter requires you to use the When the This parameter overrides the default value specified for |
customAgentConfigSource | N/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.
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. |
| first | This parameter provides an option to choose the container that must be instrumented. You can specify any of these values:
|
language | N/A | The language of the application to be instrumented. These languages are supported:
|
matchString | N/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 |
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: |
appName | <defaultAppName > | Application name used by the Java Agent to report to the Controller. This overrides If no value is provided, then the configured |
appNameLabel | N/A | The value of this label is the AppDynamics application name. |
customAgentConfig | N/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 |
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 If none are provided, it defaults to the |
imageInfo |
CODE
CODE
CODE
| Location of the agent image. You can select one of these properties:
The default value is For the specific language mentioned in this rule, this overrides 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. |
|
| To configure the Network Visibility App Agent, By default, Supported values are:
|
| 0 | If you configured the application container as a non-root user, provide the 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 |
| 0 | If you configured the application container as a non-root user, it provides the 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 |