nginx logo nginxplus logo

Instana has the ability to collect both metrics and distributed traces of requests that pass through NGINX.

Note: Tracing support is currently in technology preview. A future update will include fully automatic tracing support for both NGINX and NGINX Plus.

Enabling Metrics Collection

Once Metrics are enabled as described below, Instana will automatically begin to collect and monitor your NGINX processes.


For NGINX metrics collection, Instana uses the ngx_http_stub_status_module for remote metrics collection. To enable this, make sure that the module is enabled/available and add the following to your NGINX configuration:

location /nginx_status {
  stub_status  on;
  access_log   off;


To enable NGINX Plus metric monitoring, make sure the ngx_http_api_module ( * ) is installed/available and add the following block to enable the module:

location /api {
    api write=off;
    allow; # Or the Remote IP of the Instana Host Agent
    deny all;

Enabling Distributed Tracing

Tracing of requests that pass through NGINX is done by an Instana DSO module based on OpenTracing.

To enable NGINX tracing, update the NGINX configuration file to load the OpenTracing module and the Instana tracer.

Support for Dynamic Shared Objects (DSO) was added in NGINX release 1.9.11. Please validate that you are running at least 1.9.11 before attempting to enable tracing of requests in your NGINX proxy.

load_module modules/;

events {}

http {
  opentracing on;
  error_log /dev/stdout info;

  opentracing_load_tracer /usr/local/lib/ /etc/instana-config.json;
  upstream backend {
    server app-service:9001;

  server {
    error_log /var/log/nginx/debug.log debug;
    listen 8080;
    server_name localhost;

    location = / {
      opentracing_trace_locations off;
      proxy_pass http://backend;
      opentracing_tag "" "/";

Configuring Distributed Tracing

To report traces, the Instana DSO must know the location of the Instana Host Agent. In most cases, this can be discovered automatically with no configuration needed. By default, the Instana DSO will search localhost and the default gateway for a running Instana Host Agent listening on the default port of 42699.

If you need to manually configure where the Instana Agent is listening, there are two methods:

via Environment Variables

INSTANA_AGENT_HOST - The IP address that the Instana Host Agent is listening on

INSTANA_AGENT_PORT - The Port that the Instana Host Agent is listening on

INSTANA_SERVICE_NAME - Manually set the service name for NGINX and the traces reported from NGINX.

via json configuration file

As shown in the NGINX configuration above, you can provide /etc/instana-config.json with the following contents:

  "service": "nginx",
  "agent_host": "instana-agent",
  "agent_port": 42699

Retrieving the Instana DSO for NGINX

Until tracing of NGINX is out of technology preview, the Instana DSO for NGINX is available on Artifactory for manual download in two flavors:

  1. Linux amd64:
  2. Linux amd64 musl:

To download the files above, authentication is required. Please use _ as the username and your Instana Agent Key as password. Your Instana Agent Key is available under the “Management Portal” menu item in your Instana dashboard.

NGINX Tracing Example

See also the nginx-tracing demo application available on Github. The demo demonstrates:

  1. How to configure NGINX with Instana Tracing
  2. tracing of requests through NGINX with two Java Spring applications

Supported Versions

Functionality Version
Metrics >=1.0
Distributed Tracing >=1.9.11

Sensor (Data Collection)

Tracked Configuration

  • PID
  • Number of Worker Processes
  • Number of Worker Connections
  • Started at
  • Version
  • Build ( * )
  • Address ( * )
  • Generation ( * )
  • PPID ( * )


  • Request
  • Connections
  • Processes ( * )
  • SSL ( * )
  • Caches ( * )
  • Server zones ( * )
  • Upstreams ( * )

Health Signatures

  • active connections
  • dropping connections
  • failed ssl handshakes ( * )
  • inactive peer ( * )

( * ) only available for nginx plus.