191 lines
4.4 KiB
Markdown
191 lines
4.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;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Parent-based Tracing
|
||
|
||
```nginx
|
||
http {
|
||
server {
|
||
location / {
|
||
otel_trace $otel_parent_sampled;
|
||
otel_trace_context propagate;
|
||
|
||
proxy_pass http://backend;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Ratio-based Tracing
|
||
|
||
```nginx
|
||
http {
|
||
# trace 10% of requests
|
||
split_clients $otel_trace_id $ratio_sampler {
|
||
10% on;
|
||
* off;
|
||
}
|
||
|
||
# or we can trace 10% of user sessions
|
||
split_clients $cookie_sessionid $session_sampler {
|
||
10% on;
|
||
* off;
|
||
}
|
||
|
||
server {
|
||
location / {
|
||
otel_trace $ratio_sampler;
|
||
otel_trace_context inject;
|
||
|
||
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`.
|
||
|
||
**`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
|
||
|
||
[Apache License, Version 2.0](https://github.com/nginxinc/nginx-otel/blob/main/LICENSE)
|
||
|
||
© [F5, Inc.](https://www.f5.com/) 2023
|