feat: Add custom OTel configuration section

content/nginx-one/agent/metrics/configure-otel-metrics.md

@@ -39,3 +39,196 @@ 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/docs/collector/configuration/). 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
+3. Save and restart the NGINX agent service `sudo systemctl restart nginx-agent`
+
+```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**
+
+{{< tabs name="prometheus-exporter" >}}
+{{% tab name="NGINX Plus" %}}
+
+```yaml
+exporters:
+  prometheus:
+    endpoint: "127.0.0.1:5643"
+    resource_to_telemetry_conversion:
+      enabled: true
+
+service:
+  pipelines:
+    metrics/prometheus-example-pipeline:
+      receivers:
+        - 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:
+        - 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:
+        - 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:
+        - 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:
+        - nginxplus
+      processors:
+        - resource/default
+      exporters:
+        - debug
+```
+
+{{% /tab %}}
+{{% tab name="NGINX OSS" %}}
+
+```yaml
+exporters:
+  debug:
+    verbosity: detailed
+    sampling_initial: 5
+    sampling_thereafter: 200
+
+service:
+  pipelines:
+    metrics/debug-example-pipeline:
+      receivers:
+        - nginx
+      processors:
+        - resource/default
+      exporters:
+        - debug
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+
+
+### 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 
+
+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`