Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions content/agent/configuration/configuration-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,11 @@ server:
host: <FQDN>
grpcPort: 443
backoff: # note: default values are prepopulated
initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10
multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5
max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
initial_interval: 100ms # Add the appropriate duration value here, for example, "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
randomization_factor: 0.10 # Add the appropriate float value here, for example, 0.10
multiplier: 1.5 # Add the appropriate float value here, for example, 1.5
max_interval: 1m # Add the appropriate duration value here, for example, "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
max_elapsed_time: 0 # Add the appropriate duration value here, for example, "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
# tls options
tls:
# enable tls in the nginx-agent setup for grpcs
Expand Down Expand Up @@ -89,11 +89,11 @@ metrics:
collection_interval: 15s
mode: aggregated
backoff: # note: default values are prepopulated
initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10
multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5
max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
initial_interval: 100ms # Add the appropriate duration value here, for example, "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
randomization_factor: 0.10 # Add the appropriate float value here, for example, 0.10
multiplier: 1.5 # Add the appropriate float value here, for example, 1.5
max_interval: 1m # Add the appropriate duration value here, for example, "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
max_elapsed_time: 0 # Add the appropriate duration value here, for example, "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour

# OSS NGINX default config path
# path to aux file dirs can also be added
Expand Down Expand Up @@ -193,7 +193,7 @@ If you are upgrading from an older version, update your configuration accordingl
| `--features` | `NGINX_AGENT_FEATURES` | Specifies a comma-separated list of features enabled for the agent. Default: *[registration, nginx-config-async, nginx-ssl-config, nginx-counting, metrics, dataplane-status, process-watcher, file-watcher, activity-events, agent-api]* |
| `--ignore-directives` | | Specifies a comma-separated list of directives to ignore for sensitive info.|
| `--instance-group` | `NGINX_AGENT_INSTANCE_GROUP` | Sets the instance's group value. |
| `--log-level` | `NGINX_AGENT_LOG_LEVEL` | Sets the logging level (e.g., panic, fatal, error, info, debug, trace). Default: *info* |
| `--log-level` | `NGINX_AGENT_LOG_LEVEL` | Sets the logging level (for example, panic, fatal, error, info, debug, trace). Default: *info* |
| `--log-path` | `NGINX_AGENT_LOG_PATH` | Specifies the path to output log messages. |
| `--metrics-bulk-size` | `NGINX_AGENT_METRICS_BULK_SIZE` | Specifies the number of metrics reports collected before sending data. Default: *20* |
| `--metrics-collection-interval` | `NGINX_AGENT_METRICS_COLLECTION_INTERVAL` | Sets the interval for metrics collection. Default: *15s* |
Expand Down
2 changes: 1 addition & 1 deletion content/amplify/faq/nginx-amplify-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ If you don't see the new system or NGINX in the web interface, or (some) metrics

3. NGINX Amplify Agent is running under the same user as your NGINX worker processes.

4. The NGINX instance is started with an absolute path. Currently, NGINX Amplify Agent **can't** detect NGINX instances launched with a relative path (e.g., "./nginx").
4. The NGINX instance is started with an absolute path. Currently, NGINX Amplify Agent **can't** detect NGINX instances launched with a relative path (for example, "./nginx").

5. The [user ID that is used by NGINX Amplify Agent and NGINX ]({{< ref "/amplify/nginx-amplify-agent/install/configuring-amplify-agent#overriding-the-effective-user-id" >}}), can run *ps(1)* to see all system processes. If *ps(1)* is restricted for non-privileged users, NGINX Amplify Agent won't be able to find and properly detect the NGINX master process.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ docs: DOCS-961

F5 NGINX Amplify Agent can automatically find all relevant NGINX configuration files, parse them, extract their logical structure, and send the associated JSON data to the Amplify backend for further analysis and reporting. For more information on configuration analysis, please see the [Analyzer]({{< ref "/amplify/user-interface/analyzer.md" >}})) documentation.

After NGINX Amplify Agent finds a particular NGINX configuration, it then automatically starts to keep track of its changes. When a change is detected with NGINX — e.g., a master process restarts, or the NGINX config is edited, an update is sent to the Amplify backend.
After NGINX Amplify Agent finds a particular NGINX configuration, it then automatically starts to keep track of its changes. When a change is detected with NGINX — for example, a master process restarts, or the NGINX config is edited, an update is sent to the Amplify backend.

