nginx-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