From 0a197fc60f492b6692edb05e18c676166618a9eb Mon Sep 17 00:00:00 2001 From: Michael Vernik Date: Wed, 23 Aug 2023 14:26:57 -0700 Subject: [PATCH] Added to intro, more context/details to building/installation. Removed directives and other docs, linking to nginx.org instead. Removed $ from commands for easier copy/paste. Added steps for collecting/viewing traces, community info (slack/issues page), link to contribution guidelines, changelog. --- README.md | 200 +++++++++++++++++++++--------------------------------- 1 file changed, 79 insertions(+), 121 deletions(-) diff --git a/README.md b/README.md index 38d1448..4850bda 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,92 @@ -# nginx_otel +# NGINX Native OpenTelemetry (OTel) Module -This project provides support for OpenTelemetry distributed tracing in Nginx, offering: +## What is OpenTelemetry +OpenTelemetry (OTel) is an observability framework for monitoring, tracing, troubleshooting, and optimizing applications. OTel enables the collection of telemetry data from a deployed application stack. -- Lightweight and high-performance incoming HTTP request tracing -- [W3C trace context](https://www.w3.org/TR/trace-context/) propagation -- OTLP/gRPC trace export -- Fully Dynamic Variable-Based Sampling +## What is the Native NGINX Otel Module +The `ngx_otel_module` dynamic module enables NGINX Open-Source or NGINX Plus to send telemetry data to an OTel collector. It provides support for [W3C trace context](https://www.w3.org/TR/trace-context/) propagation, OTLP/gRPC trace exports and offers several benefits over exiting OTel modules, including: + +### Better Performance ### +3rd-party OTel implementations reduce performance of request processing by as much as 50% when tracing is enabled. The NGINX Native module limits this impact to approximately 10-15%. + +### Easy Provisioning ### +Setup and configuration can be done right in NGINX configuration files. + +### Fully Dynamic Variable-Based Sampling ### +The module provides the ability to trace a particular session by cookie/token. [NGINX Plus](https://www.nginx.com/products/nginx/), available as part of a [commercial subscription](https://www.nginx.com/products/), enables dynamic module control via the [NGINX Plus API](http://nginx.org/en/docs/http/ngx_http_api_module.html) and [key-value store](http://nginx.org/en/docs/http/ngx_http_keyval_module.html) modules. ## Building +Follow these steps to build the `ngx_otel_module` dynamic module on Ubuntu or Debian based systems: -Install build tools and dependencies: +Install build tools and dependencies. ```bash - $ sudo apt install cmake build-essential libssl-dev zlib1g-dev libpcre3-dev - $ sudo apt install pkg-config libc-ares-dev libre2-dev # for gRPC +sudo apt install cmake build-essential libssl-dev zlib1g-dev libpcre3-dev +sudo apt install pkg-config libc-ares-dev libre2-dev # for gRPC ``` -Configure Nginx: +Clone the NGINX repository. ```bash - $ ./configure --with-compat +git clone git@github.com:nginx/nginx.git ``` -Configure and build Nginx OTel module: +Configure NGINX to create objects necessary for dynamic module compilation. Objects will be placed into the `nginx/objs` directory. ```bash - $ mkdir build - $ cd build - $ cmake -DNGX_OTEL_NGINX_BUILD_DIR=/path/to/configured/nginx/objs .. - $ make +cd nginx +auto/configure --with-compat ``` -## Getting Started +Exit the NGINX directory and clone the `ngx_otel_module` repository. +```bash +cd .. +git clone git@github.com:nginxinc/nginx-otel.git +``` -### Simple Tracing +Configure and build the NGINX OTel module. -Dumping all the requests could be useful even in non-distributed environment. +**Important**: replace the path in the `cmake` command with the path to the `nginx/objs` directory from above. +```bash +cd nginx-otel +mkdir build +cd build +cmake -DNGX_OTEL_NGINX_BUILD_DIR=/path/to/configured/nginx/objs .. +make +``` + +Compilation will produce a binary named `ngx_otel_module.so`. + +## Installation +If necessary, follow [instructions](https://nginx.org/en/docs/install.html) to install NGINX. Alternatively, you may choose to [download binaries](https://nginx.org/en/download.html). + +Copy the `ngx_otel_module.so` dynamic module binary to the NGINX configuration directory, typically located at: `/etc/nginx/modules`. + +Load the module by adding the following line to the top of the main NGINX configuration file, typically located at: `/etc/nginx/nginx.conf`. ```nginx - http { - otel_trace on; - server { - location / { - proxy_pass http://backend; - } - } - } +load_module modules/ngx_otel_module.so; +``` + +## Configuring the Module +For a complete list of directives, embedded variables, default span attributes and sample configurations, please refer to the [`ngx_otel_module` documentation](https://nginx.org/en/docs/ngx_otel_module.html). + +## Examples +Use these examples to configure some common use-cases for OTel tracing. + +### Simple Tracing +This example sends telemetry data for all http requests. + +```nginx +http { + otel_trace on; + server { + location / { + proxy_pass http://backend; + } + } +} ``` ### Parent-based Tracing +In this example, we inherit trace contexts from incoming requests and record spans only if a parent span is sampled. We also propagate trace contexts and sampling decisions to upstream servers. ```nginx http { @@ -61,6 +102,7 @@ http { ``` ### Ratio-based Tracing +In this ratio-based example, tracing is configured for a percentage of traffic (in this case 10%): ```nginx http { @@ -87,105 +129,21 @@ http { } ``` -## How to Use +## Collecting and Viewing Traces +There are several methods and available software packages for viewing traces. For a quick start, [Jaeger](https://www.jaegertracing.io/) provides an all-in-one container to collect, process and view OTel trace data. Follow [these steps](https://www.jaegertracing.io/docs/next-release/deployment/#all-in-one) to download, install, launch and use Jaeger's OTel services. -### Directives +# Community +- Our Slack channel [#nginx-opentelemetry-module](https://nginxcommunity.slack.com/archives/C05NMNAQDU6), is the go-to place to start asking questions and sharing your thoughts. -#### Available in `http/server/location` contexts +- Our [GitHub issues page](https://github.com/nginxinc/nginx-otel/issues) offers space for a more technical discussion at your own pace. -**`otel_trace`** `on | off | “$var“;` +# Contributing +Get involved with the project by contributing! Please see our [contributing guide](CONTRIBUTING.md) for details. -The argument is a “complex value”, which should result in `on`/`off` or `1`/`0`. Default is `off`. - -**`otel_trace_context`** `ignore | extract | inject | propagate;` - -Defines how to propagate traceparent/tracestate headers. `extract` uses existing trace context from request. `inject` adds new context to request, rewriting existing headers if any. `propagate` updates existing context (i.e. combines `extract` and `inject`). `ignore` skips context headers processing. Default is `ignore`. - -**`otel_span_name`** `name;` - -Default is request’s location name. - -**`otel_span_attr`** `name “$var”;` - -If name starts with `http.(request|response).header.` the type of added attribute will be `string[]` to match semantic conventions (i.e. header value will be represented as a single element array). Otherwise, the attribute type will be `string`. - -#### Available in `http` context - -**`otel_exporter`**`;` - -Defines how to export tracing data. There can only be one `otel_exporter` directive in a given `http` context. - -```nginx -otel_exporter { - endpoint “host:port“; - interval 5s; # max interval between two exports - batch_size 512; # max number of spans to be sent in one batch per worker - batch_count 4; # max number of pending batches per worker, over the limit spans are dropped -} -``` - -**`otel_service_name`** `name;` - -Sets `service.name` attribute of OTel resource. By default, it is set to `unknown_service:nginx`. - -### Available in `otel_exporter` context - -**`endpoint`** `"host:post";` - -Defines exporter endpoint `host` and `port`. Only one endpoint per `otel_exporter` can be specified. - -**`interval`** `5s;` - -Maximum interval between two exports. Default is `5s`. - -**`batch_size`** `512;` - -Maximum number of spans to be sent in one batch per worker. Detault is 512. - -**`batch_count`** `4;` - -Maximum number of pending batches per worker, over the limit spans are dropped. Default is 4. - -### Variables - -`$otel_trace_id` - trace id. - -`$otel_span_id` - current span id. - -`$otel_parent_id` - parent span id. - -`$otel_parent_sampled` - `sampled` flag of parent span, `1`/`0`. - -### Default span [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md) - -`http.method` - -`http.target` - -`http.route` - -`http.scheme` - -`http.flavor` - -`http.user_agent` - -`http.request_content_length` - -`http.response_content_length` - -`http.status_code` - -`net.host.name` - -`net.host.port` - -`net.sock.peer.addr` - -`net.sock.peer.port` - -## License +# Change Log +See our [release page](https://github.com/nginxinc/nginx-otel/releases) to keep track of updates. +# License [Apache License, Version 2.0](https://github.com/nginxinc/nginx-otel/blob/main/LICENSE) © [F5, Inc.](https://www.f5.com/) 2023