diff --git a/content/nginx-one/agent/metrics/configure-otel-metrics.md b/content/nginx-one/agent/metrics/configure-otel-metrics.md index 598017cf8..10d7adfbe 100644 --- a/content/nginx-one/agent/metrics/configure-otel-metrics.md +++ b/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/). 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** + +{{< 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`