Monitoring Nginx logs with ClickStack

Integration with existing Nginx

This section covers configuring your existing Nginx installation to send logs to ClickStack by modifying the ClickStack OTel collector configuration. If you would like to test the integration before configuring your own existing setup, you can test with our preconfigured setup and sample data in the following section.

Prerequisites

ClickStack instance running
Existing Nginx installation
Access to modify Nginx configuration files

Configure Nginx log format

First, configure Nginx to output logs in JSON format for easier parsing. Add this log format definition to your nginx.conf:

The nginx.conf file is typically located at:

Linux (apt/yum): /etc/nginx/nginx.conf
macOS (Homebrew): /usr/local/etc/nginx/nginx.conf or /opt/homebrew/etc/nginx/nginx.conf
Docker: Configuration is usually mounted as a volume

Add this log format definition to the http block:

http {
    log_format json_combined escape=json
    '{'
      '"time_local":"$time_local",'
      '"remote_addr":"$remote_addr",'
      '"request_method":"$request_method",'
      '"request_uri":"$request_uri",'
      '"status":$status,'
      '"body_bytes_sent":$body_bytes_sent,'
      '"request_time":$request_time,'
      '"upstream_response_time":"$upstream_response_time",'
      '"http_referer":"$http_referer",'
      '"http_user_agent":"$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log json_combined;
    error_log /var/log/nginx/error.log warn;
}

After making this change, reload Nginx.

Create custom OTel collector configuration

ClickStack allows you to extend the base OpenTelemetry Collector configuration by mounting a custom configuration file and setting an environment variable. The custom configuration is merged with the base configuration managed by HyperDX via OpAMP.

Create a file named nginx-monitoring.yaml with the following configuration:

receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    start_at: end 
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx"

service:
  pipelines:
    logs/nginx:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

This configuration:

Reads Nginx Logs from their standard locations
Parses JSON log entries
Extracts and preserves the original log timestamps
Adds source: Nginx attribute for filtering in HyperDX
Routes logs to the ClickHouse exporter via a dedicated pipeline

Configure ClickStack to load custom configuration

To enable custom collector configuration in your existing ClickStack deployment, you must:

Mount the custom config file at /etc/otelcol-contrib/custom.config.yaml
Set the environment variable CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Mount your Nginx log directories so the collector can read them

Option 1: Docker Compose

Update your ClickStack deployment configuration:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

Option 2: Docker Run (All-in-One Image)

If using the all-in-one image with docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  clickhouse/clickstack-all-in-one:latest

Verifying Logs in HyperDX

Once configured, log into HyperDX and verify logs are flowing:

Navigate to the search view
Set source to Logs, and verify you see log entries with fields like request, request_time, upstream_response_time, etc.

This is an example of what you should see:

Demo dataset

For users who want to test the nginx integration before configuring their production systems, we provide a sample dataset of pre-generated nginx access logs with realistic traffic patterns.

Download the sample dataset

# Download the logs
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

The dataset includes:

Log entries with realistic traffic patterns
Various endpoints and HTTP methods
Mix of successful requests and errors
Realistic response times and byte counts

Create test collector configuration

Create a file named nginx-demo.yaml with the following configuration:

cat > nginx-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/nginx-demo/access.log
    start_at: beginning  # Read from beginning for demo data
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx-demo"

service:
  pipelines:
    logs/nginx-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Run ClickStack with demo configuration

Run ClickStack with the demo logs and configuration:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Verify logs in HyperDX

Once ClickStack is running:

Open HyperDX and log in to your account (you may need to create an account first)
Navigate to the Search view and set the source to Logs
Set the time range to 2025-10-19 11:00:00 - 2025-10-22 11:00:00

Here’s what you should see in your search view:

Dashboards and visualization

To help you get started monitoring nginx with ClickStack, we provide essential visualizations for Nginx Logs.

Download the dashboard configuration

Download the dashboard configuration file.

Import the pre-built dashboard

Open HyperDX and navigate to the Dashboards section.
Click “Import Dashboard” in the upper right corner under the ellipses.

Upload the nginx-logs-dashboard.json file and click finish import.

The dashboard will be created with all visualizations pre-configured

Troubleshooting

Custom config not loading

Verify the environment variable CUSTOM_OTELCOL_CONFIG_FILE is set correctly

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Check that the custom config file is mounted at /etc/otelcol-contrib/custom.config.yaml

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml

View the custom config content to verify it’s readable

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

No logs appearing in HyperDX

Ensure nginx is writing JSON logs

tail -f /var/log/nginx/access.log

Check the collector can read the logs

docker exec `<container>` cat /var/log/nginx/access.log

Verify the effective config includes your filelog receiver

docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog

Check for errors in the collector logs

docker exec `<container>` cat /etc/otel/supervisor-data/agent.log

Next steps

Set up alerts for critical metrics (error rates, latency thresholds)
Create additional dashboards for specific use cases (API monitoring, security events)

Going to production

This guide extends ClickStack’s built-in OpenTelemetry Collector for quick setup. For production deployments, we recommend running your own OTel Collector and sending data to ClickStack’s OTLP endpoint. See Sending OpenTelemetry data for production configuration.