make nginx tracing more clear

Author: AbhiPrasad

docs/product/drains/otlp-guides/nginx.mdx

@@ -37,12 +37,54 @@ ___OTLP_LOGS_URL___
 x-sentry-auth: sentry sentry_key=___PUBLIC_KEY___
 ```
 
-## Step 3: Configure Nginx Logging (Optional)
+## Step 3: Configure Nginx Logging
 
-Nginx logs are stored by default at `/var/log/nginx/access.log`. For better log parsing, you can configure Nginx to output logs in JSON format.
+Nginx logs are stored by default at `/var/log/nginx/access.log`. For better observability, configure Nginx to output structured JSON logs with trace context fields. This allows your Nginx logs to be correlated with distributed traces in Sentry.
+
+### JSON Logging with Trace Context (Recommended)
+
+To correlate Nginx logs with traces, you need to include trace context fields in your log format. This requires the [NGINX OpenTelemetry module](https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/nginx) to be installed, which provides the `$otel_trace_id`, `$otel_span_id`, and `$otel_trace_flags` variables.
 
 Add the following to your Nginx configuration (typically `/etc/nginx/nginx.conf`):
 
+```nginx {filename:nginx.conf}
+load_module modules/ngx_otel_module.so;
+
+http {
+    # Enable OpenTelemetry tracing
+    otel_exporter {
+        endpoint localhost:4317;
+    }
+    otel_trace on;
+
+    log_format json_combined escape=json
+      '{'
+        '"time_local":"$time_local",'
+        '"remote_addr":"$remote_addr",'
+        '"remote_user":"$remote_user",'
+        '"request":"$request",'
+        '"status":$status,'
+        '"body_bytes_sent":$body_bytes_sent,'
+        '"http_referer":"$http_referer",'
+        '"http_user_agent":"$http_user_agent",'
+        '"request_time":$request_time,'
+        '"trace_id":"$otel_trace_id",'
+        '"span_id":"$otel_span_id",'
+        '"trace_flags":"$otel_trace_flags"'
+      '}';
+
+    access_log /var/log/nginx/access.log json_combined;
+
+    # ... rest of your configuration
+}
+```
+
+The trace context fields enable Sentry to link your Nginx access logs directly to the corresponding traces, giving you full visibility into request flows.
+
+### Basic JSON Logging (Without Trace Context)
+
+If you don't have the OpenTelemetry module installed, you can still use structured JSON logging:
+
 ```nginx {filename:nginx.conf}
 http {
     log_format json_combined escape=json
@@ -77,18 +119,36 @@ Create a configuration file with the File Log Receiver and the OTLP HTTP exporte
 
 For additional configuration options, see the [File Log Receiver Documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver).
 
-### Basic Configuration
+### Configuration with Trace Context (Recommended)
 
-This configuration collects Nginx access and error logs:
+If you configured Nginx with the OpenTelemetry module and JSON logging with trace context fields, use this configuration to parse the logs and extract trace correlation:
 
 ```yaml {filename:config.yaml}
 receivers:
   filelog:
     include:
       - /var/log/nginx/access.log
+    attributes:
+      service.name: nginx
+    operators:
+      - type: json_parser
+        timestamp:
+          parse_from: attributes.time_local
+          layout: "%d/%b/%Y:%H:%M:%S %z"
+      - type: trace_parser
+        trace_id:
+          parse_from: attributes.trace_id
+        span_id:
+          parse_from: attributes.span_id
+        trace_flags:
+          parse_from: attributes.trace_flags
+
+  filelog/error:
+    include:
       - /var/log/nginx/error.log
     attributes:
       service.name: nginx
+      log.type: error
 
 processors:
   batch:
@@ -109,35 +169,27 @@ service:
     logs:
       receivers:
         - filelog
+        - filelog/error
       processors:
         - batch
       exporters:
         - otlphttp/sentry
 ```
 
-### Configuration with JSON Parsing
+The `trace_parser` operator extracts the trace ID, span ID, and trace flags from the parsed JSON attributes and sets them on the log record. This enables Sentry to correlate these logs with the corresponding traces.
+
+### Basic Configuration
 
-If you configured Nginx to output JSON logs, you can parse them for structured log data:
+This configuration collects Nginx access and error logs:
 
 ```yaml {filename:config.yaml}
 receivers:
   filelog:
     include:
       - /var/log/nginx/access.log
-    attributes:
-      service.name: nginx
-    operators:
-      - type: json_parser
-        timestamp:
-          parse_from: attributes.time_local
-          layout: "%d/%b/%Y:%H:%M:%S %z"
-
-  filelog/error:
-    include:
       - /var/log/nginx/error.log
     attributes:
       service.name: nginx
-      log.type: error
 
 processors:
   batch:
@@ -158,7 +210,6 @@ service:
     logs:
       receivers:
         - filelog
-        - filelog/error
       processors:
         - batch
       exporters: