You are browsing documentation for an outdated plugin version.
This plugin is not enabled by default. Click here for instructions to enable it
- Package install: Set plugins=bundled,app-dynamics in kong.conf before starting Kong
- Docker: Set KONG_PLUGINS=bundled,app-dynamics in the environment
- Kubernetes: Set KONG_PLUGINS=bundled,app-dynamics using these instructions
Looking for the plugin's configuration parameters? You can find them in the AppDynamics configuration reference doc.
This plugin integrates Kong with the AppDynamics APM platform so that proxy requests handled by Kong can be identified and analyzed in AppDynamics.
The plugin reports request and response timestamps and error information to the AppDynamics platform to be analyzed in the AppDynamics flow map and correlated with other systems participating in handling application API requests.
Prerequisites
Before using the plugin, download and install the AppDynamics C/C++ Application Agent and SDK on the machine or within the container running Kong Gateway.
Platform support
The AppDynamics C SDK supports Linux distributions based on glibc 2.5+. Kong Gateway must be running on a glibc-based distribution like RHEL, CentOS, Debian, or Ubuntu to support this plugin.
The AppDynamics C/C++ SDK does not support the following:
- MUSL-based distributions like the Alpine distribution, which is popular for container usage
- ARM64 architecture
See the AppDynamics C/C++ SDK Supported Environments document for more information.
Installation
To use the AppDynamics plugin in Kong Gateway, the AppDynamics C/C++
SDK must be installed on all nodes running Kong Gateway. Due to licensing restrictions, the SDK is
not distributed with Kong Gateway. AppDynamics
must be downloaded from the
AppDynamics Download Portal.
The libappdynamics.so
shared
library file is the only required file.
Recommended installation
If you are using Kong Gateway 3.0.0.0 or later, we recommended installing the libappdynamics.so
in the /usr/local/kong/lib
directory.
This directory is included in the Kong Gateway search path for shared libraries, so the libappdynamics.so
file will be found automatically.
Alternative installation
If you are using an older version of Kong Gateway, or if you prefer to install the libappdynamics.so
file in a different location, you can do so.
- If Kong Gateway is deployed in RHEL or CentOS, the
libappdynamics.so
file can be in the/usr/lib64
directory, which is included in the default search path for shared libraries. - If Kong Gateway is deployed in Debian or Ubuntu, the
libappdynamics.so
file can be in the/usr/lib
directory, which is included in the default search path for shared libraries. - If above options are not available, the
libappdynamics.so
file can be in one of the locations configured by the system’s shared library loader. - Alternatively, the
LD_LIBRARY_PATH
environment variable can be set to the directory containing thelibappdynamics.so
file when starting Kong Gateway.
Configuration
The AppDynamics plugin is configured through environment variables that need to be set when Kong Gateway is started. The environment variables used by the plugin are shown in the table below.
If an environment variable listed in the table does not have a
default
value, you must set the value for that variable, or the plugin may not operate correctly.
The AppDynamics plugin makes use of the AppDynamics C/C++ SDK to send information to the AppDynamics controller. Refer to the AppDynamics C/C++ SDK documentation for more information about the configuration parameters.
Environment variables
Variable | Description | Type | Default |
---|---|---|---|
KONG_APPD_CONTROLLER_HOST |
Hostname of the AppDynamics controller. | String | |
KONG_APPD_CONTROLLER_PORT |
Port number to use to communicate with the controller. | Integer | 443 |
KONG_APPD_CONTROLLER_ACCOUNT |
Account name to use with controller. | String | |
KONG_APPD_CONTROLLER_ACCESS_KEY |
Access key to use with the AppDynamics controller. | String | |
KONG_APPD_LOGGING_LEVEL |
Logging level of the AppDynamics SDK agent. | Integer | 2 |
KONG_APPD_LOGGING_LOG_DIR |
Directory into which agent log files are written. | String | /tmp/appd |
KONG_APPD_TIER_NAME |
Tier name to use for business transactions. | String | |
KONG_APPD_APP_NAME |
Application name to report to AppDynamics. | String | Kong |
KONG_APPD_NODE_NAME |
Node name to report to AppDynamics. This value defaults to the system’s hostname. | String | hostname |
KONG_APPD_INIT_TIMEOUT_MS |
Maximum time to wait for a controller connection when starting, in milliseconds. | Integer | 5000 |
KONG_APPD_CONTROLLER_USE_SSL |
Use SSL encryption in controller communication. true , on , or 1 are all interpreted as True , any other value is considered false . |
Boolean | on |
KONG_APPD_CONTROLLER_HTTP_PROXY_HOST |
Hostname of proxy to use to communicate with controller. | String | |
KONG_APPD_CONTROLLER_HTTP_PROXY_PORT |
Port number of controller proxy. | Integer | |
KONG_APPD_CONTROLLER_HTTP_PROXY_USERNAME |
Username to use to identify to proxy. This value is a string that is never shown in logs. This value can be specified as a vault reference. | String | |
KONG_APPD_CONTROLLER_HTTP_PROXY_PASSWORD |
Password to use to identify to proxy. This value is a string that is never shown in logs. This value can be specified as a vault reference. | String | |
KONG_APPD_CONTROLLER_CERTIFICATE_FILE |
Path to a self-signed certificate file. For example, /etc/kong/certs/ca-certs.pem . |
String | |
KONG_APPD_CONTROLLER_CERTIFICATE_DIR |
Path to a certificate directory. For example, /etc/kong/certs/ . |
String |
Possible values for the KONG_APPD_LOGGING_LEVEL
parameter
The KONG_APPD_LOGGING_LEVEL
environment variable is a numeric value that controls the desired logging level.
Each value corresponds to a specific level:
Value | Name | Description |
---|---|---|
0 | TRACE |
Reports finer-grained informational events than the debug level that may be useful to debug an application. |
1 | DEBUG |
Reports fine-grained informational events that may be useful to debug an application. |
2 | INFO |
Default log level. Reports informational messages that highlight the progress of the application at coarse-grained level. |
3 | WARN |
Reports on potentially harmful situations. |
4 | ERROR |
Reports on error events that may allow the application to continue running. |
5 | FATAL |
Fatal errors that prevent the agent from operating. |
Agent logging
The AppDynamics agent sorts log information into separate, independent of Kong, log files.
By default, log files are written to the /tmp/appd
directory.
This location can be changed by setting the KONG_APPD_LOGGING_LOG_DIR
environment variable.
If problems occur with the AppDynamics integration, inspect the AppDynamics agent’s log files in addition to the Kong Gateway logs.
AppDynamics node name considerations
The AppDynamics plugin defaults the KONG_APPD_NODE_NAME
to the local
host name, which typically reflects the container ID of the containerized
application. Multiple instances of the AppDynamics agent must use
different node names, and one agent must exists for each of Kong Gateway’s
worker processes, the node name is suffixed by the worker ID. This
results in multiple nodes being created for each Kong Gateway
instance, one for each worker process.