Skip to content

Commit 0b52dcd

Browse files
sairaj18sairaj18
committed
feat(nginx): move nginx otel to opentelemetry nav and combine all mdx files, create a single file for each deployment type
1 parent b04c166 commit 0b52dcd

29 files changed

+1051
-1150
lines changed

src/install/nginx-plus-otel/whatsNext.mdx renamed to src/content/docs/opentelemetry/nginx-plus/nginx-plus-otel.mdx

Lines changed: 253 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,259 @@
11
---
2-
headingText: Metrics collected
3-
componentType: default
2+
title: 'Monitor self-hosted NGINX Plus with OpenTelemetry'
3+
metaDescription: 'Send your NGINX Plus metrics to New Relic using the OpenTelemetry contrib collector.'
4+
redirects:
5+
- /docs/infrastructure/host-integrations/host-integrations-list/nginx/nginx-plus-otel
6+
freshnessValidatedDate: never
47
---
58

6-
## Metric data [#nginx-plus-metrics]
9+
Monitor your NGINX Plus servers using the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib) to send metrics and telemetry data to New Relic.
10+
This integration leverages the OpenTelemetry [prometheusreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver) and [nginx-prometheus-exporter](https://github.com/nginx/nginx-prometheus-exporter) to monitor your NGINX Plus performance metrics, connection statistics, and server health.
11+
12+
## Step 1: Check the compatibility and requirements [#prerequisites]
13+
14+
Before you begin, ensure you have:
15+
16+
- A [New Relic account](https://newrelic.com/signup) with a <InlinePopover type="licenseKey"/>
17+
- NGINX Plus version [R13](https://docs.nginx.com/nginx/releases/#r13) or higher
18+
- NGINX Plus with the [HTTP API](https://nginx.org/en/docs/http/ngx_http_api_module.html) module enabled
19+
- [NGINX Prometheus exporter](https://github.com/nginx/nginx-prometheus-exporter) installed and running alongside your NGINX Plus instance to expose HTTP API metrics in Prometheus format
20+
- [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases/latest) installed and running on a linux host
21+
- Network access from the linux host to:
22+
- NGINX Plus HTTP API endpoint
23+
- Anyone of the [New Relic OTLP](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol:~:text=HTTP-,Endpoint,-Supported%20ports) enpoint
24+
25+
## Step 2: Configure NGINX Plus [#configure-nginx]
26+
27+
Configure and enable the [HTTP API module](https://nginx.org/en/docs/http/ngx_http_api_module.html) to expose metrics from your NGINX Plus server.
28+
29+
After updating `nginx.conf`, test and reload the service:
30+
31+
```bash
32+
sudo nginx -t && sudo nginx -s reload
33+
```
34+
35+
Confirm the API endpoint path (including version) exposed in your configuration.
36+
37+
Record the full API endpoint path (without the leading slash) and the port that serves it. Common defaults are `api/9` on port `8080`.
38+
39+
Use `curl` to confirm your API endpoint is reachable:
40+
41+
```bash
42+
curl -I http://127.0.0.1:8080/api/9 2>/dev/null | head -n 1 | cut -d$' ' -f1,2
43+
```
44+
45+
Expected output:
46+
47+
```
48+
HTTP/1.1 200
49+
```
50+
51+
If you see a different response, verify your NGINX Plus configuration and ensure the API module is properly enabled.
52+
53+
## Step 3: Configure the OpenTelemetry Collector [#configure-collector]
54+
55+
In the below OpenTelemetry Collector config snippet:
56+
57+
- Update the `nginx.deployment.name` value to with a unique name to identify this NGINX Plus server in a New Relic account.
58+
- Update the `targets` value to match your Prometheus exporter host and port (default is `127.0.0.1:9113`).
59+
- Update the `nginx.server.endpoint` value to match your API status path and port.
60+
61+
Merge the receivers, processors, exporters, and service pipelines from the snippet below into your current configuration (typically located at `/etc/otelcol-contrib/config.yaml`).
62+
63+
Note: Update the `filter/nginx_metrics` as per your requirement under the processor section in order to ingest additional metrics.
64+
65+
```yaml
66+
receivers:
67+
prometheus:
68+
config:
69+
scrape_configs:
70+
- job_name: nginx-plus
71+
scrape_interval: 30s
72+
static_configs:
73+
- targets:
74+
- 127.0.0.1:9113
75+
processors:
76+
batch:
77+
send_batch_size: 1024
78+
timeout: 30s
79+
filter/nginx_metrics:
80+
metrics:
81+
include:
82+
match_type: regexp
83+
metric_names:
84+
- "nginxplus_connections_.*"
85+
- "nginxplus_http_requests_.*"
86+
- "nginxplus_ssl_.*"
87+
- "nginxplus_server_.*"
88+
- "nginxplus_location_zone_.*"
89+
- "nginxplus_cache_.*"
90+
91+
exclude:
92+
match_type: regexp
93+
metric_names:
94+
- "nginxplus_stream_server_.*"
95+
- "nginxplus_upstream_.*"
96+
- "nginxplus_stream_upstream_.*"
97+
- "nginxplus_stream_zone_sync_zone_.*"
98+
- "nginxplus_resolver_.*"
99+
- "nginxplus_limit_request_.*"
100+
- "nginxplus_limit_connection_.*"
101+
- "nginxplus_stream_limit_connection_.*"
102+
- "nginxplus_worker_.*"
103+
resource/nginx:
104+
attributes:
105+
- key: nginx.server.endpoint
106+
value: <API_ENDPOINT>
107+
action: insert
108+
- key: nginx.deployment.name
109+
value: <DEPLOYMENT_NAME>
110+
action: insert
111+
resourcedetection:
112+
detectors: [system]
113+
system:
114+
resource_attributes:
115+
host.name:
116+
enabled: true
117+
host.id:
118+
enabled: true
119+
transform/nginx:
120+
metric_statements:
121+
- context: resource
122+
statements:
123+
- set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))
124+
- context: resource
125+
statements:
126+
- delete_key(attributes, "service.name")
127+
exporters:
128+
otlphttp/newrelic:
129+
endpoint: ${env:NEWRELIC_OTLP_ENDPOINT}
130+
headers:
131+
api-key: ${env:NEWRELIC_LICENSE_KEY}
132+
service:
133+
pipelines:
134+
metrics/nginx:
135+
receivers: [prometheus]
136+
processors: [batch, filter/nginx_metrics, resourcedetection, resource/nginx, transform/nginx]
137+
exporters: [otlphttp/newrelic]
138+
```
139+
140+
Save the file and ensure the `otelcol-contrib` system user can read it.
141+
142+
## Step 4: Set environment variables for the collector [#set-environment]
143+
144+
Inject your New Relic <InlinePopover type="licenseKey"/> and OTLP endpoint into the collector service so the exporter can authenticate.
145+
146+
1. Create a systemd override directory:
147+
```bash
148+
sudo mkdir -p /etc/systemd/system/otelcol-contrib.service.d
149+
```
150+
2. Write `environment.conf` with your OTLP endpoint. Replace `YOUR_LICENSE_KEY` with the New Relic license key and `YOUR_OTLP_ENDPOINT` with the appropriate endpoint for your region. Refer to the OTLP endpoint configuration [documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) to select the right endpoint.
151+
152+
```bash
153+
cat <<EOF | sudo tee /etc/systemd/system/otelcol-contrib.service.d/environment.conf
154+
[Service]
155+
Environment="NEWRELIC_OTLP_ENDPOINT=YOUR_OTLP_ENDPOINT"
156+
Environment="NEWRELIC_LICENSE_KEY=YOUR_LICENSE_KEY"
157+
EOF
158+
```
159+
3. Reload systemd and restart the collector:
160+
```bash
161+
sudo systemctl daemon-reload
162+
sudo systemctl restart otelcol-contrib.service
163+
```
164+
165+
## Step 5: Forward NGINX logs and create log parsing rules [#forward-logs]
166+
167+
Extend your collector configuration to include access and error logs if you want log events alongside metrics.
168+
169+
### Configure NGINX Plus log format
170+
171+
Before forwarding logs, configure NGINX Plus to use a structured log format. Refer to the [NGINX logging documentation](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/) for guidance on configuring access and error logs.
172+
173+
### Configure the OpenTelemetry Collector for log forwarding
174+
175+
1. Note the full paths to your NGINX access and error log files. Defaults are usually `/var/log/nginx/access.log` and `/var/log/nginx/error.log`.
176+
177+
2. Update `/etc/otelcol-contrib/config.yaml` to add a `filelog` receiver and log pipeline:
178+
179+
```yaml
180+
receivers:
181+
prometheus:
182+
# existing Prometheus receiver configuration
183+
filelog/nginx_access_logs:
184+
include:
185+
- /var/log/nginx/access.log
186+
filelog/nginx_error_logs:
187+
include:
188+
- /var/log/nginx/error.log
189+
190+
processors:
191+
batch:
192+
# existing settings
193+
filter/nginx_metrics:
194+
# existing settings
195+
resourcedetection:
196+
# existing settings
197+
resource/nginx:
198+
# existing settings
199+
transform/nginx_metrics:
200+
# existing settings
201+
transform/nginx_access_logs:
202+
log_statements:
203+
- context: resource
204+
statements:
205+
- set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))
206+
- set(attributes["logtype"], "nginx")
207+
transform/nginx_error_logs:
208+
log_statements:
209+
- context: resource
210+
statements:
211+
- set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))
212+
- set(attributes["logtype"], "nginx-error")
213+
214+
exporters:
215+
# existing exporter setup
216+
217+
service:
218+
pipelines:
219+
metrics/nginx:
220+
receivers: [prometheus]
221+
processors: [batch, filter/nginx_metrics, resourcedetection, resource/nginx, transform/nginx_metrics]
222+
exporters: [otlphttp/newrelic]
223+
logs/nginx-access:
224+
receivers: [filelog/nginx_access_logs]
225+
processors: [batch, resource/nginx, transform/nginx_access_logs]
226+
exporters: [otlphttp/newrelic]
227+
logs/nginx-error:
228+
receivers: [filelog/nginx_error_logs]
229+
processors: [batch, resource/nginx, transform/nginx_error_logs]
230+
exporters: [otlphttp/newrelic]
231+
```
232+
233+
3. Grant the `otelcol-contrib` user read access to the log files:
234+
235+
```bash
236+
sudo usermod -a -G adm otelcol-contrib
237+
sudo chmod 644 /var/log/nginx/access.log
238+
sudo chmod 644 /var/log/nginx/error.log
239+
```
240+
241+
4. Restart the collector to apply the changes:
242+
243+
```bash
244+
sudo systemctl restart otelcol-contrib
245+
```
246+
247+
## Step 6: Find and use data [#find-data]
248+
249+
1. Go to **[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents**.
250+
2. Select **Dashboards**, and click **NGINX OTel overview dashboard**.
251+
3. In the popup window, select your account.
252+
4. Click View dashboard, and see your NGINX Plus data in New Relic.
253+
254+
The NGINX Plus metrics are attached to the `Metric` [event type](/docs/using-new-relic/data/understand-data/new-relic-data-types#events-new-relic). You can [query this data](/docs/using-new-relic/data/understand-data/query-new-relic-data) for troubleshooting purposes or to create custom charts and dashboards.
255+
256+
## Metrics collected [#metrics]
7257

8258
The OpenTelemetry Collector scrapes metrics from the [NGINX Prometheus exporter](https://github.com/nginx/nginx-prometheus-exporter), which exposes NGINX Plus HTTP API metrics in Prometheus format.
9259

0 commit comments

Comments
 (0)