diff --git a/content/agent/how-to/export-metrics.md b/content/agent/how-to/export-metrics.md deleted file mode 100644 index 9edae11dc..000000000 --- a/content/agent/how-to/export-metrics.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Export metrics data" -weight: 300 -docs: DOCS-000 ---- - -This document describes how to export the metrics data from F5 NGINX Agent. - -[//]: # "These are Markdown comments to guide you through document structure." -[//]: # "Remove them as you go, as well as unnecessary sections for this use case." - -## Overview - -[//]: # "Write a description which outlines precisely what this page of instructions will accomplish." -[//]: # "This description, like all instructions, should be direct and imperative." -[//]: # "Avoid ambiguous promises such as 'enables functionality': state precisely what it does." - ---- - -## Before you begin - -[//]: # "List all of the prerequisites for completing this task." -[//]: # "This might be the first page for a reader, so include a link to installation." - -To begin this task, you will require the following: - -- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). -- -- - ---- - -## Export metrics data - - - ---- - -## See also - -[//]: # "Examples of additional topics users might want to read include:" -[//]: # "Relevant reference information, configuration options and more complex use cases." - -- [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) -- diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md new file mode 100644 index 000000000..09c7397c6 --- /dev/null +++ b/content/agent/how-to/run-agent-container.md @@ -0,0 +1,105 @@ +--- +title: "Run the NGINX Agent in a container" +weight: 300 +toc: true +type: how-to +product: Agent +--- + +## Overview + +This guide serves as a step-by-step guide to run NGINX Agent in a container. It covers the basic setup needed to get the NGINX Agent up and running efficiently and securely. + +## Before you begin + +Before you begin this guide ensure: + +{{< note >}} +This guide uses Docker but NGINX Agent also works with other container applications. +{{< /note >}} + +- **Docker:** Ensure Docker is installed and configured on your system. [Download Docker from the official site](https://www.docker.com/products/docker-desktop/). +- **Credentials:** Acquire any necessary authentication tokens or credentials required for the NGINX Agent. + +## Prepare the environment + +To run NGINX Agent in a container you will need to download the NGINX Agent +container image and create a configuration file. + +### Pull the NGINX Agent container image + +The NGINX Agent container image must be downloaded from a trusted source such as Docker Hub or a private container registry. + +Run the following command to pull the official image: + +```bash + +docker pull :latest +``` + +Ensure you are using the correct image version. Replace `latest` with the desired version tag if necessary. + + +### Create a configuration file + +Create a configuration file named `nginx-agent.conf` in your current directory +and populate the file with the following structure: + +```yaml +command: + server: + host: "" # Command server host + port: 443 # Command server port + auth: + token: "" # Authentication token for the command server + tls: + skip_verify: false +``` + +Replace the placeholder values: + +- ``: The URL of your NGINX One Console instance. +- ``: Your Data Plane access token. + + +## Run the container + +Run the NGINX Agent container with the configuration file mounted. + +Use the following command: + +```bash +docker run -d \ + --name nginx-agent \ + -v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf \ + nginx/agent:latest +``` + +Key options explained: + +- `-d`: Runs the container in detached mode. +- `--name nginx-agent`: Assigns a name to the container for easy identification. +- `-v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf`: Mounts the configuration file into the container. + + +### Verify the container is running + +Check the running status of the container: + +```bash +docker ps +``` + +You should see an entry for `nginx-agent`. The `STATUS` field indicates that the container is running. + +### Monitor logs + +To ensure the container is functioning properly and communicating with NGINX One Console, monitor the container logs. + +Run the following command: + +```bash +docker logs -f nginx-agent +``` + +Look for log entries indicating successful connection to the NGINX One Console and periodic metric transmission. diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index cac034103..0e302b7a4 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -1,229 +1,39 @@ --- -title: Metrics Export +title: Export metrics with NGINX Agent weight: 200 --- ## Overview -The F5 NGINX Agent v3 now includes an embedded [OpenTelemetry](https://opentelemetry.io/) Collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: +F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io/) collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: -* Metrics from NGINX Plus and NGINX OSS +* Metrics from NGINX Plus and NGINX Open Source * Host metrics (CPU, memory, disk, and network activity) from VMs or Containers - -This guide walks you through enabling and configuring the embedded OpenTelemetry Collector for metric export. +{{< note >}} +The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. +{{< /note >}} -# Key Benefits +### Key benefits * Seamless Integration: No need to deploy an external OpenTelemetry Collector. All components are embedded within the Agent for streamlined observability. * Standardized Protocol: Support for OpenTelemetry standards ensures interoperability with a wide range of observability backends, including Jaeger, Prometheus, Splunk, and more. -## Before you begin +### Verify that metrics are exported -Before you begin configuring the F5 NGINX Agent OTel Collector: +You can validate that metrics are successfully exported by using the methods below: -- [NGINX One Console Getting Started]({{< relref "/nginx-one/getting-started" >}}) -- F5 NGINX OSS/Plus installed on a Virtual Machine -- F5 NGINX Agent v3 is installed +- **NGINX One dashboard** + - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. -## Configure the OTel Collector - Virtual Machine +- **Agent logs** -1. Locate the configuration file for the F5 NGINX Agent: + Check the OpenTelemetry Collector logs for confirmation of successful metric processing: - ```bash - /etc/nginx-agent/nginx-agent.conf - ``` -2. Open the configuration file for editing: - - ```bash - sudo vim /etc/nginx-agent/nginx-agent.conf - ``` - -3. Edit the `/etc/nginx-agent/nginx-agent.conf` and add the following. - - Make sure to replace your-data-plane-key-here with the real data plane key that you are using for your application or service. - - ```vim - collector: - receivers: - host_metrics: - collection_interval: 1m0s - initial_delay: 1s - scrapers: - cpu: {} - memory: {} - disk: {} - network: {} - filesystem: {} - processors: - batch: {} - exporters: - otlp_exporters: - - server: - host: - port: 443 - authenticator: headers_setter - tls: - skip_verify: false - extensions: - headers_setter: - headers: - - action: insert - key: "authorization" - value: "your-data-plane-key-here" - ``` -4. Restart the NGINX Agent service - - ```bash - sudo systemctl restart nginx-agent - ``` - -## Running a Container to Connect to the NGINX One Console and Send Metrics - -This guide provides step-by-step instructions on how to run a container to connect to the NGINX One Console and send metrics. Follow these steps to ensure proper setup and execution. - ---- - -## Prerequisites -Before running the container, ensure the following: -1. **Docker Installed**: Docker must be installed on your system. You can download it from [Docker's official website](https://www.docker.com/). -2. **NGINX One Console**: The NGINX One Console is set up and accessible. -3. **Data Plane Token**: Obtain an access key or Data Plane token from the NGINX One Console for authentication. -4. **Network Connectivity**: Verify that the container can reach the NGINX One Console endpoint. - ---- - -## Steps to Run the Container - -### Step 1: Pull the NGINX Metrics Agent Container Image -The NGINX Metrics Agent container image must be downloaded from a trusted source such as Docker Hub or a private container registry. - -Run the following command to pull the official image: -```bash - -docker pull :latest -``` - -Ensure you are using the correct image version. Replace `latest` with the desired version tag if necessary. - ---- - -### Step 2: Create a Configuration File - -1. Create a configuration file named `nginx-agent.conf` in your current directory. -2. Populate the file with the following structure: - -```vim -command: - server: - host: "" # Command server host - port: 443 # Command server port - type: 0 # Server type (e.g., 0 for gRPC) - auth: - token: "" # Authentication token for the command server - tls: - skip_verify: false - - collector: - receivers: - host_metrics: - collection_interval: 1m0s - initial_delay: 1s - scrapers: - cpu: {} - memory: {} - disk: {} - network: {} - filesystem: {} - processors: - batch: {} - exporters: - otlp_exporters: - - server: - host: - port: 443 - authenticator: headers_setter - tls: - skip_verify: false - extensions: - headers_setter: - headers: - - action: insert - key: "authorization" - value: "your-data-plane-key-here" -``` - -Replace the placeholder values: -- ``: The URL of your NGINX One Console instance. -- ``: Your Data Plane access token. - ---- - -### Step 3: Run the Container -Run the NGINX Agent container with the configuration file mounted. - -Use the following command: -```bash -docker run -d \ - --name nginx-agent \ - -v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf \ - nginx/agent:latest -``` - -Key options explained: -- `-d`: Runs the container in detached mode. -- `--name nginx-agent`: Assigns a name to the container for easy identification. -- `-v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf`: Mounts the configuration file into the container. - ---- - -### Step 4: Verify the Container is Running -Check the running status of the container: -```bash -docker ps -``` - -You should see an entry for `nginx-agent`. The `STATUS` field should indicate that the container is running. - ---- - -### Step 5: Monitor Logs -To ensure the container is functioning properly and communicating with NGINX One Console, monitor the container logs. - -Run the following command: -```bash -docker logs -f nginx-agent -``` - -Look for log entries indicating successful connection to the NGINX One Console and periodic metric transmission. - ---- - -### Troubleshooting - -1. **Container Fails to Start**: - - Check the configuration file for errors. - - Ensure the NGINX One Console endpoint is reachable from the host. - -2. **No Metrics Sent**: - - Verify the access token is valid. - - Confirm network connectivity to the NGINX One Console. - -3. **Logs Show Errors**: - - Examine the logs for specific error messages. - - Address any permission or network-related issues. - ---- - -## Clean Up -To stop and remove the container when it is no longer needed, run: -```bash -docker stop nginx-metrics-agent -docker rm nginx-metrics-agent -``` - ---- - -## Conclusion -Following these instructions, you can successfully run a container to connect to the NGINX One Console and send metrics. For further details or issues, refer to the documentation provided by NGINX or your administrator. \ No newline at end of file + 1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` + 2. Look for the following logs: + + ```text + Everything is ready. Begin running and processing data. + ``` \ No newline at end of file diff --git a/content/agent/otel/metrics.md b/content/agent/otel/metrics.md deleted file mode 100644 index 179f413b9..000000000 --- a/content/agent/otel/metrics.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: OpenTelemetry metrics -weight: 300 -docs: DOCS-000 ---- \ No newline at end of file