github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/third-party-modules/opentracing.md (about)

     1  # OpenTracing
     2  
     3  The Ingress Controller supports [OpenTracing](https://opentracing.io/) with the third-party module [opentracing-contrib/nginx-opentracing](https://github.com/opentracing-contrib/nginx-opentracing).
     4  
     5  This document explains how to use OpenTracing with the Ingress Controller.
     6  
     7  **Note**: The examples below use the snippets annotations, which are disabled by default. To use snippets, set the [`enable-snippets`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-enable-snippets) command-line argument.
     8  
     9  ## Prerequisites
    10  1. **Use the Ingress Controller image with OpenTracing.** You can find the images with NGINX or NGINX Plus with OpenTracing listed [here](/nginx-ingress-controller/technical-specifications/#supported-docker-images). Alternatively, you can follow the build instructions to build the image using `debian-image-opentracing` for NGINX or `debian-image-opentracing-plus` for NGINX Plus.
    11  [Jaeger](https://github.com/jaegertracing/jaeger-client-cpp), [Zipkin](https://github.com/rnburn/zipkin-cpp-opentracing) and [Datadog](https://github.com/DataDog/dd-opentracing-cpp/) tracers are installed by default.
    12  
    13  1. **Load the OpenTracing module.** You need to load the module with the configuration for the chosen tracer using the following ConfigMap keys:
    14     * `opentracing-tracer`: sets the path to the vendor tracer binary plugin. This is the path you used in the COPY line of step *ii* above.
    15     * `opentracing-tracer-config`: sets the tracer configuration in JSON format.
    16  
    17     Below an example on how to use those keys to load the module with Jaeger tracer:
    18      ```yaml
    19      opentracing-tracer: "/usr/local/lib/libjaegertracing_plugin.so"
    20      opentracing-tracer-config: |
    21              {
    22                  "service_name": "nginx-ingress",
    23                  "sampler": {
    24                      "type": "const",
    25                      "param": 1
    26                  },
    27                  "reporter": {
    28                      "localAgentHostPort": "jaeger-agent.default.svc.cluster.local:6831"
    29                  }
    30              }
    31      ```
    32  
    33  ## Enable OpenTracing Globally
    34  To enable OpenTracing globally (for all Ingress, VirtualServer and VirtualServerRoute resources), set the `opentracing` ConfigMap key to `True`:
    35  
    36  ```yaml
    37  opentracing: True
    38  ```
    39  
    40  ## Enable/Disable OpenTracing per Ingress Resource
    41  
    42  It is possible to use annotations to enable or disable OpenTracing for a specific Ingress Resource. As mentioned in the prerequisites section, both `opentracing-tracer` and `opentracing-tracer-config` must be configured.
    43  
    44  Consider the following two cases:
    45  1. OpenTracing is globally disabled.
    46     1. To enable OpenTracing for a specific Ingress Resource, use the server snippet annotation:
    47          ```yaml
    48          nginx.org/server-snippets: |
    49              opentracing on;
    50          ```
    51     1. To enable OpenTracing for specific paths, (1) you need to use [Mergeable Ingress resources](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration) and (2) use the location snippets annotation to enable OpenTracing for the paths of a specific Minion Ingress resource:
    52          ```yaml
    53          nginx.org/location-snippets: |
    54              opentracing on;
    55          ```
    56  
    57  2. OpenTracing is globally enabled:
    58     1. To disable OpenTracing for a specific Ingress Resource, use the server snippet annotation:
    59          ```yaml
    60          nginx.org/server-snippets: |
    61              opentracing off;
    62          ```
    63  
    64     1. To disable OpenTracing for specific paths, (1) you need to use [Mergeable Ingress resources](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration) and (2) use the location snippets annotation to disable OpenTracing for the paths of a specific Minion Ingress resource:
    65          ```yaml
    66          nginx.org/location-snippets: |
    67              opentracing off;
    68          ```
    69  
    70  ## Customize OpenTracing
    71  
    72  You can customize OpenTracing though the supported [OpenTracing module directives](https://github.com/opentracing-contrib/nginx-opentracing/blob/master/doc/Reference.md). Use the snippets ConfigMap keys or annotations to insert those directives into the http, server or location contexts of the generated NGINX configuration.
    73  
    74  For example, to propagate the active span context for upstream requests, it is required to set the `opentracing_propagate_context` directive, which you can add to an Ingress resource using the location snippets annotation:
    75  
    76  ```yaml
    77  nginx.org/location-snippets: |
    78     opentracing_propagate_context;
    79  ```
    80  
    81  **Note**: `opentracing_propagate_context` and `opentracing_grpc_propagate_context` directives can be used in http, server or location contexts according to the [module documentation](https://github.com/opentracing-contrib/nginx-opentracing/blob/master/doc/Reference.md#opentracing_propagate_context). However, because of the way the module works and how the Ingress Controller generates the NGINX configuration, it is only possible to use the directive in the location context.