Skip to content

Commit fc7e69a

Browse files
mtbChefmtbChef
authored
Updated README: Added steps for installation from packages. (#19)
1 parent 9f359ff commit fc7e69a

File tree

1 file changed

+72
-44
lines changed

1 file changed

+72
-44
lines changed

‎README.md

Lines changed: 72 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -17,60 +17,29 @@ The ability to control trace parameters dynamically using cookies, tokens, and v
1717

1818
Additionally, [NGINX Plus](https://www.nginx.com/products/nginx/), available as part of a [commercial subscription](https://www.nginx.com/products/), enables dynamic control of sampling parameters 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.
1919

20-
## Building
21-
Follow these steps to build the `ngx_otel_module` dynamic module on Ubuntu or Debian based systems:
20+
## Installing
21+
Prebuilt packages of the module are available for easy installation. Follow these steps to install NGINX Open Source with the OTel module. See list of [compatible operating systems](https://nginx.org/en/linux_packages.html#distributions).
2222

23-
Install build tools and dependencies.
24-
```bash
25-
sudo apt install cmake build-essential libssl-dev zlib1g-dev libpcre3-dev
26-
sudo apt install pkg-config libc-ares-dev libre2-dev # for gRPC
27-
```
23+
### Adding Package Repositories and Installing NGINX Open Source
24+
Follow the official NGINX Open Source [installation steps](https://nginx.org/en/linux_packages.html#instructions) to set up package repositories for your specific operating system and install NGINX.
2825

29-
For the next step, you will need the `configure` script that is packaged with the NGINX source code. There are several methods for obtaining NGINX sources. You may choose to [download](http://hg.nginx.org/nginx/archive/tip.tar.gz) them or clone them directly from the [NGINX Github repository](https://github.com/nginx/nginx).
26+
**Important:** To ensure module compatibility, you must use officially distributed NGINX binaries. Compatibility with community distributed binaries, commonly available through various operating system vendors, is not guaranteed.
3027

31-
**Important:** To ensure compatibility, the `ngx_otel_module` and the NGINX binary that it will be used with, will need to be built using the same NGINX source code and operating system. We will build and install NGINX from obtained sources in a later step. When obtaining NGINX sources from Github, please ensure that you switch to the branch that you intend to use with the module binary. For simplicity, we will assume that the `main` branch will be used for the remainder of this tutorial.
28+
### Installing the OTel Module from Packages
29+
Once remote package repositories have been added and local package records have been updated, you may install the OTel module (`nginx-module-otel`) for your specific operating system. As an example, run the following commands to install on:
3230

31+
#### RedHat, RHEL and Derivatives
3332
```bash
34-
git clone https://github.com/nginx/nginx.git
33+
sudo yum install nginx-module-otel
3534
```
3635

37-
Configure NGINX to generate files necessary for dynamic module compilation. These files will be placed into the `nginx/objs` directory.
38-
39-
**Important:** If you did not obtain NGINX source code via the clone method in the previous step, you will need to adjust paths in the following commands to conform to your specific directory structure.
40-
```bash
41-
cd nginx
42-
auto/configure --with-compat
43-
```
44-
45-
Exit the NGINX directory and clone the `ngx_otel_module` repository.
46-
```bash
47-
cd ..
48-
git clone https://github.com/nginxinc/nginx-otel.git
49-
```
50-
51-
Configure and build the NGINX OTel module.
52-
53-
**Important**: replace the path in the `cmake` command with the path to the `nginx/objs` directory from above.
36+
#### Debian, Ubuntu and derivatives
5437
```bash
55-
cd nginx-otel
56-
mkdir build
57-
cd build
58-
cmake -DNGX_OTEL_NGINX_BUILD_DIR=/path/to/configured/nginx/objs ..
59-
make
38+
sudo apt install nginx-module-otel
6039
```
6140

62-
Compilation will produce a binary named `ngx_otel_module.so`.
63-
64-
## Installation
65-
***Important:*** The built `ngx_otel_module.so` dynamic module binary will ONLY be compatible with the same version of NGINX source code that was used to build it. To guarantee proper operation, you will need to build and install NGINX from sources obtained in previous steps on the same operating system.
66-
67-
Follow [instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source) related to compiling and installing NGINX. Skip procedures for downloading source code.
68-
69-
By default, this will install NGINX into `/usr/local/nginx`. The following steps assume this directory structure.
70-
71-
Copy the `ngx_otel_module.so` dynamic module binary to `/usr/local/nginx/modules`.
72-
73-
Load the module by adding the following line to the top of the main NGINX configuration file, located at: `/usr/local/nginx/conf/nginx.conf`.
41+
### Enabling the OTel Module
42+
Following the installation steps above will install the module into `/etc/nginx/modules` by default. Load the module by adding the following line to the top of the main NGINX configuration file, located at `/etc/nginx/nginx.conf`.
7443

7544
```nginx
7645
load_module modules/ngx_otel_module.so;
@@ -148,6 +117,65 @@ http {
148117
## Collecting and Viewing Traces
149118
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.
150119

120+
## Building
121+
Follow these steps to build the `ngx_otel_module` dynamic module on Ubuntu or Debian based systems:
122+
123+
Install build tools and dependencies.
124+
```bash
125+
sudo apt install cmake build-essential libssl-dev zlib1g-dev libpcre3-dev
126+
sudo apt install pkg-config libc-ares-dev libre2-dev # for gRPC
127+
```
128+
129+
For the next step, you will need the `configure` script that is packaged with the NGINX source code. There are several methods for obtaining NGINX sources. You may choose to [download](http://hg.nginx.org/nginx/archive/tip.tar.gz) them or clone them directly from the [NGINX Github repository](https://github.com/nginx/nginx).
130+
131+
**Important:** To ensure compatibility, the `ngx_otel_module` and the NGINX binary that it will be used with, will need to be built using the same NGINX source code and operating system. We will build and install NGINX from obtained sources in a later step. When obtaining NGINX sources from Github, please ensure that you switch to the branch that you intend to use with the module binary. For simplicity, we will assume that the `main` branch will be used for the remainder of this tutorial.
132+
133+
```bash
134+
git clone https://github.com/nginx/nginx.git
135+
```
136+
137+
Configure NGINX to generate files necessary for dynamic module compilation. These files will be placed into the `nginx/objs` directory.
138+
139+
**Important:** If you did not obtain NGINX source code via the clone method in the previous step, you will need to adjust paths in the following commands to conform to your specific directory structure.
140+
```bash
141+
cd nginx
142+
auto/configure --with-compat
143+
```
144+
145+
Exit the NGINX directory and clone the `ngx_otel_module` repository.
146+
```bash
147+
cd ..
148+
git clone https://github.com/nginxinc/nginx-otel.git
149+
```
150+
151+
Configure and build the NGINX OTel module.
152+
153+
**Important**: replace the path in the `cmake` command with the path to the `nginx/objs` directory from above.
154+
```bash
155+
cd nginx-otel
156+
mkdir build
157+
cd build
158+
cmake -DNGX_OTEL_NGINX_BUILD_DIR=/path/to/configured/nginx/objs ..
159+
make
160+
```
161+
162+
Compilation will produce a binary named `ngx_otel_module.so`.
163+
164+
## Installing from Built Binaries
165+
***Important:*** The built `ngx_otel_module.so` dynamic module binary will ONLY be compatible with the same version of NGINX source code that was used to build it. To guarantee proper operation, you will need to build and install NGINX from sources obtained in previous steps on the same operating system.
166+
167+
Follow [instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source) related to compiling and installing NGINX. Skip procedures for downloading source code.
168+
169+
By default, this will install NGINX into `/usr/local/nginx`. The following steps assume this directory structure.
170+
171+
Copy the `ngx_otel_module.so` dynamic module binary to `/usr/local/nginx/modules`.
172+
173+
Load the module by adding the following line to the top of the main NGINX configuration file, located at `/usr/local/nginx/conf/nginx.conf`.
174+
175+
```nginx
176+
load_module modules/ngx_otel_module.so;
177+
```
178+
151179
# Community
152180
- 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.
153181

0 commit comments

Comments
 (0)