Detailed explanation of the use of ngx_http_session_log_module

1. Introduction

In traditional HTTP logs, each request will be recorded separately, which is very intuitive for scenarios such as short connections and asynchronous loading; but in some scenarios where user behavior is analyzed in units of "session", such as video on demand, multi-resource parallel loading, long polling, etc., a single request log is difficult to accurately reflect the life cycle and traffic consumption of the user's entire session.

ngx_http_session_log_moduleModule (Commercial Subscription) is launched for this requirement: it can transfer multiple requestsAggregate into a session, write the log once after the session is over, which is convenient for statistics and analysis. The following will beZero foundation, step-by-step demonstrationThe way to master the module.

2. Prerequisites

• NGINX Commercial Edition: Confirm that it has been includedngx_http_session_log_module。
• Linux environment(Ubuntu/CentOS, etc.), ownsudoPermissions.
• Configuration and reload commands: Can usenginx -t、systemctl reload nginx。

3. Module verification

Execute in the terminal:

nginx -V 2>&1 | grep --color session_log

• If the output contains--with-http_session_log_moduleorsession_log, indicating that the module is available.
• Otherwise, you need to contact the supplier or recompile NGINX (add--add-module=.../ngx_http_session_log_module）。

4. Detailed explanation of core instructions

4.1 session_log_zone

session_log_zone /path/to/log
                 zone=name:size
                 [format=format_name]
                 [timeout=time]
                 [id=var]
                 [md5=expr];

• /path/to/log: Session log file path.
• zone=name:size: Define the shared memory areanameand size (such as1m）。
• format=format_name(Optional): Quote bysession_log_formatThe format defined, the built-in one is by defaultcombined。
• timeout=time(Optional, default 30s): After this time has elapsed since the last request, the session is considered to end and the log is written.
• id=var(Optional): If from the clientvar(For example, a cookie is valid MD5 and will be directly used as the session ID.
• md5=expr:whenidWhen not specified or invalid, based onexpr(Can be spliced ​​by multiple variables) Calculate MD5 as the new session ID.

Key points：Same sessionAll requests undertimeoutThe time window is all classified as the same log; the new session is written and restarted only after the timeout.

4.2 session_log_format

session_log_format name string ...;

• name: Format name, used forsession_log_zoneofformat=Parameters.
• string: Log template, supports all standard HTTP variables, and$body_bytes_sentThe value is accumulated within the session, and other variables take the value of the first request.

Common built-in variables：

4.3 session_log

session_log name | off;

• name: Enable correspondingsession_log_zoneSession log defined in  .
• off: Close the session log inherited at the current level.

Available inhttp、serverorlocationLevel use.

5. Step-by-step configuration example

Below we use "Client IP + User-Agent" as the session identifier and count/media/The session logs for all requests under the path.

5.1 Create a persistent directory

sudo mkdir -p /var/log/nginx/session
sudo chown nginx:nginx /var/log/nginx/session

5.2 Define the session log area in the http block

edit/etc/nginx/,existhttp { ... }Added within:

# Define the session log area, 1MB size, 30s timeout, and the session ends writing to /var/log/nginx/session/# The session format uses the default combined, and can also be customizedsession_log_zone /var/log/nginx/session/
                 zone=media_zone:1m
                 timeout=30s
                 md5=$binary_remote_addr$http_user_agent;

5.3 Custom log format (optional)

To record more fields, you canhttpBlocks continue to be added:

session_log_format media_fmt 
    '$session_log_id '
    '$remote_addr [$time_local] '
    '"$http_user_agent" '
    'bytes_sent=$body_bytes_sent '
    'session_time=$session_time';

Then insession_log_zoneAddformat=media_fmt。

5.4 Enable on server/location

server {
    listen 80;
    server_name ;

    location /media/ {
        # Enable session-level logging        session_log media_zone;
    }

    # Other paths are not recorded}

5.5 Check and Overload

sudo nginx -t && sudo systemctl reload nginx

VI. Verification and Testing

• Simulation sessionRequest the same resource multiple times in the browser or command line to ensure that the interval between consecutive requests is less than 30s:

  curl /media/
  sleep 5
  curl /media/
  

• View log

  tail -n20 /var/log/nginx/session/
  

  You will see something like:

  5f2d3a4b... 192.168.1.10 [12/May/2025:14:00:00 +0800] "Mozilla/5.0 ..." bytes_sent=1048576 session_time=5.123
  

  in:

  • The first columnfor session ID;
  • bytes_sentSend bytes for the accumulated requests for two requests;
  • session_timeThe duration of the first to last request.

7. Typical application scenarios

• Streaming on demand statisticsAggregate a full video playback session (multiple shard requests) to count the total traffic and viewing time.
• Long polling/Comet sessionClassify multiple heartbeats/push requests into one session to evaluate the user's online duration.
• API batch operationIf the client splits multiple batch operations into multiple requests, the total number of requests and data size can be counted according to the session.

8. Advanced configuration and optimization

• Adjust timeout

  • For long connection and heartbeat scenarios, you can change thetimeoutSet higher (such as5m）。

• Specify id parameter

  • If the front-end provides a stable session ID through cookies, it can be writtenid=$cookie_sessionid, avoid repeated new creations.

• Log rotation

  • CooperatelogrotateTools are cut regularly/var/log/nginx/session/*.log, prevent disk fullness.

• Performance monitoring

  • Monitor shared memory usage. If there are a large number of active sessions, it can be increased.zone=size。

9. Frequently Asked Questions and Troubleshooting

10. Summary

passngx_http_session_log_module,you can:

• At session levelDon't replace the request-level log to intuitively count the complete user interaction.
• Aggregation flow and duration, convenient for scenario analysis such as streaming media, long polling, batch APIs, etc.
• Flexible configurationTimeout, format, ID source, meet various business needs.

After mastering the above configuration and tuning methods, you can provide accurate and coherent logging for complex HTTP sessions at the NGINX layer, helping with business monitoring and data analysis. I wish you a smooth start and flexible operation and maintenance!

This is the article about the detailed explanation of the use of ngx_http_session_log_module. For more related content on the use of ngx_http_session_log_module, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!