Skip to content

Commit b0d8356

Browse files
y82y82
committed
More updates to OpenTelemetry
1 parent db65ed9 commit b0d8356

File tree

1 file changed

+148
-97
lines changed

1 file changed

+148
-97
lines changed

‎content/nginx/admin-guide/dynamic-modules/opentelemetry.md

Lines changed: 148 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -15,159 +15,204 @@ type:
1515

1616
The `nginx-plus-module-otel` module is an NGINX-authored dynamic module that enables NGINX Plus to send telemetry data to an OTel collector. The module supports [W3C](https://w3c.github.io/trace-context/) trace context propagation, OpenTelemetry Protocol (OTLP)/gRPC trace exports, and offers several advantages over existing OTel modules including:
1717

18-
- Enhanced performance: other OTel implementations can reduce request processing by up to 50%, while `nginx-plus-module-otel` minimizes this impact to just 10-15%.
18+
- Enhanced performance: other OTel implementations can reduce request processing by up to 50%, while the native module minimizes this impact to just 10-15%.
1919

2020
- Simplified provisioning through NGINX configuration file.
2121

2222
- Dynamic, variable-based control of trace parameters with cookies, tokens, and variables. See [Ratio-based Tracing](#example) example for details.
2323

2424
- Dynamic control of sampling parameters via the [NGINX Plus API]({{< ref "/nginx/admin-guide/monitoring/live-activity-monitoring.md#using-the-rest-api" >}}) and [key-value storage]({{< ref "/nginx/admin-guide/security-controls/denylisting-ip-addresses.md" >}}).
2525

26-
The repository can be found on [GitHub](https://github.com/nginxinc/nginx-otel). The documentation can be found on [nginx.org](https://nginx.org/en/docs/ngx_otel_module.html).
26+
The source code for the module is available in the official [GitHub repository](https://github.com/nginxinc/nginx-otel). The official documentation, including module reference and usage examples, is available on the [nginx.org](https://nginx.org/en/docs/ngx_otel_module.html) website.
27+
28+
The OpenTelemetry module supersedes the deprecated [OpenTracing]({{< ref "opentracing.md" >}}) module which was available until NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}).
2729

2830

2931
## Installation
3032

31-
Similar to [NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}), prebuilt packages of the `nginx-plus-module-otel` module can can be installed directly from the official repository for different distributions. Before installation you will need to add the NGINX Plus package repositories for your distribution and update the repository metadata.
33+
The installation process closely follows the [NGINX Plus installation procedure]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). Prebuilt packages of the module for various Linux distributions can can be installed directly from the official repository. Prior to installation, you need to add the NGINX Plus package repository for your distribution and update the repository metadata.
34+
35+
1. Check the [Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) page to verify that the module is supported by your operating system.
36+
37+
{{< note >}} The OpenTelemetry module cannot be installed on Amazon Linux 2 LTS and SLES 15 SP5+. {{< /note >}}
38+
39+
2. Make sure you have the latest version of NGINX Plus. In Terminal, run the command:
40+
41+
```shell
42+
nginx -v
43+
```
44+
45+
Expected output of the command:
46+
47+
```shell
48+
nginx version: nginx/1.27.4 (nginx-plus-r34)
49+
```
50+
51+
3. Ensure you have the **nginx-repo.crt** and **nginx-repo.key** files from [MyF5 Customer Portal](https://account.f5.com/myf5) in the **/etc/ssl/nginx/** directory. These files are required for accessing the NGINX Plus repository.
52+
53+
```shell
54+
sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crt && \
55+
sudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key
56+
```
57+
58+
For Alpine, the **nginx-repo.crt** to **/etc/apk/cert.pem** and **nginx-repo.key** files should be added to **/etc/apk/cert.key**. Ensure these files contain only the specific key and certificate as Alpine Linux does not support mixing client certificates for multiple repositories.
3259

33-
1. Check the [Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) page to verify that the module is supported by your operating system.
60+
For FreeBSD, the path to these files should also be added to the `/usr/local/etc/pkg.conf` file:
3461

35-
{{< note >}} The OpenTelemetry module cannot be installed on Amazon Linux 2 LTS and SLES 15 SP5+. {{< /note >}}
62+
```shell
63+
PKG_ENV: { SSL_NO_VERIFY_PEER: "1",
64+
SSL_CLIENT_CERT_FILE: "/etc/ssl/nginx/nginx-repo.crt",
65+
SSL_CLIENT_KEY_FILE: "/etc/ssl/nginx/nginx-repo.key" }
66+
```
3667
37-
2. Make sure you have the latest version of NGINX Plus. In Terminal, run the command:
68+
4. Ensure that all required dependencies for your operating system are installed.
3869
39-
```shell
40-
nginx -v
41-
```
70+
For Amazon Linux 2023, AlmaLinux, CentOS, Oracle Linux, RHEL, and Rocky Linux:
4271
43-
Expected output of the command:
72+
```shell
73+
sudo dnf update && \
74+
sudo dnf install ca-certificates
75+
```
4476
45-
```shell
46-
nginx version: nginx/1.27.4 (nginx-plus-r34)
47-
```
77+
For Debian:
4878
49-
3. Make sure you have installed the dependencies required for your operating system.
79+
```shell
80+
sudo apt update && \
81+
sudo apt install apt-transport-https \
82+
lsb-release \
83+
ca-certificates \
84+
wget \
85+
gnupg2 \
86+
debian-archive-keyring
87+
```
5088
51-
For Amazon Linux 2023, AlmaLinux, CentOS, Oracle Linux, RHEL, and Rocky Linux:
89+
For Ubuntu:
5290
53-
```shell
54-
sudo dnf update
55-
sudo dnf install ca-certificates
56-
sudo dnf update-ca-certificates #use if ca-certificates are installed
57-
```
91+
```shell
92+
sudo apt update && \
93+
sudo apt install apt-transport-https \
94+
lsb-release \
95+
ca-certificates \
96+
wget \
97+
gnupg2 \
98+
ubuntu-keyring
99+
```
58100
59-
For Debian:
101+
For FreeBSD:
60102
61-
```shell
62-
sudo apt update
63-
sudo apt install apt-transport-https lsb-release ca-certificates wget gnupg2 debian-archive-keyring
64-
```
103+
```shell
104+
sudo pkg update && \
105+
sudo pkg install ca_root_nss
106+
```
65107
66-
```shell
67-
wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \
108+
5. Ensure that the NGINX signing key has been added, if required by your operating system.
109+
110+
For Debian:
111+
112+
```shell
113+
wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \
68114
| gpg --dearmor \
69115
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
70-
```
71-
72-
For Ubuntu:
116+
```
73117
74-
```shell
75-
sudo apt update
76-
sudo apt install apt-transport-https lsb-release ca-certificates wget gnupg2 ubuntu-keyring
77-
```
118+
For Ubuntu:
78119
79-
```shell
80-
printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
81-
https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" \
82-
| sudo tee /etc/apt/sources.list.d/nginx-plus.list
83-
```
120+
```shell
121+
printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
122+
https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" \
123+
| sudo tee /etc/apt/sources.list.d/nginx-plus.list
124+
```
84125
85-
For Alpine:
126+
For Alpine:
86127
87-
```shell
88-
sudo wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub
89-
```
128+
```shell
129+
sudo wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub
130+
```
90131
91-
For FreeBSD:
132+
6. Ensure that your package management system is configured to pull packages from the NGINX Plus repository. See [Installing NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) for details.
92133
93-
```shell
94-
sudo pkg update
95-
sudo pkg install ca_root_nss
96-
```
134+
7. Update the repository information and install the package. In a terminal, run the appropriate command for your operating system.
97135
98-
3. Make sure you have obtained the **nginx-repo.crt** and **nginx-repo.key** files from MyF5 and put them to the **/etc/ssl/nginx/** directory. These files are required for accessing the NGINX Plus repository:
136+
For CentOS, Oracle Linux, and RHEL:
99137
100-
```shell
101-
sudo cp nginx-repo.crt /etc/ssl/nginx/
102-
sudo cp nginx-repo.key /etc/ssl/nginx/
103-
```
138+
```shell
139+
sudo yum update && \
140+
sudo yum install nginx-plus-module-otel
141+
```
104142
105-
For Alpine, upload **nginx-repo.crt** to **/etc/apk/cert.pem** and **nginx-repo.key** to **/etc/apk/cert.key**. Ensure these files contain only the specific key and certificate as Alpine Linux does not support mixing client certificates for multiple repositories.
143+
For Amazon Linux 2023, AlmaLinux, Rocky Linux:
106144
107-
4. Make sure your package management system is configured to pull from the NGINX Plus repository. See [Installing NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) for details.
145+
```shell
146+
sudo dnf update && \
147+
sudo dnf install nginx-plus-module-otel
148+
```
108149
109-
4. Update the repository information and install the package. In a terminal, run the appropriate command for your operating system.
150+
For Debian and Ubuntu:
110151
111-
For CentOS, Oracle Linux, and RHEL:
152+
```shell
153+
sudo apt update && \
154+
sudo apt install nginx-plus-module-otel
155+
```
112156
113-
```shell
114-
sudo yum update
115-
sudo yum install nginx-plus-module-otel
116-
```
157+
For Alpine:
117158
118-
For Amazon Linux 2023, AlmaLinux, Rocky Linux:
159+
```shell
160+
sudo apk update && \
161+
sudo apk add nginx-plus-module-otel
162+
```
119163
120-
```shell
121-
sudo dnf update
122-
sudo dnf install nginx-plus-module-otel
123-
```
164+
For FreeBSD:
124165
125-
For Debian and Ubuntu:
166+
```shell
167+
sudo pkg update && \
168+
sudo pkg install nginx-plus-module-otel
169+
```
126170
127-
```shell
128-
sudo apt update
129-
sudo apt install nginx-plus-module-otel
130-
```
171+
The resulting `ngx_otel_module.so` dynamic module will be written to the following directory, depending on your operating system:
131172
132-
For Alpine:
173+
- `/usr/local/nginx/modules` for most Linux Distributions
174+
- `/usr/lib/nginx/modules` for Ubuntu
175+
- `/usr/local/etc/nginx/modules` for FreeBSD
133176
134-
```shell
135-
sudo apk update
136-
sudo apk add nginx-plus-module-otel
137-
```
177+
8. Enable dynamic loading of the module.
138178
139-
For FreeBSD:
179+
- In a text editor, open the NGINX Plus configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD).
140180
141-
```shell
142-
sudo pkg update
143-
sudo pkg install nginx-plus-module-otel
144-
```
181+
- On the top-level (or “`main`”) context, specify the path to the dynamic module with the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive:
145182
146-
The module will be installed in the `/usr/local/nginx` directory.
183+
```nginx
184+
load_module modules/ngx_otel_module.so;
147185
148-
6. Copy the `ngx_otel_module.so` dynamic module binary to `/usr/local/nginx/modules`.
186+
http {
187+
#...
188+
}
189+
```
190+
- Save the configuration file.
149191
150-
7. Enable dynamic loading of the module. Open the NGINX Plus configuration file, `nginx.conf` in a text editor, and specify the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive on the top-level (“`main`”) context:
192+
9. Test the NGINX Plus configuration. In a terminal, type-in the command:
151193
152-
```nginx
153-
load_module modules/ngx_otel_module.so;
194+
```shell
195+
nginx -t
196+
```
154197
155-
http {
156-
#...
157-
}
158-
```
198+
Expected output of the command:
159199
160-
3. Save the configuration file.
200+
```shell
201+
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
202+
nginx: configuration file /etc/nginx/nginx.conf is successful
203+
```
161204
162-
4. Test and reload NGINX Plus configuration to enable the module. In Terminal, type-in the command:
205+
10. Reload the NGINX Plus configuration to enable the module:
163206
164-
```shell
165-
nginx -t && nginx -s reload
166-
```
207+
```shell
208+
nginx -s reload
209+
```
167210
168211
169212
## Configuration
170213
214+
In a text editor, open the NGINX Plus configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD).
215+
171216
For a complete list of directives, embedded variables, default span attributes, refer to the `ngx_otel_module` official documentation.
172217
173218
List of directives:
@@ -187,7 +232,7 @@ Default span attributes:
187232
188233
### Simple Tracing
189234
190-
Dumping all the requests could be useful even in non-distributed environment.
235+
This configuration enables basic request tracing, capturing tracing information for every incoming request, even in non-distributed environments.
191236
192237
```nginx
193238
http {
@@ -202,6 +247,8 @@ http {
202247
203248
### Parent-based Tracing
204249
250+
This configuration enables parent-based tracing, where NGINX Plus captures and propagates trace information from incoming requests, allowing tracing contexts to be inherited from the parent request. It is useful in scenarios where NGINX Plus is used as a reverse proxy within a distributed tracing system.
251+
205252
```nginx
206253
http {
207254
server {
@@ -217,6 +264,8 @@ http {
217264
218265
### Ratio-based Tracing
219266
267+
This configuration enables sampling of a specified percentage of requests or user sessions for tracing, based on configurable ratios.
268+
220269
```nginx
221270
http {
222271
# trace 10% of requests
@@ -248,6 +297,8 @@ http {
248297
249298
- [Official Documentation for the NGINX Native OpenTelemetry Module](https://nginx.org/en/docs/ngx_otel_module.html)
250299
300+
- [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}})
301+
251302
- [NGINX Dynamic Modules]({{< ref "dynamic-modules.md" >}})
252303
253-
- [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}})
304+
- [Uninstalling a Dynamic Module]({{< ref "uninstall.md" >}})

0 commit comments

Comments
 (0)