README.md

NGINX plugin for OpenTracing

Enable requests served by nginx for distributed tracing via The OpenTracing Project.

Dependencies

• The C++ OpenTracing Library
• A C++ OpenTracing Tracer. It currently works with Jaeger, Zipkin, LightStep, or Datadog.
• Source for Nginx 1.9.13 or later.

Installation

For linux-x86_64, pre-compiled binaries are provided for the supported versions of NGINX. These can be dropped into existing NGINX installations provided that NGINX was compiled with the --with-compat option. See example/trivial/ubuntu-x86_64 for an example of how to set it up.

Otherwise, nginx-opentracing can be used from the Docker image or built from source.

Getting Started

First, write a configuration for the tracer used. Below's an example of what a Jaeger configuration might look like:

/etc/jaeger-nginx-config.json

{
  "service_name": "nginx",
  "sampler": {
    "type": "const",
    "param": 1
  },
  "reporter": {
    "localAgentHostPort": "jaeger:6831"
  },
  "headers": {
    "jaegerDebugHeader": "jaeger-debug-id",
    "jaegerBaggageHeader": "jaeger-baggage",
    "traceBaggageHeaderPrefix": "uberctx-"
  },
  "baggage_restrictions": {
    "denyBaggageOnInitializationFailure": false,
    "hostPort": ""
  }
}

See the vendor documentation for details on what options are available.

You can then set up NGINX for distributed tracing by adding the following to nginx.conf:

# Load the OpenTracing dynamic module.
load_module modules/ngx_http_opentracing_module.so;

http {
  # Load a vendor tracer
  opentracing_load_tracer /usr/local/lib/libjaegertracing_plugin.so /etc/jaeger-nginx-config.json;

  # or
  #   opentracing_load_tracer /usr/local/lib/liblightstep_tracer_plugin.so /path/to/config;
  # or
  #   opentracing_load_tracer /usr/local/lib/libzipkin_opentracing_plugin.so /path/to/config;
  # or
  #   opentracing_load_tracer /usr/local/lib/libdd_opentracing_plugin.so /path/to/config;

  # Enable tracing for all requests.
  opentracing on;

  # Optionally, set additional tags.
  opentracing_tag http_user_agent $http_user_agent;

  upstream backend {
    server app-service:9001;
  }

  location ~ {
    # The operation name used for spans defaults to the name of the location
    # block, but you can use this directive to customize it.
    opentracing_operation_name $uri;

    # Propagate the active span context upstream, so that the trace can be
    # continued by the backend.
    # See http://opentracing.io/documentation/pages/api/cross-process-tracing.html
    opentracing_propagate_context;

    proxy_pass http://backend;
  }
}

See Tutorial for a more complete example, Reference for a list of available OpenTracing-related directives.

Docker

A docker image opentracing/nginx-opentracing is provided to support using nginx with OpenTracing in a manner analogous to the nginx Docker image. See here for examples of how to use it.

Additionally, custom images can be built by running

docker build \
       -t opentracing-contrib/nginx-opentracing:latest \
       .

and arguments to tweak the versions used can be provided with

docker build \
       -t opentracing-contrib/nginx-opentracing:latest \
       --build-arg OPENTRACING_CPP_VERSION=master \
       .

Other build arguments

• OPENTRACING_CPP_VERSION
• JAEGER_CPP_VERSION
• GRPC_VERSION

Building From Source

tar zxvf nginx-1.9.x.tar.gz
cd nginx-1.9.x
./configure --add-dynamic-module=/absolute/path/to/nginx-opentracing/opentracing
make && sudo make install

You will also need to install a C++ tracer for either Jaeger, LightStep (Available for OpenTracing 1.5.x), Datadog, or Zipkin. For linux x86-64, portable binary plugins are available:

# Jaeger
wget https://github.com/jaegertracing/jaeger-client-cpp/releases/download/v0.4.2/libjaegertracing_plugin.linux_amd64.so -O /usr/local/lib/libjaegertracing_plugin.so

# LightStep
wget -O - https://github.com/lightstep/lightstep-tracer-cpp/releases/download/v0.8.1/linux-amd64-liblightstep_tracer_plugin.so.gz | gunzip -c > /usr/local/lib/liblightstep_tracer_plugin.so

# Zipkin
wget -O - https://github.com/rnburn/zipkin-cpp-opentracing/releases/download/v0.5.2/linux-amd64-libzipkin_opentracing_plugin.so.gz | gunzip -c > /usr/local/lib/libzipkin_opentracing_plugin.so

# Datadog
wget -O - https://github.com/DataDog/dd-opentracing-cpp/releases/download/v0.3.0/linux-amd64-libdd_opentracing_plugin.so.gz | gunzip -c > /usr/local/lib/libdd_opentracing_plugin.so

Make sure the nginx module for opentracing and a tracer plugin were built against the same version of C++ OpenTracing Library. By default Opentracing v1.6.0 is used.

Testing

Run tests on local machine requires pyenv and tested against version 3.8.5.

make test