daroche/nginx-otel-nix
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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.

Browse source
This commit is contained in:
Michael Vernik 2023-08-23 14:26:57 -07:00
parent c732ff5fd1
commit 0a197fc60f
1 changed files with 79 additions and 121 deletions
Download patch file Download diff file Expand all files Collapse all files

200
README.md
View file

@ -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 ## What is the Native NGINX Otel Module
- [W3C trace context](https://www.w3.org/TR/trace-context/) propagation 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:
- OTLP/gRPC trace export
- Fully Dynamic Variable-Based Sampling ### 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 ## 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 ```bash
$ sudo apt install cmake build-essential libssl-dev zlib1g-dev libpcre3-dev 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 pkg-config libc-ares-dev libre2-dev # for gRPC
``` ```
Configure Nginx: Clone the NGINX repository.
```bash ```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 ```bash
$ mkdir build cd nginx
$ cd build auto/configure --with-compat
$ cmake -DNGX_OTEL_NGINX_BUILD_DIR=/path/to/configured/nginx/objs ..
$ make
``` ```
## 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 ```nginx
http { load_module modules/ngx_otel_module.so;
otel_trace on; ```
server {
location / { ## Configuring the Module
proxy_pass http://backend; 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 ### 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 ```nginx
http { http {
@ -61,6 +102,7 @@ http {
``` ```
### Ratio-based Tracing ### Ratio-based Tracing
In this ratio-based example, tracing is configured for a percentage of traffic (in this case 10%):
```nginx ```nginx
http { 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`. # Change Log
See our [release page](https://github.com/nginxinc/nginx-otel/releases) to keep track of updates.
**`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
# License
[Apache License, Version 2.0](https://github.com/nginxinc/nginx-otel/blob/main/LICENSE) [Apache License, Version 2.0](https://github.com/nginxinc/nginx-otel/blob/main/LICENSE)
© [F5, Inc.](https://www.f5.com/) 2023 © [F5, Inc.](https://www.f5.com/) 2023