Debug mode in Nginx - Commands & Configuration

Introduction

Sometimes your web server has problems and you need to find out what is wrong. Debug mode in nginx helps by showing detailed information about what the server is doing. This makes it easier to fix issues.

When your website is not loading and you want to see detailed error messages.

When you want to check how nginx processes requests step-by-step.

When you need to find configuration mistakes causing server errors.

When you want to monitor how nginx handles connections and responses.

When troubleshooting slow responses or unexpected behavior in nginx.

Config File - nginx.conf

nginx.conf

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    error_log  /var/log/nginx/error.log debug;

    server {
        listen       80;
        server_name  localhost;

        location / {
            root   /usr/share/nginx/html;
            index  index.html index.htm;
        }
    }
}

This configuration sets nginx to run with one worker process and allows 1024 connections. The key part is error_log /var/log/nginx/error.log debug; which enables debug mode for error logging. This means nginx will write detailed debug information to the error log file. The server block listens on port 80 and serves files from the default html folder.

Commands

This command tests the nginx configuration file for syntax errors before applying it. It helps ensure the config is valid.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command restarts the nginx service to apply the new configuration with debug mode enabled.

Terminal

sudo systemctl restart nginx

Expected Output

No output (command runs silently)

This command shows the live debug logs from nginx error log file. You can watch detailed debug messages as requests come in.

Terminal

sudo tail -f /var/log/nginx/error.log

Expected Output

2024/06/01 12:00:00 [debug] 12345#0: *1 http request line: "GET / HTTP/1.1"

2024/06/01 12:00:00 [debug] 12345#0: *1 http uri: "/"

2024/06/01 12:00:00 [debug] 12345#0: *1 http args: ""

Key Concept

If you remember nothing else from this pattern, remember: enabling debug mode in nginx means setting the error_log level to debug to get detailed logs.

Common Mistakes

Not testing the nginx configuration before restarting the service.

If the config has errors, nginx will fail to start and your website will be down.

Always run 'sudo nginx -t' to check the config syntax before restarting nginx.

Forgetting to restart nginx after changing the configuration.

Changes in the config file do not take effect until nginx is restarted or reloaded.

Run 'sudo systemctl restart nginx' or 'sudo nginx -s reload' after config changes.

Not checking the correct error log file for debug messages.

Debug messages only appear in the error log file set with debug level, missing them means no useful info.

Verify the error_log path and level in nginx.conf and check that file for debug output.

Summary

Set the error_log directive with debug level in nginx.conf to enable debug mode.

Test the configuration with 'nginx -t' before restarting nginx.

Restart nginx to apply changes and use 'tail -f' on the error log to see debug messages.

Practice

1. What does enabling debug mode in nginx do?

easy

A. Shows detailed logs to help find problems

B. Stops nginx from running

C. Deletes all log files

D. Automatically fixes errors

Solution

1. Step 1: Understand debug mode purpose

   Debug mode is designed to provide detailed information about what nginx is doing internally.

2. Step 2: Identify effect of enabling debug mode

   It shows detailed logs that help find and fix problems in nginx configuration or operation.

3. Final Answer:

   Shows detailed logs to help find problems -> Option A

4. Quick Check:

   Debug mode = detailed logs [OK]

Hint: Debug mode means detailed logs for troubleshooting [OK]

Common Mistakes:

• Thinking debug mode stops nginx
• Believing debug mode deletes logs
• Assuming debug mode auto-fixes errors

2. Which is the correct syntax to enable debug mode in nginx's error log?

easy

A. error_log debug /var/log/nginx/error.log;

B. error_log /var/log/nginx/error.log info;

C. error_log /var/log/nginx/error.log debug;

D. error_log /var/log/nginx/error.log off;

Solution

1. Step 1: Recall error_log syntax

   The correct syntax is: error_log <file_path> <level>; where level can be debug, info, etc.

2. Step 2: Identify correct option

   error_log /var/log/nginx/error.log debug; uses correct order: file path first, then debug level.

3. Final Answer:

   error_log /var/log/nginx/error.log debug; -> Option C

4. Quick Check:

   error_log file_path debug; = error_log /var/log/nginx/error.log debug; [OK]

Hint: error_log path then level debug; is correct syntax [OK]

Common Mistakes:

• Swapping file path and level order
• Using info instead of debug for debug mode
• Setting level to off disables logging

3. Given this nginx config snippet:

error_log /var/log/nginx/error.log debug;
server {
  listen 80;
  server_name example.com;
}

What will happen when nginx receives a request?

medium

A. Detailed debug logs will be written to /var/log/nginx/error.log

B. No logs will be created

C. Only error messages will be logged

D. Nginx will refuse connections

Solution

1. Step 1: Analyze error_log level

   The error_log is set to debug level, which logs detailed info about requests.

2. Step 2: Understand effect on request handling

   When nginx receives a request, it logs detailed debug info to the specified file.

3. Final Answer:

   Detailed debug logs will be written to /var/log/nginx/error.log -> Option A

4. Quick Check:

   debug level logs detailed info [OK]

Hint: debug level logs detailed info on requests [OK]

Common Mistakes:

• Thinking debug disables logging
• Assuming only errors are logged
• Believing nginx refuses connections with debug

4. You set error_log /var/log/nginx/error.log debug; but see no debug logs. What is a likely cause?

medium

A. Debug mode disables logging

B. Nginx was not reloaded after config change

C. The log file path is missing

D. The debug level is misspelled

Solution

1. Step 1: Check if config changes are active

   After changing nginx config, you must reload nginx to apply changes.

2. Step 2: Identify why no debug logs appear

   If nginx is not reloaded, it uses old config without debug logging.

3. Final Answer:

   Nginx was not reloaded after config change -> Option B

4. Quick Check:

   Reload nginx after config change [OK]

Hint: Reload nginx after config changes to activate debug [OK]

Common Mistakes:

• Forgetting to reload nginx
• Thinking debug disables logs
• Misspelling debug level

5. You want to enable debug mode only temporarily to avoid large log files. Which is the best approach?

hard

A. Delete log files manually to reduce size

B. Permanently set debug mode in nginx.conf

C. Disable logging completely during debugging

D. Set error_log /var/log/nginx/error.log debug;, reload nginx, then revert after debugging

Solution

1. Step 1: Understand temporary debug enabling

   Temporarily enable debug by changing error_log level and reloading nginx.

2. Step 2: Revert changes after debugging

   To avoid large logs, revert error_log level back and reload nginx again.

3. Final Answer:

   Set error_log /var/log/nginx/error.log debug;, reload nginx, then revert after debugging -> Option D

4. Quick Check:

   Temporary debug = enable then revert [OK]

Hint: Enable debug, reload, then revert to avoid big logs [OK]

Common Mistakes:

• Leaving debug mode enabled permanently
• Deleting logs instead of controlling debug level
• Disabling logging disables debug info