Skip to content

Commit 3b1c78e

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 3b1c78e

31 files changed

+1093
-1151
lines changed

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

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

8268
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.
9269

@@ -778,7 +1038,7 @@ Below are the available NGINX Plus metrics:
7781038
`logtype`
7791039
</td>
7801040
<td>
781-
The type of log being collected (applicable to logs only). Used by New Relic's built-in [parsing rules](https://docs.newrelic.com/docs/logs/ui-data/built-log-parsing-rules/#nginx)
1041+
The type of log being collected (applicable to logs only). Used by New Relic's built-in [parsing rules](https://docs.newrelic.com/docs/logs/ui-data/built-log-parsing-rules/#nginx). This attribute is only available when log forwarding is enabled.
7821042
</td>
7831043
<td>
7841044
`nginx` (for access logs), `nginx-error` (for error logs)

0 commit comments

Comments
 (0)