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 Types

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.
• 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.
• 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

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 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.

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

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
• NGINX ngx_http_log_module
• OpenTelemetry nginxreceiver