Skip to content

Commit 43fd0cb

Browse files
ADubhlaoichy82
ADubhlaoich
and
y82
authored
feat: Add OpenTelemetry documentation (#824)
This commit adds OpenTelemetry documentation for NGINX Ingress Controller, converting an example hidden in the code repository. It adds it to the "Logging and monitoring" section, where the prior OpenTracing document has also been moved. The latter document has had an explicit warning call-out added to the top directing users to the new document, and the release page now links directly to the new configuration document for context. Some page titles and metadata in the section have also been updated as part of this work, to ensure the user experience is more consistent. Co-authored-by: yar <y82@users.noreply.github.com>
1 parent bbb3861 commit 43fd0cb

File tree

9 files changed

+187
-60
lines changed

9 files changed

+187
-60
lines changed

‎content/nic/configuration/global-configuration/configmap-resource.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic
235235
|*otel-exporter-header-value* | The value of a custom HTTP header to add to telemetry export request. `otel-exporter-endpoint` and `otel-exporter-header-name` required. | N/A | *"custom-value"* |
236236
|*otel-service-name* | Sets the `service.name` attribute of the OTel resource. `otel-exporter-endpoint` required. | N/A | *"nginx-ingress-controller:nginx"* |
237237
| *otel-trace-in-http* | Enables [OpenTelemetry](https://opentelemetry.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Set this to *"false"* to enable OpenTelemetry for individual routes with snippets. `otel-exporter-endpoint` required. | *"false"* | *"true"* |
238-
|*opentracing* | Removed in v5.0.0. Enables [OpenTracing](https://opentracing.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the [docs]({{< ref "/nic/installation/integrations/opentracing.md" >}}) for more information. | *False* | |
238+
|*opentracing* | Removed in v5.0.0. Enables [OpenTracing](https://opentracing.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the [docs]({{< ref "/nic/logging-and-monitoring/opentracing.md" >}}) for more information. | *False* | |
239239
|*opentracing-tracer* | Removed in v5.0.0. Sets the path to the vendor tracer binary plugin. | N/A | |
240240
|*opentracing-tracer-config* | Removed in v5.0.0. Sets the tracer configuration in JSON format. | N/A | |
241241
|*app-protect-compressed-requests-action* | Sets the *app_protect_compressed_requests_action* [global directive](/nginx-app-protect/configuration/#global-directives). | *drop* | |

‎content/nic/logging-and-monitoring/_index.md

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
---
2-
title: Logging And Monitoring
2+
title: Logging and monitoring
33
description:
44
weight: 1500
55
url: /nginx-ingress-controller/logging-and-monitoring
6-
menu:
7-
docs:
8-
parent: NGINX Ingress Controller
96
---

‎content/nic/logging-and-monitoring/logging.md

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,37 @@
11
---
2-
title: Logging
2+
title: Logs available from NGINX Ingress Controller
33
toc: true
4-
weight: 1800
4+
weight: 100
55
nd-content-type: reference
66
nd-product: NIC
77
nd-docs: DOCS-613
88
---
99

10-
This document gives an overview of logging provided by NGINX Ingress Controller.
10+
This document gives an overview of logging provided by F5 NGINX Ingress Controller.
1111

12-
NGINX Ingress Controller exposes the logs of the Ingress Controller process (the process that generates NGINX configuration and reloads NGINX to apply it) and NGINX access and error logs. All logs are sent to the standard output and error of the NGINX Ingress Controller process. To view the logs, you can execute the `kubectl logs` command for an Ingress Controller pod. For example:
12+
NGINX Ingress Controller exposes the logs of the Ingress Controller process (The process that generates NGINX configuration and reloads NGINX to apply it) and NGINX access and error logs.
13+
14+
All logs are sent to the standard output and error of the NGINX Ingress Controller process. To view the logs, you can execute the `kubectl logs` command for an Ingress Controller pod.
15+
16+
For example:
1317

1418
```shell
1519
kubectl logs <nginx-ingress-pod> -n nginx-ingress
1620
```
1721

1822
## NGINX Ingress Controller Process Logs
1923

20-
The NGINX Ingress Controller process logs are configured through the `-log-level` command-line argument of the NGINX Ingress Controller, which sets the log level. The default value is `info`. Other options include: `trace`, `debug`, `info`, `warning`, `error` and `fatal`. The value `debug` is useful for troubleshooting: you will be able to see how NGINX Ingress Controller gets updates from the Kubernetes API, generates NGINX configuration and reloads NGINX.
24+
The NGINX Ingress Controller process logs are configured through the `-log-level` command-line argument of the NGINX Ingress Controller, which sets the log level.
25+
26+
The default value is `info`. Other options include: `trace`, `debug`, `info`, `warning`, `error` and `fatal`.
27+
28+
The value `debug` is useful for troubleshooting: you will be able to see how NGINX Ingress Controller gets updates from the Kubernetes API, generates NGINX configuration and reloads NGINX.
2129

22-
See also the doc about NGINX Ingress Controller [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}).
30+
Read more about NGINX Ingress Controller [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}).
2331

2432
## NGINX Logs
2533

26-
The NGINX includes two logs:
34+
NGINX includes two logs:
2735

2836
- *Access log*, where NGINX writes information about client requests in the access log right after the request is processed. The access log is configured via the [logging-related]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#logging" >}}) ConfigMap keys:
2937
- `log-format` for HTTP and HTTPS traffic.
@@ -32,4 +40,4 @@ The NGINX includes two logs:
3240
Additionally, you can disable access logging with the `access-log-off` ConfigMap key.
3341
- *Error log*, where NGINX writes information about encountered issues of different severity levels. It is configured via the `error-log-level` [ConfigMap key]({{< ref "/nic/configuration/global-configuration.md#configmap-resource#logging" >}}). To enable debug logging, set the level to `debug` and also set the `-nginx-debug` [command-line argument]({{< ref "/nic/configuration/global-configuration.md#command-line-arguments" >}}), so that NGINX is started with the debug binary `nginx-debug`.
3442

35-
See also the doc about [NGINX logs]({{< ref "/nginx/admin-guide/monitoring/logging.md" >}}) from NGINX Admin guide.
43+
Read more about [NGINX logs]({{< ref "/nginx/admin-guide/monitoring/logging.md" >}}) from NGINX Admin guide.

‎content/nic/logging-and-monitoring/opentelemetry.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
# We use sentence case and present imperative tone
3+
title: "Enable OpenTelemetry"
4+
# Weights are assigned in increments of 100: determines sorting order
5+
weight: 300
6+
# Creates a table of contents and sidebar, useful for large documents
7+
toc: true
8+
# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
9+
nd-content-type: how-to
10+
# Intended for internal catalogue and search, case sensitive:
11+
# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
12+
nd-product: NIC
13+
---
14+
15+
This topic describes how to enable [OpenTelemetry](https://opentelemetry.io/) for F5 NGINX Ingress Controller using the [native NGINX module](https://nginx.org/en/docs/ngx_otel_module.html).
16+
17+
## Before you begin
18+
19+
To complete this guide, you need the following pre-requisites:
20+
21+
- An [NGINX Ingress Controller installation]({{< ref "/nic/installation/" >}}) with OpenTelemetry (v5.1.0+)
22+
23+
## Load the OpenTelemetry module
24+
25+
To enable OpenTelemetry, you must first load the module by adding the [_otel-exporter-endpoint_ ConfigMap key]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#modules" >}}), which takes an endpoint argument.
26+
27+
The following is an example of a OpenTelemetry collector running in your cluster as the target for exporting data:
28+
29+
```yaml
30+
otel-exporter-endpoint: "http://otel-collector.default.svc.cluster.local:4317"
31+
```
32+
33+
A complete ConfigMap example with all OpenTelemetry options could look as follows:
34+
35+
{{< ghcode "https://raw.githubusercontent.com/nginx/kubernetes-ingress/refs/heads/main/examples/shared-examples/otel/nginx-config.yaml" >}}
36+
37+
## Enable OpenTelemetry
38+
39+
Once you have loaded the module, you can now enable OpenTelemetry.
40+
41+
You can configure it globally for all resources, or on a per resource basis.
42+
43+
### Global
44+
45+
To enable OpenTelemetry for all resources, set the _otel-trace-in-http_ ConfigMap key to `true`:
46+
47+
```yaml
48+
otel-trace-in-http: "true"
49+
```
50+
51+
### Per resource
52+
53+
You can configure OpenTelemetry on a per resource basis in NGINX Ingress Controller.
54+
55+
For this functionality, you must [enable snippets]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) with the `-enable-snippets` command-line argument.
56+
57+
Based on the state of global configuration, you can selectively enable or disable metrics for each resource.
58+
59+
#### Enable a specific resource or path
60+
61+
With OpenTelemetry **disabled** globally, you can enable it for a specific resource using the server snippet annotation:
62+
63+
```yaml
64+
nginx.org/server-snippets: |
65+
otel_trace on;
66+
```
67+
68+
You can enable it for specific paths using [Mergeable Ingress resources]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}).
69+
70+
Use the server snippet annotation for the paths of a specific Minion Ingress resource:
71+
72+
```yaml
73+
nginx.org/location-snippets: |
74+
otel_trace on;
75+
```
76+
77+
#### Disable a specific resource or path
78+
79+
With OpenTelemetry **enabled** globally, you can disable it for a specific resource using the server snippet annotation:
80+
81+
```yaml
82+
nginx.org/server-snippets: |
83+
otel_trace off;
84+
```
85+
86+
You can disable it for specific paths using [Mergeable Ingress resources]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}).
87+
88+
Use the server snippet annotation for the paths of a specific Minion Ingress resource:
89+
90+
```yaml
91+
nginx.org/location-snippets: |
92+
otel_trace off;
93+
```
94+
95+
## Customize OpenTelemetry
96+
97+
{{< call-out "note" >}}
98+
99+
You cannot modify the additional directives in the _otel_exporter_ block using snippets.
100+
101+
{{< /call-out >}}
102+
103+
You can customize OpenTelemetry through the supported [OpenTelemetry module directives](https://nginx.org/en/docs/ngx_otel_module.html).
104+
105+
Use the `location-snippets` ConfigMap keys or annotations to insert those directives into the generated NGINX configuration.

‎content/nic/installation/integrations/opentracing.md renamed to ‎content/nic/logging-and-monitoring/opentracing.md

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,24 @@
11
---
2-
nd-docs: DOCS-618
3-
doctypes:
4-
- ''
5-
title: OpenTracing (Removed in v5.0.0)
2+
title: Enable OpenTracing (Removed in v5.0.0)
63
toc: true
7-
weight: 500
4+
weight: 700
5+
nd-content-type: how-to
6+
nd-product: NIC
7+
nd-docs: DOCS-618
88
---
9-
OpenTracing support has been removed from v5.0.0 of F5 NGINX Ingress Controller.
109

11-
12-
Learn how to use OpenTracing with F5 NGINX Ingress Controller.
10+
This topic describes how to OpenTracing with F5 NGINX Ingress Controller.
1311

1412
NGINX Ingress Controller supports [OpenTracing](https://opentracing.io/) with the third-party module [opentracing-contrib/nginx-opentracing](https://github.com/opentracing-contrib/nginx-opentracing).
1513

14+
{{< call-out "warning" >}}
15+
16+
OpenTracing support has been removed from v5.0.0 of NGINX Ingress Controller.
17+
18+
From v5.1.0 onwards, you should follow the guidance in [Configure OpenTelemetry]({{< ref "/nic/logging-and-monitoring/opentelemetry.md" >}}).
19+
20+
{{< /call-out >}}
21+
1622
## Prerequisites
1723

1824
1. Use a NGINX Ingress Controller image that contains OpenTracing.

‎content/nic/logging-and-monitoring/prometheus.md

Lines changed: 30 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,41 @@
11
---
2-
nd-docs: DOCS-614
3-
doctypes:
4-
- concept
5-
title: Prometheus
2+
title: Enable Prometheus metrics
63
toc: true
7-
weight: 2000
4+
weight: 400
5+
nd-content-type: how-to
6+
nd-product: NIC
7+
nd-docs: DOCS-614
88
---
99

10-
NGINX Ingress Controller exposes metrics in the [Prometheus](https://prometheus.io/) format. Those include NGINX/NGINX Plus and the Ingress Controller metrics.
10+
This topic describes how to enable [Prometheus metrics](https://prometheus.io/) for F5 NGINX Ingress Controller.
11+
12+
The metrics exposed include NGINX Ingress Controller data, as well as NGINX Open Source and NGINX Plus.
1113

1214
## Enabling Metrics
1315

16+
### Using Helm
17+
18+
To enable Prometheus metrics when using *Helm* to install NGINX Ingress Controller, configure the `prometheus.*` parameters of the Helm chart.
19+
20+
See the [Installation with Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md" >}}) topic.
21+
22+
#### Using ServiceMonitor
23+
24+
When deploying with *Helm*, you can deploy a `Service` and `ServiceMonitor` resource using the `prometheus.service.*` and `prometheus.serviceMonitor.*` parameters.
25+
When these resources are deployed, Prometheus metrics exposed by NGINX Ingress Controller can be captured and enumerated using a `Prometheus` resource alongside a Prometheus Operator deployment.
26+
27+
To view metrics captured this way, you will need:
28+
29+
* A working [Prometheus resource and Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/introduction/)
30+
* The latest ServiceMonitor CRD from the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) repository:
31+
32+
```shell
33+
LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name)
34+
curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$LATEST/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml | kubectl create -f -
35+
```
36+
1437
### Using Manifests
38+
1539
If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable Prometheus metrics:
1640

1741
1. Run the Ingress Controller with the `-enable-prometheus-metrics` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). As a result, the Ingress Controller will expose NGINX or NGINX Plus metrics in the Prometheus format via the path `/metrics` on port `9113` (customizable via the `-prometheus-metrics-listen-port` command-line argument).
@@ -32,23 +56,6 @@ If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the
3256
prometheus.io/scheme: http
3357
```
3458
35-
### Using Helm
36-
37-
If you're using *Helm* to install the Ingress Controller, to enable Prometheus metrics, configure the `prometheus.*` parameters of the Helm chart. See the [Installation with Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md" >}}) doc.
38-
39-
### Using ServiceMonitor
40-
41-
When deploying with *Helm*, you can deploy a `Service` and `ServiceMonitor` resource using the `prometheus.service.*` and `prometheus.serviceMonitor.*` parameters.
42-
When these resources are deployed, Prometheus metrics exposed by NGINX Ingress Controller can be captured and enumerated using a `Prometheus` resource alongside a Prometheus Operator deployment.
43-
44-
To view metrics captured this way, the following is required:
45-
* The latest ServiceMonitor CRD from the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) repository:
46-
```shell
47-
LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name)
48-
curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$LATEST/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml | kubectl create -f -
49-
```
50-
* A working [Prometheus resource and Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/introduction/)
51-
5259
## Available Metrics
5360
5461
The Ingress Controller exports the following metrics:

‎content/nic/logging-and-monitoring/service-insight.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: Service Insight
2+
title: Enable Service Insight
33
toc: true
4-
weight: 2100
4+
weight: 600
55
nd-content-type: how-to
66
nd-product: NIC
77
nd-docs: DOCS-1180

‎content/nic/logging-and-monitoring/status-page.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: Status Page
2+
title: View the NGINX status page
33
toc: true
4-
weight: 1900
4+
weight: 200
55
nd-content-type: how-to
66
nd-product: NIC
77
nd-docs: DOCS-615

0 commit comments

Comments
 (0)