feat: Add OpenTelemetry documentation

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

@@ -235,7 +235,7 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic
 |*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"* |
 |*otel-service-name* | Sets the `service.name` attribute of the OTel resource. `otel-exporter-endpoint` required. | N/A | *"nginx-ingress-controller:nginx"* |
 | *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"* |
-|*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* | |
+|*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* | |
 |*opentracing-tracer* | Removed in v5.0.0. Sets the path to the vendor tracer binary plugin. | N/A | |
 |*opentracing-tracer-config* | Removed in v5.0.0. Sets the tracer configuration in JSON format. | N/A | |
 |*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

@@ -1,9 +1,6 @@
 ---
-title: Logging And Monitoring
+title: Logging and monitoring
 description:
 weight: 1500
 url: /nginx-ingress-controller/logging-and-monitoring
-menu:
- docs:
- parent: NGINX Ingress Controller
 ---

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

@@ -1,29 +1,37 @@
 ---
-title: Logging
+title: Logs available from NGINX Ingress Controller
 toc: true
-weight: 1800
+weight: 100
 nd-content-type: reference
 nd-product: NIC
 nd-docs: DOCS-613
 ---
 
-This document gives an overview of logging provided by NGINX Ingress Controller.
+This document gives an overview of logging provided by F5 NGINX Ingress Controller.
 
-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:
+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:
 
 ```shell
 kubectl logs <nginx-ingress-pod> -n nginx-ingress
 ```
 
 ## NGINX Ingress Controller Process Logs
 
-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.
+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.
 
-See also the doc about NGINX Ingress Controller [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}).
+Read more about NGINX Ingress Controller [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}).
 
 ## NGINX Logs
 
-The NGINX includes two logs:
+NGINX includes two logs:
 
 - *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:
  - `log-format` for HTTP and HTTPS traffic.
@@ -32,4 +40,4 @@ The NGINX includes two logs:
  Additionally, you can disable access logging with the `access-log-off` ConfigMap key.
 - *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`.
 
-See also the doc about [NGINX logs]({{< ref "/nginx/admin-guide/monitoring/logging.md" >}}) from NGINX Admin guide.
+Read more about [NGINX logs]({{< ref "/nginx/admin-guide/monitoring/logging.md" >}}) from NGINX Admin guide.

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

@@ -0,0 +1,100 @@
+---
+# We use sentence case and present imperative tone
+title: "Enable OpenTelemetry"
+# Weights are assigned in increments of 100: determines sorting order
+weight: 300
+# Creates a table of contents and sidebar, useful for large documents
+toc: true
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+nd-content-type: how-to
+# Intended for internal catalogue and search, case sensitive:
+# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+nd-product: NIC
+---
+
+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).
+
+## Before you begin
+
+To complete this guide, you need the following pre-requisites:
+
+- An [NGINX Ingress Controller installation]({{< ref "/nic/installation/" >}}) with OpenTelemetry (v5.1.0+)
+- [Snippets enabled]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}), using the `-enable-snippets` command-line argument
+
+## Load the OpenTelemetry module
+
+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.
+
+The following is an example of a OpenTelemetry collector running in your cluster as the target for exporting data:
+
+```yaml
+otel-exporter-endpoint: "http://otel-collector.default.svc.cluster.local:4317"
+```
+
+## Enable OpenTelemetry
+
+Once you have loaded the module, you can now enable OpenTelemetry.
+
+You can configure it globally for all resources, or on a per resource basis.
+
+### Global
+
+To enable OpenTelemetry for all resources, set the _otel-trace-in-http_ ConfigMap key to `true`:
+
+```yaml
+otel-trace-in-http: "true"
+```
+
+### Per resource
+
+You can configure OpenTracing on a per resource basis in NGINX Ingress Controller.
+
+Based on the state of global configuration, you can selectively enable or disable metrics for each resource.
+
+#### Enabling a specific resource or path
+
+With OpenTelemetry **disabled** globally, you can enable it for a specific resource using the server snippet annotation:
+
+```yaml
+nginx.org/server-snippets: |
+ otel_trace on;
+```
+
+You can enable it for specific paths using [Mergeable Ingress resources]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}).
+
+Use the server snippet annotation for the paths of a specific Minion Ingress resource:
+
+```yaml
+nginx.org/location-snippets: |
+ otel_trace on;
+```
+
+#### Disable a specific resource or path
+
+With OpenTelemetry **enabled** globally, you can disable it for a specific resource using the server snippet annotation:
+
+ ```yaml
+nginx.org/server-snippets: |
+ otel_trace off;
+```
+
+You can disable it for specific paths using [Mergeable Ingress resources]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}).
+
+Use the server snippet annotation for the paths of a specific Minion Ingress resource:
+
+```yaml
+nginx.org/location-snippets: |
+ otel_trace off;
+```
+
+## Customize OpenTelemetry
+
+{{< call-out "note" >}}
+
+You cannot modify the additional directives in the _otel_exporter_ block using snippets.
+
+{{< /call-out >}}
+
+You can customize OpenTelemetry through the supported [OpenTelemetry module directives](https://nginx.org/en/docs/ngx_otel_module.html). 
+
+Use the `location-snippets` ConfigMap keys or annotations to insert those directives into the generated NGINX configuration.

content/nic/installation/integrations/opentracing.md → content/nic/logging-and-monitoring/opentracing.md

@@ -1,13 +1,21 @@
 ---
-nd-docs: DOCS-618
-doctypes:
-- ''
 title: OpenTracing (Removed in v5.0.0)
 toc: true
-weight: 500
+weight: 700
+nd-content-type: how-to
+nd-product: NIC
+nd-docs: DOCS-618
 ---
+
+{{< call-out "warning" "OpenTracing is removed from v5.0.0" >}}
+
 OpenTracing support has been removed from v5.0.0 of F5 NGINX Ingress Controller.
 
+From v5.1.0 onwards, you should follow the guidance in [Configure OpenTelemetry]({{< ref "/nic/logging-and-monitoring/opentelemetry.md" >}}).
+
+{{< /call-out >}}
+
+
 
 Learn how to use OpenTracing with F5 NGINX Ingress Controller.
 

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

@@ -1,17 +1,41 @@
 ---
-nd-docs: DOCS-614
-doctypes:
-- concept
-title: Prometheus
+title: Enable Prometheus metrics
 toc: true
-weight: 2000
+weight: 400
+nd-content-type: how-to
+nd-product: NIC
+nd-docs: DOCS-614
 ---
 
-NGINX Ingress Controller exposes metrics in the [Prometheus](https://prometheus.io/) format. Those include NGINX/NGINX Plus and the Ingress Controller metrics.
+This topic describes how to enable [Prometheus metrics](https://prometheus.io/) for F5 NGINX Ingress Controller.
+
+The metrics exposed include NGINX Ingress Controller data, as well as NGINX Open Source and NGINX Plus.
 
 ## Enabling Metrics
 
+### Using Helm
+
+To enable Prometheus metrics when using *Helm* to install NGINX Ingress Controller, configure the `prometheus.*` parameters of the Helm chart. 
+
+See the [Installation with Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md" >}}) topic.
+
+#### Using ServiceMonitor
+
+When deploying with *Helm*, you can deploy a `Service` and `ServiceMonitor` resource using the `prometheus.service.*` and `prometheus.serviceMonitor.*` parameters.
+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.
+
+To view metrics captured this way, you will need:
+
+* A working [Prometheus resource and Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/introduction/)
+* The latest ServiceMonitor CRD from the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) repository:
+
+```shell
+LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name)
+curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$LATEST/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml | kubectl create -f -
+```
+
 ### Using Manifests
+
 If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable Prometheus metrics:
 
 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
  prometheus.io/scheme: http
  ```
 
