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 at the beginning of your NGINX configuration:

location /nginx_status {
  stub_status  on;
  access_log   off;

By default, the Instana agent searches for the location of the configuration file in any available process arguments; otherwise, it fallbacks to /etc/nginx/nginx.conf.


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;

Kubernetes NGINX Ingress

From Kubernetes NGINX Ingress version 0.23.0 onwards, the server listening on port 18080 was disabled. For Instana to monitor this NGINX instance, restore the server by adding the following snippet to the configmap:

http-snippet: |
  server {
    listen 18080;

    location /nginx_status {
      stub_status on;

    location / {
      return 404;

For full details see the NGINX Ingress Release Notes.

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 "" "/";

      # Add support for EUM correlation
      add_header "server-timing" "intid;desc=${opentracing_context_x_instana_t}";

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

Enable Distributed Tracing for Kubernetes NGINX Ingress

The Kubernetes NGINX Ingress allows for distributed tracing via the OpenTracing project. As the Instana Agent is capable of ingesting also Jaeger and Zipkin traces, it is possible to configure the NGINX Ingress in such a way that traces are forwarded to Instana.

Note: While this setup is supported, Instana won’t be able to take over the trace-context from OpenTracing traces, meaning insight is limited to only NGINX spans presented in isolation. Only when all services are traced via OpenTracing is the context retained and will Instana show the full distributed trace. Note2: Requires nginx-ingress version 0.23.0 or higher, as otherwise the variable expansion won’t be possible.

Configure NGINX Ingress for Instana Agent

The following configuration values need to be specified.

  • To the ConfigMap for the NGINX ingress, add the following:
    enable-opentracing: "true"
    zipkin-collector-host: $HOST_IP
    zipkin-collector-port: "42699"
  • To the NGINX Pod Spec add the following environment variable (it should have already POD_NAME and POD_NAMESPACE):
- name: HOST_IP
        fieldPath: status.hostIP

This configuration uses the Kubernetes DownwardAPI to make the host IP available as environment variable (“HOST_IP”) and the config map will pick this up. The port can be fixed to 42699, our Agent port.

Also note that the service will be named either as the default; nginx or it needs to be overwritten via the parameter zipkin-service-name which can be configured in the ConfigMap.

For more information about the NGINX ingress and OpenTracing see the Kubernetes NGINX Ingress documentation.

Supported Versions

Functionality Version
Metrics >=1.0
Distributed Tracing >=1.9.11

Metrics collection

Configuration data

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

Performance metrics

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

Health Signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the incoming metrics and are used to raise issues or incidents depending on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any given entity.

For information about built-events for the NGINX sensor, see the Built-in events reference.