> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/nginx.md). # Nginx The Nginx source collects metrics from the NGINX `stub_status` HTTP endpoint, parses access and error log files, and receives OTLP traces exported by the NGINX OpenTelemetry module. Choose any combination of Logs, Metrics, and Traces with the telemetry type selector. ### Supported Telemetry | Platform | Metrics | Logs | Traces | | -------- | ------- | ---- | ------ | | Linux | ✓ | ✓ | ✓ | | Windows | ✓ | ✓ | ✓ | | macOS | ✓ | ✓ | ✓ | ### Prerequisites * **Metrics:** NGINX must be built with `ngx_http_stub_status_module` (the `--with-http_stub_status_module` build option, not enabled by default) and expose a reachable status endpoint via a `stub_status` location. The default endpoint is `http://localhost:80/status`. The collector host must be able to reach that endpoint. See [Module ngx\_http\_stub\_status\_module](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html). * **Logs:** NGINX must be writing access and error logs, and the collector must run where it can read those files (or have them shipped to it). Default paths are `/var/log/nginx/access.log*` and `/var/log/nginx/error.log*`. The configured Log Format must match the on-disk format. See [Module ngx\_http\_log\_module](https://nginx.org/en/docs/http/ngx_http_log_module.html). * **Traces:** The NGINX OpenTelemetry module must be configured to export OTLP/gRPC trace data to the host and port this source listens on (default `0.0.0.0:4317`). ### Configuration
Bindplane docs - Nginx - image 1
**General** | Parameter | Type | Required | Default | Description | | --------------------- | ------------------ | -------- | --------------------- | ---------------------------------------------------------- | | Choose Telemetry Type | Telemetry Selector | No | `["Logs", "Metrics"]` | Which signals this source collects: Logs, Metrics, Traces. | **Logs** Relevant when Choose Telemetry Type includes Logs. | Parameter | Type | Required | Default | Description | | ---------------- | --------------- | -------- | ---------------------------- | ------------------------------------- | | Data Flow | Enum: high, low | No | high | Enable high flow or reduced low flow. | | Access Log Paths | Strings | No | `/var/log/nginx/access.log*` | Path to NGINX access log file(s). | | Error Log Paths | Strings | No | `/var/log/nginx/error.log*` | Path to NGINX error log file(s). | **Metrics** Relevant when Choose Telemetry Type includes Metrics. | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ---------------------------- | -------------------------------------------------------- | | Endpoint | String | Yes | `http://localhost:80/status` | The endpoint of the NGINX server `stub_status` location. | **Traces** Relevant when Choose Telemetry Type includes Traces. | Parameter | Type | Required | Default | Description | | -------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | OTLP GRPC Port | Integer | No | 4317 | TCP port to receive OTLP trace data using the gRPC protocol. Configure the NGINX otel module to export to this port. Valid range 1-65535. | **Advanced** | Parameter | Type | Required | Default | Description | | --------------------------------------- | ----------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Log Format | Enum: default, observiq | No | default | Log parsing format. Relevant when collecting Logs. | | Start At | Enum: beginning, end | No | end | Start reading logs from `beginning` or `end`. Relevant when collecting Logs. | | Parse | Boolean | No | true | Parses the log fields into structured data. Relevant when collecting Logs. | | Filtering | Metrics | No | *(all enabled)* | Select which NGINX metrics to collect. All metrics are enabled by default; toggle individual metrics off as needed. See [NGINX Metrics](#nginx-metrics) below. Relevant when collecting Metrics. | | Enable TLS | Boolean | No | false | Whether or not to use TLS for the metrics endpoint. Relevant when collecting Metrics. | | Skip TLS Certificate Verification | Boolean | No | false | Enable to skip TLS certificate verification. Relevant when Enable TLS is true. | | TLS Certificate Authority File | String | No | *(empty)* | Certificate authority used to validate TLS certificates. Relevant when Enable TLS is true. | | TLS Client Certificate File | String | No | *(empty)* | A TLS certificate used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS is true. | | TLS Client Private Key File | String | No | *(empty)* | A TLS private key used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS is true. | | Collection Interval | Integer | No | 60 | How often (seconds) to scrape for metrics. Relevant when collecting Metrics. | | OTLP GRPC Listen Address | String | No | `0.0.0.0` | The IP address to listen on for OTLP gRPC trace data from the NGINX otel module. Relevant when collecting Traces. | | Enable TLS (Traces) | Boolean | No | false | Whether or not to use TLS for the OTLP gRPC listener. Relevant when collecting Traces. | | Server Certificate File | String | Yes | *(empty)* | A path to the server certificate to be used for TLS. Relevant when the Traces Enable TLS is true. | | Server Private Key | String | Yes | *(empty)* | A path to the server private key to be used for TLS. Relevant when the Traces Enable TLS is true. | | Mutual TLS | Boolean | No | false | Whether or not to require client TLS authentication (mTLS). Relevant when the Traces Enable TLS is true. | | TLS Certificate Authority File (Traces) | String | Yes | *(empty)* | A path to the certificate authority to use for authenticating client certificates. Relevant when the Traces Enable TLS and Mutual TLS are both true. | **NGINX Metrics** The Filtering parameter toggles these metrics individually. Defaults reflect the upstream Nginx Receiver (`v0.153.0`). | Metric | Unit | Default | Description | | ---------------------------- | ------------- | ------- | ------------------------------------------------------------- | | `nginx.connections_accepted` | `connections` | Enabled | The total number of accepted client connections. | | `nginx.connections_current` | `connections` | Enabled | The current number of nginx connections by state. | | `nginx.connections_handled` | `connections` | Enabled | The total number of handled connections.1 | | `nginx.requests` | `requests` | Enabled | Total number of requests made to the server since it started. | 1. *Generally the same as `nginx.connections_accepted` unless a resource limit (for example, the `worker_connections` limit) has been reached.* ### Examples #### Collect metrics and logs from a local NGINX server Scrape the `stub_status` endpoint every 30 seconds and tail the default access and error logs. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: nginx spec: type: nginx parameters: - name: telemetry_types value: ["Logs", "Metrics"] - name: endpoint value: http://localhost:80/status - name: collection_interval value: 30 - name: access_log_paths value: - /var/log/nginx/access.log* - name: error_log_paths value: - /var/log/nginx/error.log* ``` ### Configuration Tips * For metrics, point Endpoint at the `stub_status` location you configured in NGINX (for example `http://localhost:80/status`), not the site root. * Use the Filtering parameter to disable individual NGINX metrics you do not need rather than collecting all of them. * For traces, set OTLP GRPC Port and Listen Address to match what the NGINX otel module is configured to export to, and open that port between NGINX and the collector. ### Troubleshooting #### No metrics appear Symptoms: the source is running but reports no NGINX metrics. Solutions: 1. Confirm NGINX was built with `ngx_http_stub_status_module` and that a `stub_status` location is enabled and reachable at the configured Endpoint. 2. Verify the collector host can reach the Endpoint (try `curl http://localhost:80/status` from the collector host). 3. If TLS is enabled, confirm the certificate paths are correct, or enable Skip TLS Certificate Verification for testing. #### Connection refused on the metrics endpoint Symptoms: the collector logs connection-refused errors scraping the status endpoint. Solutions: 1. Confirm NGINX is listening on the host and port in the Endpoint and that the `stub_status` location is not restricted by `allow`/`deny` rules blocking the collector host. 2. Check for a firewall blocking the path between the collector and NGINX. #### No logs appear Symptoms: no log records reach the pipeline. Solutions: 1. Verify the Access Log Paths and Error Log Paths match where NGINX actually writes logs. 2. Confirm the collector user has read permission on those files. 3. Ensure the Log Format matches the on-disk format; if `parse` fails, set Log Format correctly or disable Parse. ### Standalone Source ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: nginx spec: type: nginx parameters: - name: telemetry_types value: ["Logs", "Metrics"] - name: endpoint value: http://localhost:80/status - name: collection_interval value: 60 - name: data_flow value: high - name: log_format value: default - name: access_log_paths value: - /var/log/nginx/access.log* - name: error_log_paths value: - /var/log/nginx/error.log* - name: start_at value: end - name: parse value: true ``` ### Related Resources * [NGINX `ngx_http_stub_status_module`](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html) * [NGINX `ngx_http_log_module`](https://nginx.org/en/docs/http/ngx_http_log_module.html) * [OpenTelemetry `nginxreceiver`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/nginxreceiver) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/sources/nginx.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.