-### Using Helm
-
-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.
-
-### Using ServiceMonitor
-
-When deploying with *Helm*, you can deploy a `Service` and `ServiceMonitor` resource using the `prometheus.service.*` and `prometheus.serviceMonitor.*` parameters.
-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.
-
-To view metrics captured this way, the following is required:
-* The latest ServiceMonitor CRD from the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) repository:
-```shell
-LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name)
-curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$LATEST/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml | kubectl create -f -
-```
-* A working [Prometheus resource and Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/introduction/)
-
 ## Available Metrics
 
 The Ingress Controller exports the following metrics:

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

@@ -1,7 +1,7 @@
 ---
-title: Service Insight
+title: Enable Service Insight
 toc: true
-weight: 2100
+weight: 600
 nd-content-type: how-to
 nd-product: NIC
 nd-docs: DOCS-1180

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

@@ -1,7 +1,7 @@
 ---
-title: Status Page
+title: View the NGINX status page
 toc: true
-weight: 1900
+weight: 200
 nd-content-type: how-to
 nd-product: NIC
 nd-docs: DOCS-615

content/nic/releases.md

@@ -14,11 +14,11 @@ This NGINX Ingress Controller release brings initial connectivity to the NGINX O
 
 This release also includes the ability to configure Rate Limiting for your APIs based on a specific NGINX variable and its value. This allows you more granular control over how frequently specific users access your resources.
 
-Lastly, in our previous v5.0.0 release, we removed support for Open Tracing. This release replaces that observability capability with native NGINX Open Telemetry traces, allowing you to monitor the internal traffic of your applications.
+Lastly, in our previous v5.0.0 release, we removed support for OpenTracing. This release replaces that observability capability with native [NGINX OpenTelemetry]({{< ref "/nic/logging-and-monitoring/opentelemetry.md" >}}) traces, allowing you to monitor the internal traffic of your applications.
 
 ### <i class="fa-solid fa-rocket"></i> Features
