99 lines
2.4 KiB
Markdown
99 lines
2.4 KiB
Markdown
# nginx_otel
|
|
|
|
This project provides support for OpenTelemetry distributed tracing in Nginx, offering:
|
|
|
|
- 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
|
|
|
|
## Building
|
|
|
|
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
|
|
```
|
|
|
|
Configure Nginx:
|
|
```bash
|
|
$ ./configure --with-compat
|
|
```
|
|
|
|
Configure and build Nginx OTel module:
|
|
```bash
|
|
$ mkdir build
|
|
$ cd build
|
|
$ cmake -DNGX_OTEL_NGINX_BUILD_DIR=/path/to/configured/nginx/objs ..
|
|
$ make
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
### Simple Tracing
|
|
|
|
Dumping all the requests could be useful even in non-distributed environment.
|
|
|
|
```nginx
|
|
http {
|
|
otel_trace on;
|
|
server {
|
|
location / {
|
|
proxy_pass http://backend;
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## How to Use
|
|
|
|
### Directives
|
|
|
|
#### Available in `http/server/location` contexts
|
|
|
|
**`otel_trace`** `on | off | “$var“;`
|
|
|
|
The argument is a “complex value”, which should result in `on`/`off` or `1`/`0`. Default is `off`.
|
|
|
|
#### 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.
|
|
|
|
## License
|
|
|
|
[Apache License, Version 2.0](https://github.com/nginxinc/nginx-otel/blob/main/LICENSE)
|
|
|
|
© [F5, Inc.](https://www.f5.com/) 2023
|