> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring Nginx traces with ClickStack

> Monitoring Nginx Traces with ClickStack

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **TL;DR**

  Capture distributed traces from Nginx in ClickStack using the OpenTelemetry Nginx module. Includes a demo dataset and pre-built dashboard.
</Info>

<h2 id="existing-nginx">
  Integration with existing Nginx
</h2>

This section covers adding distributed tracing to your existing Nginx installation by installing the OpenTelemetry module and configuring it to send traces to ClickStack.
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](/clickstack/integration-examples/nginx-traces#demo-dataset).

<h5 id="prerequisites">
  Prerequisites
</h5>

* ClickStack instance running with OTLP endpoints accessible (ports 4317/4318)
* Existing Nginx installation (version 1.18 or higher)
* Root or sudo access to modify Nginx configuration
* ClickStack hostname or IP address

<Steps>
  <Step>
    <h4 id="install-module">
      Install OpenTelemetry Nginx module
    </h4>

    The easiest way to add tracing to Nginx is using the official Nginx image with OpenTelemetry support built-in.

    <h5 id="using-otel-image">
      Using the nginx:otel image
    </h5>

    Replace your current Nginx image with the OpenTelemetry-enabled version:

    ```yaml theme={null}
    # In your docker-compose.yml or Dockerfile
    image: nginx:1.27-otel
    ```

    This image includes the `ngx_otel_module.so` pre-installed and ready to use.

    <Note>
      If you're running Nginx outside of Docker, refer to the [OpenTelemetry Nginx documentation](https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/nginx) for manual installation instructions.
    </Note>
  </Step>

  <Step>
    <h4 id="configure-nginx">
      Configure Nginx to send traces to ClickStack
    </h4>

    Add OpenTelemetry configuration to your `nginx.conf` file. The configuration loads the module and directs traces to ClickStack's OTLP endpoint.

    First, get your API key:

    1. Open HyperDX at your ClickStack URL
    2. Navigate to Settings → API Keys
    3. Copy your **Ingestion API Key**
    4. Set it as an environment variable: `export CLICKSTACK_API_KEY=your-api-key-here`

    Add this to your `nginx.conf`:

    ```yaml theme={null}
    load_module modules/ngx_otel_module.so;

    events {
        worker_connections 1024;
    }

    http {
        # OpenTelemetry exporter configuration
        otel_exporter {
            endpoint <clickstack-host>:4317;
            header authorization ${CLICKSTACK_API_KEY};
        }
        
        # Service name for identifying this nginx instance
        otel_service_name "nginx-proxy";
        
        # Enable tracing
        otel_trace on;
        
        server {
            listen 80;
            
            location / {
                # Enable tracing for this location
                otel_trace_context propagate;
                otel_span_name "$request_method $uri";
                
                # Add request details to traces
                otel_span_attr http.status_code $status;
                otel_span_attr http.request.method $request_method;
                otel_span_attr http.route $uri;
                
                # Your existing proxy or application configuration
                proxy_pass http://your-backend;
            }
        }
    }
    ```

    If running Nginx in Docker, pass the environment variable to the container:

    ```yaml theme={null}
    services:
      nginx:
        image: nginx:1.27-otel
        environment:
          - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
        volumes:
          - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ```

    Replace `<clickstack-host>` with your ClickStack instance hostname or IP address.

    <Note>
      * **Port 4317** is the gRPC endpoint used by the Nginx module
      * **otel\_service\_name** should be descriptive of your Nginx instance (e.g., "api-gateway", "frontend-proxy")
      * Change **otel\_service\_name** to match your environment for easier identification in HyperDX
    </Note>

    <h5 id="understanding-configuration">
      Understanding the configuration
    </h5>

    **What gets traced:**
    Each request to Nginx creates a trace span showing:

    * Request method and path
    * HTTP status code
    * Request duration
    * Timestamp

    **Span attributes:**
    The `otel_span_attr` directives add metadata to each trace, allowing you to filter and analyze requests in HyperDX by status code, method, route, etc.

    After making these changes, test your Nginx configuration:

    ```bash theme={null}
    nginx -t
    ```

    If the test passes, reload Nginx:

    ```bash theme={null}
    # For Docker
    docker-compose restart nginx

    # For systemd
    sudo systemctl reload nginx
    ```
  </Step>

  <Step>
    <h4 id="verifying-traces">
      Verifying traces in HyperDX
    </h4>

    Once configured, log into HyperDX and verify traces are flowing, you should see something like this, if you don't see traces, try adjusting your time range:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/nginx-traces-search-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=392f0f4ed941a5091c970090a6190769" alt="View Traces" width="3838" height="1938" data-path="images/clickstack/nginx-traces-search-view.png" />
  </Step>
</Steps>

<h2 id="demo-dataset">
  Demo dataset
</h2>

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

<Steps>
  <Step>
    <h4 id="start-clickstack">
      Start ClickStack
    </h4>

    If you don't have ClickStack running yet, start it with:

    ```bash theme={null}
    docker run --name clickstack-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

    Wait about 30 seconds for ClickStack to fully initialize before proceeding.

    * Port 8080: HyperDX web interface
    * Port 4317: OTLP gRPC endpoint (used by nginx module)
    * Port 4318: OTLP HTTP endpoint (used for demo traces)
  </Step>

  <Step>
    <h4 id="download-sample">
      Download the sample dataset
    </h4>

    Download the sample traces file and update timestamps to the current time:

    ```bash theme={null}
    # Download the traces
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json
    ```

    The dataset includes:

    * 1,000 trace spans with realistic timing
    * 9 different endpoints with varied traffic patterns
    * \~93% success rate (200), \~3% client errors (404), \~4% server errors (500)
    * Latencies ranging from 10ms to 800ms
    * Original traffic patterns preserved, shifted to current time
  </Step>

  <Step>
    <h4 id="send-traces">
      Send traces to ClickStack
    </h4>

    Set your API key as an environment variable (if not already set):

    ```bash theme={null}
    export CLICKSTACK_API_KEY=your-api-key-here
    ```

    **Get your API key:**

    1. Open HyperDX at your ClickStack URL
    2. Navigate to Settings → API Keys
    3. Copy your **Ingestion API Key**

    Then send the traces to ClickStack:

    ```bash theme={null}
    curl -X POST http://localhost:4318/v1/traces \
      -H "Content-Type: application/json" \
      -H "Authorization: $CLICKSTACK_API_KEY" \
      -d @nginx-traces-sample.json
    ```

    <Info>
      **Running on localhost**

      This demo assumes ClickStack is running locally on `localhost:4318`. For remote instances, replace `localhost` with your ClickStack hostname.
    </Info>

    You should see a response like `{"partialSuccess":{}}` indicating the traces were successfully sent. All 1,000 traces will be ingested into ClickStack.
  </Step>

  <Step>
    <h4 id="verify-demo-traces">
      Verify traces in HyperDX
    </h4>

    1. Open [HyperDX](http://localhost:8080/) and log in to your account (you may need to create an account first)
    2. Navigate to the Search view and set the source to `Traces`
    3. Set the time range to **2025-10-25 13:00:00 - 2025-10-28 13:00:00**

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

    <Info>
      **Timezone Display**

      HyperDX displays timestamps in your browser's local timezone. The demo data spans **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)**. The wide time range ensures you'll see the demo traces regardless of your location. Once you see the traces, you can narrow the range to a 24-hour period for clearer visualizations.
    </Info>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/nginx-traces-search-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=392f0f4ed941a5091c970090a6190769" alt="View Traces" width="3838" height="1938" data-path="images/clickstack/nginx-traces-search-view.png" />
  </Step>
</Steps>

<h2 id="dashboards">
  Dashboards and visualization
</h2>

To help you get started monitoring traces with ClickStack, we provide essential visualizations for trace data.

<Steps>
  <Step>
    <h4 id="download">
      <TrackedLink href={'/examples/nginx-traces-dashboard.json'} download="nginx-traces-dashboard.json" eventName="docs.nginx_traces_monitoring.dashboard_download">Download</TrackedLink> the dashboard configuration
    </h4>
  </Step>

  <Step>
    <h4 id="import-dashboard">
      Import the pre-built dashboard
    </h4>

    1. Open HyperDX and navigate to the Dashboards section.
    2. Click "Import Dashboard" in the upper right corner under the ellipses.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/import-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=cdfe26f160c1c080b995c8451311241d" alt="Import Dashboard" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/finish-nginx-traces-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=61bedea50b428001998f1096e1fe0761" alt="Finish Import" width="3812" height="1906" data-path="images/clickstack/finish-nginx-traces-dashboard.png" />
  </Step>

  <Step>
    <h4 id="created-dashboard">
      The dashboard will be created with all visualizations pre-configured.
    </h4>

    <Note>
      For the demo dataset, set the time range to **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)** (adjust based on your local timezone). The imported dashboard won't have a time range specified by default.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/nginx-traces-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=6496aed12bbbb3a91b7a162176469994" alt="Example Dashboard" width="3812" height="1906" data-path="images/clickstack/nginx-traces-dashboard.png" />
  </Step>
</Steps>

<h2 id="troubleshooting">
  Troubleshooting
</h2>

<h3 id="no-traces">
  No traces appearing in HyperDX
</h3>

**Verify nginx module is loaded:**

```bash theme={null}
nginx -V 2>&1 | grep otel
```

You should see references to the OpenTelemetry module.

**Check network connectivity:**

```bash theme={null}
telnet <clickstack-host> 4317
```

This should connect successfully to the OTLP gRPC endpoint.

**Verify API key is set:**

```bash theme={null}
echo $CLICKSTACK_API_KEY
```

Should output your API key (not empty).

**Check nginx error logs:**

```bash theme={null}
# For Docker
docker logs <nginx-container> 2>&1 | grep -i otel

# For systemd
sudo tail -f /var/log/nginx/error.log | grep -i otel
```

Look for OpenTelemetry-related errors.

**Verify nginx is receiving requests:**

```bash theme={null}
# Check access logs to confirm traffic
tail -f /var/log/nginx/access.log
```

<h2 id="next-steps">
  Next steps
</h2>

* Set up [alerts](/clickstack/features/alerts) for critical metrics (error rates, latency thresholds)
* Create additional [dashboards](/clickstack/features/dashboards/overview) for specific use cases (API monitoring, security events)

<h2 id="going-to-production">
  Going to production
</h2>

This guide sends traces directly from the Nginx OpenTelemetry module to ClickStack's OTLP endpoint. For production deployments, we recommend running your own OTel Collector as a gateway to provide batching and resilience. See [Sending OpenTelemetry data](/clickstack/ingesting-data/opentelemetry) for production configuration.