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.
This commit is contained in:
Michael Vernik
parent
c732ff5fd1
commit
0a197fc60f
1 changed files with 79 additions and 121 deletions
200
README.md
200
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue