This plugin is not enabled by default. Click here for instructions to enable it ⬇️
- Package install: Set plugins=bundled,AppDynamics in kong.conf before starting Kong
- Docker: Set KONG_PLUGINS=bundled,AppDynamics in the environment
- Kubernetes: Set KONG_PLUGINS=bundled,AppDynamics using these instructions
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+. MUSL-based distributions like the Alpine distribution, which is popular for container usage, are not supported. Kong Gateway must be running on a glibc-based distribution like RHEL, CentOS, Debian, or Ubuntu to support this plugin.
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, it must be placed 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 the libappdynamics.so
file when
starting Kong Gateway.
If the AppDynamics plugin is enabled but the libappdynamics.so
file cannot be loaded, Kong Gateway will refuse to start.
You will receive an error message like this:
kong/plugins/app-dynamics/appdynamics.lua:74: libappdynamics.so: cannot open shared object file: No such file or directory
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 |
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.