{{< note >}} NGINX Amplify Agent never sends the raw unprocessed config files to the backend system. In addition, the following directives in the NGINX configuration are never analyzed — and their parameters aren't exported to the SaaS backend:
[ssl_certificate_key](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_certificate_key), [ssl_client_certificate](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_client_certificate), [ssl_password_file](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_password_file), [ssl_stapling_file](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_stapling_file), [ssl_trusted_certificate](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate), [auth_basic_user_file](http://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic_user_file), [secure_link_secret](http://nginx.org/en/docs/http/ngx_http_secure_link_module.html#secure_link_secret).{{< /note >}}
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ NGINX Amplify Agent will also collect more NGINX metrics from the [access.log](h

You don't have to specifically point NGINX Amplify Agent to either the NGINX configuration or the NGINX log files — it should detect their location automatically.

NGINX Amplify Agent will also try to detect the [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for a particular log to parse it properly and try to extract even more useful metrics, e.g., [$upstream_response_time](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time).
NGINX Amplify Agent will also try to detect the [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for a particular log to parse it properly and try to extract even more useful metrics, for example, [$upstream_response_time](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time).

{{< note >}}Several metrics outlined in [Metrics and Metadata]({{< ref "metrics-metadata" >}}) will only be available if the corresponding variables are included in a custom [access.log](http://nginx.org/en/docs/http/ngx_http_log_module.html) format used for logging requests. You can find a complete list of NGINX log variables [here](http://nginx.org/en/docs/varindex.html).{{< /note >}}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ docs: DOCS-964
F5 NGINX Amplify Agent collects the following types of data:

* **NGINX metrics.** NGINX Amplify Agent collects a lot of NGINX related metrics from [stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html), the NGINX Plus status API, the NGINX log files, and from the NGINX process state.
* **System metrics.** These are various key metrics describing the system, e.g., CPU usage, memory usage, network traffic, etc.
* **System metrics.** These are various key metrics describing the system, for example, CPU usage, memory usage, network traffic, etc.
* **PHP-FPM metrics.** NGINX Amplify Agent can obtain metrics from the PHP-FPM pool status if it detects a running PHP-FPM main process.
* **MySQL metrics.** NGINX Amplify Agent can obtain metrics from the MySQL global status set of variables.
* **NGINX metadata.** This is what describes your NGINX instances, and it includes package data, build information, the path to the binary, build configuration options, etc. NGINX metadata also includes the NGINX configuration elements.
Expand Down
2 changes: 1 addition & 1 deletion content/amplify/user-interface/account-settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Users can be assigned one of the three roles — Admin, User, or Read-Only. Admi

In the **Notifications** section, you will find information about the emails currently registered with your account and whether they are verified or not. The alert notifications are only sent to verified emails.

In addition to the email alert notifications, you can optionally configure the integration with your Slack team and workspace. Under the registered emails section, select the "Add to Slack" button to allow Amplify to send you certain notifications on Slack. You will have to log in and provide the necessary details about your team and what channels you'd like to add to Amplify notifications. Both direct messages and channels can be used for notifications. If configured successfully, Amplify can send alert information to Slack. A few more additional notifications are available — e.g., F5 NGINX Amplify Agent not finding a running NGINX instance, but also proactive messages about the issues with the SSL certs.
In addition to the email alert notifications, you can optionally configure the integration with your Slack team and workspace. Under the registered emails section, select the "Add to Slack" button to allow Amplify to send you certain notifications on Slack. You will have to log in and provide the necessary details about your team and what channels you'd like to add to Amplify notifications. Both direct messages and channels can be used for notifications. If configured successfully, Amplify can send alert information to Slack. A few more additional notifications are available — for example, F5 NGINX Amplify Agent not finding a running NGINX instance, but also proactive messages about the issues with the SSL certs.


{{< img src="amplify/amplify-notifications.png" alt="Notifications" >}}
Expand Down
4 changes: 2 additions & 2 deletions content/amplify/user-interface/analyzer.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,14 +37,14 @@ The following information is provided when a report is generated from an NGINX c
* Typical configuration issues highlighted
* Common advice about proxy configurations
* Suggestions about simplifying rewrites for certain use cases
* Key security measures (e.g., *stub_status* is unprotected)
* Key security measures (for example, *stub_status* is unprotected)
* Typical errors in configuring locations, especially with *regex*

To parse SSL certificate metadata, NGINX Amplify Agent uses standard OpenSSL(1) functions. SSL certificates are parsed and analyzed only when the corresponding [settings]({{< ref "/amplify/user-interface/account-settings" >}}) are turned on. SSL certificate analysis is *off* by default.

Static analysis will only include information about specific issues with the NGINX configuration if those are found in your NGINX setup.

In the future, the **Analyzer** page will also include *dynamic analysis*, effectively linking the observed NGINX behavior to its configuration — e.g., when it makes sense to increase or decrease certain parameters like [proxy_buffers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers), etc.
In the future, the **Analyzer** page will also include *dynamic analysis*, effectively linking the observed NGINX behavior to its configuration — for example, when it makes sense to increase or decrease certain parameters like [proxy_buffers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers), etc.

{{< note >}} Config analysis is *on* by default. If you don't want your NGINX configuration to be checked, unset the corresponding setting in either Global, or Local (per-system) settings. See [**Settings**]({{< ref "/amplify/user-interface/account-settings" >}}). {{< /note >}}

Expand Down
4 changes: 2 additions & 2 deletions content/amplify/user-interface/dashboards.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,14 @@ To define a graph, perform these steps:
2. Pick one or more metrics. You can combine multiple metrics on the same graph using the "Add another metric" button.
3. After the metric is selected, you can see the systems for which the metric has been observed. Select one or multiple systems here. You can also use tags to specify the systems.
4. When aggregating across multiple systems, select either "Sum" or "Avg" as the aggregation function.
5. Last but not least, the “filter” functionality is also available for NGINX metrics collected from the log files. If you select "Add metric filter", you can add multiple criteria to define specific "metric dimensions". In the example above, we are matching the NGINX upstream response time against the **/api/feed/reports** URI. You can also build other filters, e.g., displaying metric **nginx.http.status.2xx** for the responses with the status code 201.
5. Last but not least, the “filter” functionality is also available for NGINX metrics collected from the log files. If you select "Add metric filter", you can add multiple criteria to define specific "metric dimensions". In the example above, we are matching the NGINX upstream response time against the **/api/feed/reports** URI. You can also build other filters, for example, displaying metric **nginx.http.status.2xx** for the responses with the status code 201.
6. Select "Save" to add the graph to the dashboard. You can also edit the graph, move it around, resize it, stack the graphs on top of each other, etc.

{{< note >}} When using filters, all the "metric dimensions" aren't stored in the F5 NGINX Amplify backend by default. A particular filter starts to slice the metric according to the specification only after the graph is created. Hence, it can be a while before the "filtered" metric is displayed on the graph — the end result depends on how quickly the log files are being populated with the new entries, but typically you should see the first data points in under 5 minutes. {{< /note >}}

Because NGINX Amplify is **not** a SaaS log analyzer, the additional slicing for "metric dimensions" is implemented inside NGINX Amplify Agent. NGINX Amplify Agent can parse the NGINX access logs on-the-fly and extract all the necessary metrics **without** sending the raw log entries elsewhere. Moreover, NGINX Amplify Agent understands custom log formats automatically, and will start looking for various newly defined "metric dimensions" following a particular [log_format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) specification.

Essentially, NGINX Amplify Agent performs a combination of real-time log analytics and standard metrics collection (e.g., metrics from the *stub_status* module). NGINX Amplify Agent does only the **real-time log processing**, and always on the same host where it is running.
Essentially, NGINX Amplify Agent performs a combination of real-time log analytics and standard metrics collection (for example, metrics from the *stub_status* module). NGINX Amplify Agent does only the **real-time log processing**, and always on the same host where it is running.

Metric filters can be really powerful. By using the filters and creating additional "metric dimensions", it is possible to build highly granular and informative graphs. To enable NGINX Amplify Agent to slice the metrics you must add the corresponding log variables to the active NGINX log format. Please see the [Additional NGINX metrics]({{< ref "/amplify/metrics-metadata/nginx-metrics#additional-nginx-metrics" >}}) section below.

Expand Down
2 changes: 1 addition & 1 deletion content/amplify/user-interface/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The cumulative [metrics]({{< ref "/amplify/metrics-metadata" >}}) displayed on t

{{< note >}} By default the metrics above are calculated for all monitored hosts. You can configure specific tags in the **Overview** settings popup to display the metrics for a set of hosts (e.g. only the "production environment"). {{< /note >}}

You may see zero numbers if some metrics are not being gathered, e.g., if the request time (P95) is 0.000s, please check that you have correctly configured NGINX log for [additional metric]() collection.
You may see zero numbers if some metrics are not being gathered, for example, if the request time (P95) is 0.000s, please check that you have correctly configured NGINX log for [additional metric]() collection.

{{< img src="amplify/amplify-overview.png" alt="Overview section of the User Interface" >}}

Expand Down
2 changes: 1 addition & 1 deletion content/controller/releases/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -1274,7 +1274,7 @@ Refer to the [NGINX Controller Tech Specs]({{< ref "/controller/admin-guides/ins

- **After enabling WAF, security violations aren't reported right away (10558)**

When an App Component is initially enabled with WAF, there may be a few seconds where Security Events (that is, WAF violation events) are not mapped to the correct App Component and App. The following warning message is logged in `/var/log/nginx-controller/security-events-mgr.log`: *"Generating event without app-centric dimensions (i.e., app, component, environment, gateway, correlationId)."*
When an App Component is initially enabled with WAF, there may be a few seconds where Security Events (that is, WAF violation events) are not mapped to the correct App Component and App. The following warning message is logged in `/var/log/nginx-controller/security-events-mgr.log`: *"Generating event without app-centric dimensions (that is, app, component, environment, gateway, correlationId)."*

- **Security events not mapped to App or App Component if combined length of resource IDs exceeds 445 characters (11112)**

Expand Down
Loading
Loading