How Dynatrace supports NGINX applications

Dynatrace NGINX support is based on specific NGINX builds as built and packaged by nginx.org. NGINX builds are known as binaries.

Though Dynatrace NGINX support is based on supported binaries, generally Dynatrace support for NGINX versions is as follows:

Support for NGINX earlier than 1.4

NGINX versions earlier than 1.4 aren't supported.

Support for NGINX 1.11.5 to 1.3x, or NGINX Plus R1

Support for NGINX 1.11.5 and later

  • For OneAgent versions 1.145 and later, in addition to the list of supported NGINX binaries, almost all NGINX versions 1.11.5 and later are supported (except very recent NGINX releases). New NGINX releases are usually supported within a few weeks following their release, once OneAgent passes a series of tests using the new NGINX releases.

The following image shows this support.

NGINX  supported versions

Dynatrace encourages you to upgrade to OneAgent version 1.145 or later to take advantage of the latest features and avoid any issues with builds built and distributed by OpenResty. For OneAgent versions 1.144 and earlier, if the NGINX binaries used are built and distributed by OpenResty, the binaries must be included in the list of supported binaries below, or the debug information must be available locally to be supported.

For OneAgent version 1.145 or later, Dynatrace uses a debug-information-less signature method to qualify NGINX binaries for support. In Dynatrace, a message appears when viewing an NGINX process that attempts to use unsupported binaries.

List of supported NGINX binaries

The following applies to Dynatrace OneAgent versions 1.144 and earlier.

Though you can use the API to write a custom NGINX module, you can't add that module to a pre-existing NGINX installation. All modules must be built into the NGINX binary at compile time. Organizations such as nginx.org, Ubuntu, and distributors such as phusionpassenger.com provide pre-built NGINX binaries that contain a selection of modules that they believe their customers may need, often in multiple variants such as nginx-light or nginx-full.

How Dynatrace supports NGINX

OneAgent NGINX code modules are loaded into the NGINX process whether there's an official API for it or not. When inside the process, it uses the API available for the compiled NGINX modules to establish itself as an additional API. However, that API is not cleanly accessible at run-time. It's accessible only at build time and doesn't get preserved, except as debug info for the debugger. Dynatrace supports only those NGINX binaries for which it has access to the corresponding debug information.

How NGINX debug information is used in Dynatrace NGINX support

Standard NGINX package sources provided either as part of the NGINX distribution, through nginx.org, or through one of the packagers working in a similar way, provide their debug information in a separate package. These packages have dbg in their package name, for example nginx-extras-dbg_1.8.0-8.5.0.15~vivid1_i386.deb. Dynatrace discovers these on a regular basis.