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.

Enable Distributed Tracing for NGINX / NGINX Plus

The documentation for enabling NGINX tracing, currently in technical preview, together with a demo application, is available on Github.

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.