From 08e1f5b076b9ff5092f6cd7b1c4777f46f06868d Mon Sep 17 00:00:00 2001 From: Aphral Griffin Date: Mon, 6 Oct 2025 13:33:53 +0100 Subject: [PATCH 1/4] feat: Add custom OTel configuration section --- .../agent/metrics/configure-otel-metrics.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/content/nginx-one/agent/metrics/configure-otel-metrics.md b/content/nginx-one/agent/metrics/configure-otel-metrics.md index 598017cf8..c9771fd1a 100644 --- a/content/nginx-one/agent/metrics/configure-otel-metrics.md +++ b/content/nginx-one/agent/metrics/configure-otel-metrics.md @@ -39,3 +39,91 @@ You can validate that metrics are successfully exported by using the methods bel ```text Everything is ready. Begin running and processing data. ``` + +### Custom OTel Configuration + +NGINX Agent generates a default OpenTelemetry config to send metrics to your management plane located at `/etc/nginx-agent/opentelemetry-collector-agent.yaml`. An option is provided to +bring your own OpenTelemetry configs which will be merged with the NGINX Agent default config. + +OpenTelemetry will merge your [OpenTelemetry Config](https://opentelemetry.io/). The order of the OpenTelemetry config files matters, +the last config in the list will take priority over others listed if they have the same value configured. + +To have NGINX Agent use your own OpenTelemetry config: + +1. Edit the configuration file `sudo vim /etc/nginx-agent/nginx-agent.conf` +2. Add the collector property + +```yaml +collector: + additional_config_paths: + - "/my_config.yaml" +``` + +### Example usage: + +{{< call-out "important" >}} NGINX Agent uses `/default` for naming its default processors, exporters and pipelines using the same naming in your own config might cause issues with sending metrics to your management plane {{< /call-out >}} + +#### Add Prometheus Exporter +```yaml +exporters: + prometheus: + endpoint: "127.0.0.1:5643" + resource_to_telemetry_conversion: + enabled: true + +service: + pipelines: + metrics/prometheus-example-pipeline: + receivers: + - containermetrics + - hostmetrics + processors: + - resource/default + exporters: + - prometheus +``` + +#### Add Debug Exporter +```yaml +exporters: + debug: + verbosity: detailed + sampling_initial: 5 + sampling_thereafter: 200 + +service: + pipelines: + metrics/debug-example-pipeline: + receivers: + - containermetrics + - hostmetrics + processors: + - resource/default + exporters: + - debug +``` + + +#### Debug Merging Configs + +To view the merged OpenTelemetry configuration set the Agent log level to debug in `/etc/nginx-agent/nginx-agent.conf` and restart NGINX Agent + +1. Edit the configuration file `sudo vim /etc/nginx-agent/nginx-agent.conf` +2. Change the log property +```yaml +log: + level: debug +``` +3. Restart NGINX Agent +4. View merged OpenTelemetry configuration `cat /var/lib/nginx-agent/opentelemetry-collector-agent-debug.yaml` + + + + + + + + + + + From b94a78da677166019850af406a91e10241dceadd Mon Sep 17 00:00:00 2001 From: Aphral Griffin Date: Mon, 6 Oct 2025 13:44:06 +0100 Subject: [PATCH 2/4] feat: change section headings --- .../agent/metrics/configure-otel-metrics.md | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/content/nginx-one/agent/metrics/configure-otel-metrics.md b/content/nginx-one/agent/metrics/configure-otel-metrics.md index c9771fd1a..c9388a5f0 100644 --- a/content/nginx-one/agent/metrics/configure-otel-metrics.md +++ b/content/nginx-one/agent/metrics/configure-otel-metrics.md @@ -63,7 +63,7 @@ collector: {{< call-out "important" >}} NGINX Agent uses `/default` for naming its default processors, exporters and pipelines using the same naming in your own config might cause issues with sending metrics to your management plane {{< /call-out >}} -#### Add Prometheus Exporter +- **Add Prometheus Exporter** ```yaml exporters: prometheus: @@ -83,7 +83,7 @@ service: - prometheus ``` -#### Add Debug Exporter +- **Add Debug Exporter** ```yaml exporters: debug: @@ -104,7 +104,7 @@ service: ``` -#### Debug Merging Configs +### Debug Merging Configs To view the merged OpenTelemetry configuration set the Agent log level to debug in `/etc/nginx-agent/nginx-agent.conf` and restart NGINX Agent @@ -116,14 +116,3 @@ log: ``` 3. Restart NGINX Agent 4. View merged OpenTelemetry configuration `cat /var/lib/nginx-agent/opentelemetry-collector-agent-debug.yaml` - - - - - - - - - - - From 5c7c341217fde8676b10f81c142089b8491c9f8b Mon Sep 17 00:00:00 2001 From: Aphral Griffin Date: Mon, 6 Oct 2025 14:25:29 +0100 Subject: [PATCH 3/4] feat: add third party otel collector example --- .../agent/metrics/configure-otel-metrics.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/content/nginx-one/agent/metrics/configure-otel-metrics.md b/content/nginx-one/agent/metrics/configure-otel-metrics.md index c9388a5f0..cc0396725 100644 --- a/content/nginx-one/agent/metrics/configure-otel-metrics.md +++ b/content/nginx-one/agent/metrics/configure-otel-metrics.md @@ -64,6 +64,10 @@ collector: {{< call-out "important" >}} NGINX Agent uses `/default` for naming its default processors, exporters and pipelines using the same naming in your own config might cause issues with sending metrics to your management plane {{< /call-out >}} - **Add Prometheus Exporter** + +{{< tabs name="prometheus-exporter" >}} +{{% tab name="NGINX Plus" %}} + ```yaml exporters: prometheus: @@ -77,13 +81,132 @@ service: receivers: - containermetrics - hostmetrics + - nginxplus processors: - resource/default exporters: - prometheus ``` +{{% /tab %}} +{{% tab name="NGINX OSS" %}} + +```yaml +exporters: + prometheus: + endpoint: "127.0.0.1:5643" + resource_to_telemetry_conversion: + enabled: true + +service: + pipelines: + metrics/prometheus-example-pipeline: + receivers: + - containermetrics + - hostmetrics + - nginx + processors: + - resource/default + exporters: + - prometheus +``` + +{{% /tab %}} +{{< /tabs >}} + + +- **Third-party OTel Collector** + +{{< tabs name="third-party-collector" >}} +{{% tab name="NGINX Plus" %}} + +```yaml +exporters: + otlp/local-collector: + endpoint: "my-local-collector.com:443" + timeout: 10s + retry_on_failure: + enabled: true + initial_interval: 10s + max_interval: 60s + max_elapsed_time: 10m + tls: + insecure: true + +service: + pipelines: + metrics/otlp-example-pipeline: + receivers: + - containermetrics + - hostmetrics + - nginxplus + processors: + - resource/default + exporters: + - otpl/local-collector +``` + +{{% /tab %}} +{{% tab name="NGINX OSS" %}} + +```yaml +exporters: + otlp/local-collector: + endpoint: "my-local-collector.com:443" + timeout: 10s + retry_on_failure: + enabled: true + initial_interval: 10s + max_interval: 60s + max_elapsed_time: 10m + tls: + insecure: true + +service: + pipelines: + metrics/otlp-example-pipeline: + receivers: + - containermetrics + - hostmetrics + - nginx + processors: + - resource/default + exporters: + - otpl/local-collector +``` + +{{% /tab %}} +{{< /tabs >}} + + - **Add Debug Exporter** + +{{< tabs name="debug-exporter" >}} +{{% tab name="NGINX Plus" %}} + +```yaml +exporters: + debug: + verbosity: detailed + sampling_initial: 5 + sampling_thereafter: 200 + +service: + pipelines: + metrics/debug-example-pipeline: + receivers: + - containermetrics + - hostmetrics + - nginxplus + processors: + - resource/default + exporters: + - debug +``` + +{{% /tab %}} +{{% tab name="NGINX OSS" %}} + ```yaml exporters: debug: @@ -97,12 +220,17 @@ service: receivers: - containermetrics - hostmetrics + - nginx processors: - resource/default exporters: - debug ``` +{{% /tab %}} +{{< /tabs >}} + + ### Debug Merging Configs From ddc8ae19b5b75134df61ae5e69074464f67c05d0 Mon Sep 17 00:00:00 2001 From: Aphral Griffin Date: Mon, 6 Oct 2025 14:31:10 +0100 Subject: [PATCH 4/4] feat: clean up examples --- .../agent/metrics/configure-otel-metrics.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/content/nginx-one/agent/metrics/configure-otel-metrics.md b/content/nginx-one/agent/metrics/configure-otel-metrics.md index cc0396725..10d7adfbe 100644 --- a/content/nginx-one/agent/metrics/configure-otel-metrics.md +++ b/content/nginx-one/agent/metrics/configure-otel-metrics.md @@ -79,8 +79,6 @@ service: pipelines: metrics/prometheus-example-pipeline: receivers: - - containermetrics - - hostmetrics - nginxplus processors: - resource/default @@ -102,8 +100,6 @@ service: pipelines: metrics/prometheus-example-pipeline: receivers: - - containermetrics - - hostmetrics - nginx processors: - resource/default @@ -137,8 +133,6 @@ service: pipelines: metrics/otlp-example-pipeline: receivers: - - containermetrics - - hostmetrics - nginxplus processors: - resource/default @@ -166,8 +160,6 @@ service: pipelines: metrics/otlp-example-pipeline: receivers: - - containermetrics - - hostmetrics - nginx processors: - resource/default @@ -195,8 +187,6 @@ service: pipelines: metrics/debug-example-pipeline: receivers: - - containermetrics - - hostmetrics - nginxplus processors: - resource/default @@ -218,8 +208,6 @@ service: pipelines: metrics/debug-example-pipeline: receivers: - - containermetrics - - hostmetrics - nginx processors: - resource/default @@ -232,7 +220,7 @@ service: -### Debug Merging Configs +### Troubleshooting To view the merged OpenTelemetry configuration set the Agent log level to debug in `/etc/nginx-agent/nginx-agent.conf` and restart NGINX Agent