-- [7642](https://github.com/nginx/kubernetes-ingress/pull/7642) Add OpenTelemetry support
-- [7916](https://github.com/nginx/kubernetes-ingress/pull/7916) Add support for NGINX Agent version 3 and Connecting to NGINX One Console
+- [7642](https://github.com/nginx/kubernetes-ingress/pull/7642) Add [OpenTelemetry support]({{< ref "/nic/logging-and-monitoring/opentelemetry.md" >}})
+- [7916](https://github.com/nginx/kubernetes-ingress/pull/7916) Add support for NGINX Agent version 3 and NGINX One Console
 - [7884](https://github.com/nginx/kubernetes-ingress/pull/7884) Tiered rate limits with variables
 - [7765](https://github.com/nginx/kubernetes-ingress/pull/7765) Add OIDC PKCE configuration through Policy
 - [7832](https://github.com/nginx/kubernetes-ingress/pull/7832) Add request_method to rate-limit Policy
@@ -63,17 +63,21 @@ versions: 1.25-1.33.
 
 Added support for [NGINX Plus R34]({{< ref "/nginx/releases.md#nginxplusrelease-34-r34" >}}), users needing to use a forward proxy for license verification are now able to make use of the [`proxy`](https://nginx.org/en/docs/ngx_mgmt_module.html#proxy) directives available in F5 NGINX Plus.
 
-{{< important >}}
-With the removal of the OpenTracing dynamic module from [NGINX Plus R34](({{< ref "/nginx/releases.md#nginxplusrelease-34-r34" >}}), NGINX Ingress Controller also removes full OpenTracing support. This will affect users making use of OpenTracing with the ConfigMap, `server-snippets` & `location-snippets` parameters. Support for tracing with [OpenTelemetry]({{< ref "/nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) will come in a future release.
-{{< /important >}}
+{{< call-out "warning" >}}
+
+With the removal of the OpenTracing dynamic module from [NGINX Plus R34]({{< ref "/nginx/releases.md#nginxplusrelease-34-r34" >}}), NGINX Ingress Controller also removes full OpenTracing support. This will affect users making use of OpenTracing with the ConfigMap, `server-snippets` & `location-snippets` parameters. Support for tracing with [OpenTelemetry]({{< ref "/nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) will come in a future release.
+
+{{< /call-out >}}
 
 We have extended the rate-limit Policy to allow tiered rate limit groups with JWT claims. This will also allow users to apply different rate limits to their `VirtualServer` or `VirtualServerRoutes` with the value of a JWT claim. See [here](https://github.com/nginx/kubernetes-ingress/tree/v5.0.0/examples/custom-resources/rate-limit-tiered-jwt-claim/) for a working example.
 
 We introduced NGINX Plus Zone Sync as a managed service within NGINX Ingress Controller in this release. In previous releases, we had examples using `stream-snippets` for OIDC support, users can now enable `zone-sync` without the need for `snippets`. NGINX Plus Zone Sync is available when utilising two or more replicas, it supports OIDC & rate limiting.
 
-{{< note >}}
+{{< call-out "note" >}}
+
 For users who have previously installed OIDC or used the `zone_sync` directive with `stream-snippets`, please see the note in the [Configmap resources]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#zone-sync" >}}) topic to use the new `zone-sync` ConfigMap option.
-{{< /note >}}
+
+{{< /call-out >}}
 
 Open Source NGINX Ingress Controller architectures `armv7`, `s390x` & `ppc64le` are deprecated and will be removed in the next minor release.
 
@@ -215,14 +219,14 @@ versions: 1.25-1.32.
 
 25 Nov 2024
 
-{{< note >}}
+{{< call-out "note" >}}
 In our next major release, `v4.0.0`, the default log library for NGINX Ingress Controller will be changed from `golang/glog` to `log/slog`.
 This will mean that logs generated by NGINX Ingress Controller will be in a structured format with the option to choose a `string` or `json` output.
 This will not affect logs generated by NGINX.
 To ensure backwards compatibility, we will ensure the existing log format, `glog`, will be maintained through a configuration option for the next 3 releases.
-{{< /note >}}
+{{< /call-out >}}
 
-{{< important >}}
+{{< call-out "important" >}}
 CRD version removal notice.
 In our next major release, `v4.0.0`, support for the following apiVersions for these listed CRDs will be dropped:
 1. `k8s.nginx.org/v1alpha` for `GlobalConfiguration`
@@ -233,7 +237,7 @@ Prior to upgrading, **please ensure** that any of these resources deployed as `a
 If a resource of `kind: GlobalConfiguration`, `kind: Policy` or `kind: TransportServer` are deployed as `apiVersion: k8s.nginx.org/v1alpha1`, these resources will be **deleted** when upgrading from, at least, `v3.4.0` to `v4.0.0`
 
 When `v4.0.0` is released, the release notes will contain the required upgrade steps to go from `v3.X.X` to `v4.X.X`
-{{< /important >}}
+{{< /call-out >}}
 
 ### <i class="fa-solid fa-bug-slash"></i> Fixes
 - [6838](https://github.com/nginx/kubernetes-ingress/pull/6838) Update oidc_template and conf