Nginx, like most applications, records a wealth of data related to client interactions, system events, and potential errors. However, this data's potential can only be fully realized through proper configuration, management, and analysis.
This article will teach you to effectively customize Nginx logs for enhanced visibility and control over your web servers and proxies. Doing this will help you proactively identify and address issues before they disrupt user experience.
Let's begin!
To follow through with this tutorial, you need the following:
sudo privileges.Using the official Docker image is the easiest way to begin working with the Nginx. It simplifies the setup process and ensures consistent reproducibility across different systems.
To get started, create a new nginx-logging-tutorial directory, navigate into
it, and execute the following docker run command: :
In this command:
--name nginx-server: Assigns the nginx-server name to the container for
easier reference.--rm: Automatically removes the container when it's stopped, ideal for
testing or temporary setups.-p 80:80: Maps port 80 of your host machine to port 80 inside the container,
allowing you to access the Nginx server at http://localhost.If the nginx image isn't already present on your system, Docker will download
it before launching the container.
If you encounter an error like the following:
It indicates that another application on your system is already using port 80. Ensure that no other services are running on this port before retrying the command.
If Nginx starts successfully, you'll see messages like these in your terminal:
Now, open your web browser and navigate to http://localhost. You should be
greeted by the default Nginx welcome page, confirming that your web server is up
and running.
Upon returning to your terminal, you might notice log entries like these:
These logs reveal that your browser successfully fetched the main webpage but
encountered a 404 error when attempting to retrieve the favicon.ico file
because it's not in the default Nginx directory.
Feel free to stop the Nginx container using Ctrl-C before moving on to the
next section, where we'll dive deeper into the meaning of these log messages.
Like most web servers, Nginx meticulously records its activities in two distinct log files:
Access log: This file chronicles each incoming request, capturing crucial details such as the client's IP address, the timestamp of the request, the requested resource (URI), the HTTP status code of the response, and the client's user agent (browser and operating system).
Error log: This file serves as a diagnostic tool, recording errors and issues encountered during request processing and other Nginx operations. It logs information such as the timestamp, error level, error message, and any relevant context to aid troubleshooting.
The location of these log files varies depends on your operating system and Nginx installation method.
In most Linux distributions, Nginx log files are typically located in the
/var/log/nginx/ directory. You'll find them named access.log and error.log
respectively.
If you can't find the log files in the default location, you'll need to check
your specific Nginx configuration. Start by determining the location of your
Nginx configuration file (usually /etc/nginx/nginx.conf):
This command should output the location of your configuration file if it's valid:
Open the configuration file and look for the error_log and access_log
directives to pinpoint their respective locations.
By default, Nginx applies the error_log directive globally, while the
access_log is usually placed within the http block.
You can use the tail command to view the contents of these files in real-time:
Since Docker containers are ephemeral, it's not practical to store logs directly
within the container. The official Nginx Docker image addresses this by creating
symbolic links from /var/log/nginx/access.log and /var/log/nginx/error.log
to the container's standard output (/dev/stdout) and standard error
(/dev/stderr) streams respectively. This enables Docker's logging
mechanisms to collect and manage the logs.
You can find the relevant lines in the Dockerfile:
Start the nginx-server container once again, but detach it from your current
terminal session:
With the container running, visit http://localhost once again to generate some
logs, then use the docker logs command to view them accordingly:
You will see the familiar Nginx log output which combines both the access and error logs:
To view only the access logs, redirect the standard error to /dev/null:
Similarly, to view only the error logs, redirect the standard output to
/dev/null:
Now that you know how to locate and access Nginx log files in various environments, let's explore how you can customize the access log format to suit your needs.
By default, Nginx access logs are generated in the combined format unless
otherwise specified. This format is defined as:
This configuration produces access log entries similar to this:
Let's break down what each token in the log represents:
172.17.0.1: The IP address of the client that made the request.-: If authentication is used, this is the authenticated username; otherwise,
it's a hyphen (-).[27/May/2025:16:37:59 +0000]: The local time when the request was processed."GET / HTTP/1.1" : The request method, path, and HTTP protocol version.200: The HTTP status code returned to the client.615: The size of the response body in bytes."-": The URL of the referring page (if any)."Mozilla/5.0 (X11; Linux x86_64; rv:128.0) Gecko/20100101 Firefox/128.0" -
The browser and operating system information provided by the client."-": If the request passed through a proxy, this variable contains the
original client IP address.While this format captures a wide range of information that is useful for analyzing traffic patterns, troubleshooting errors, and understanding user behavior, you may want to customize it to capture only the data that matters most to you. Let's look at how to do that next.
You can tailor the access log format using the log_format directive in either
the main Nginx configuration file (/etc/nginx/nginx.conf) or within
host-specific configurations in /etc/nginx/sites-enabled.
If Nginx is running directly on your host machine, you can edit the relevant
file accordingly. For Docker instances, execute the command below to extract the
Nginx configuration file from the nginx image and save it to an nginx.conf
file on your host machine:
Once you're ready to launch the container once again, ensure to mount the
modified file from your host machine to /etc/nginx/nginx.conf within the
container:
Running Nginx in Docker? Better Stack provides eBPF-based observability that automatically captures logs, metrics, and network traces from your containers—no code changes required.
Get instant visibility into request latency, HTTP errors, and service dependencies with our remotely controlled collector. Forward logs using Vector or connect directly via OpenTelemetry.
Predictable pricing starting at $0.25/GB. Start free in minutes.
Customizing the format of the entries in the access log can be done using the
log_format directive:
All you need to do is give the custom format a name and define the structure of the log using the provided core variables and log variables. Here's an example of what it could look like:
This example adds the $host variable to the combined log format so that it the
domain (or subdomain) being requested is also presented in the logs.
To apply this custom format, modify the access_log directive:
Save your changes, then stop and remove your existing nginx-server container
with:
Start it again with:
When you visit http://localhost now, you will observe that the domain is
recorded in the corresponding log entry:
Nginx's access logs can become quite large, especially under heavy traffic. Conditional logging allows you to selectively filter log entries based on specific criteria to reduce log volume and improve performance.
The syntax looks like this:
The <condition> is a boolean expression that Nginx evaluates for each request.
If it evaluates to true, the log entry is written; otherwise, it's skipped.
The following example demonstrates how to exclude successful (2xx) and redirection (3xx) status codes from the access log:
Some practical applications of conditional logging include:
If you're already collecting request logs through your web application, you may
want to disable the Nginx access log by using a special off value, or by
redirecting to /dev/null
In the world of cloud-native distributed systems and microservices, structured logging has gained significant traction due to its numerous benefits over traditional plain-text logs.
For example, Caddy, an Nginx alternative, produces access logs that look like this:
Let's explore how to bring Nginx access logs into this modern era.
While Nginx doesn't natively produce JSON logs, you can achieve this using the
log_format directive in conjunction with the escape=json parameter which
ensures that characters that aren't valid in JSON are properly escaped.
Let's see how this works:
In this configuration:
custom_json and enabled JSON escaping with
escape=json.$http_<header_name>.$sent_http_<header_name>.custom_json format is applied to the access log.After saving the configuration and restarting Nginx, make a request with some fictional distributed tracing headers:
You'll observe new access log entries in a clean JSON format:
This structured format makes your logs much easier to parse and analyze, opening the doors to powerful log management and visualization capabilities.
The Nginx error log is a crucial tool for diagnosing and resolving issues with your web server. It captures errors, warnings, and other important events that occur during various Nginx operations. Let's explore how to configure and manage this valuable resource.
The error_log directive controls Nginx's error logging behavior. It accepts
two parameters: the path of the log file, and the minimum severity
level of the log.
Nginx categorizes error log messages into the following levels, ranging from least to most severe:
debug: Highly detailed messages primarily used for troubleshooting and
development.info: General informational messages about the server's operation.notice: Noteworthy events that aren't necessarily errors.warn: Unexpected occurrences that could indicate potential problems.error: Actual errors encountered during processing.crit: Critical conditions that require attention.alert: Errors that demand immediate action.emerg: Severe errors that render the system unusable.If you haven't explicitly configured the error severity level in your Nginx
configuration, you will see messages at the error level and all levels above
it (crit, alert, and emerg). However, the default level for the official
Nginx docker image is set to notice.
To change the default error log level, provide the desired level as the second
parameter to the error_log directive:
This configuration will log messages at the warn level and all higher levels.
Nginx error logs adhere to a format designed for human readability and easy parsing by tools. The general format is:
Where:
<pid>: Process ID<tid>: Thread ID<cid>: Connection IDHere's an example of an actual error log entry:
Similar to access logs, you can configure Nginx to log errors to multiple files, even with different severity levels:
In this setup, all events except debug level messages will be logged to
error.log, while emergency events will be logged to a separate file named
emerg_error.log.
If you need to completely disable the Nginx error log (though not generally
recommended), you can redirect it to /dev/null. There doesn't appear to be a
special off value at the time of writing.
In the next section, we'll look at how you can structure your Nginx error logs in JSON format.
While Nginx doesn't offer built-in JSON formatting for its error logs, we can leverage external log processing tools like Logstash, Fluentd, or Vector to parse, reformat, and enrich these logs for better analysis and integration with modern logging systems.
In this section, I'll demonstrate how to use Vector to transform Nginx error logs into structured JSON format, providing similar benefits to what we achieved with the access logs in the previous step.
If you haven't already, install Vector on your machine or pull the official Docker image:
Next, create a vector.yaml file in the current directory with the following
contents:
sources: Defines the log source. In this case, we're collecting logs from
Docker containers based on the nginx image.
transforms: Defines a transformation named nginx_json.
type: remap: Uses the Vector Remap Language (VRL) for transformation.inputs: Takes input from the nginx source.source: Contains the VRL script:parse_json().parse_nginx_log()..context.message..context.message and deletes
.context.message.. at the end returns the modified event.sinks: Defines the destination for the transformed logs which is the console
in JSON format.
Note for file-based logs: If you're reading the Nginx logs from files, the
sources portion should be changed to:
To see this in action, let's bring up both the Nginx and Vector containers with
Docker Compose. Before you proceed, create a
docker-compose.yml file in your nginx-logging-tutorial directory and
populate it with the contents below:
When configuring the vector service in your docker-compose.yml, it's necessary
to mount the vector.yaml file you created into the container to replace the
default configuration
You also need to mount the Docker socket (/var/run/docker.sock) inside the
container. This gives Vector the necessary access to communicate with the Docker
daemon, enabling it to identify and monitor the logs of other containers you
specify.
However, in a production environment, exposing the Docker socket directly to a container can be a security risk. Consider alternative approaches, such as:
These precautions help safeguard your Docker environment while still allowing Vector to effectively collect and process your Nginx logs.
To bring up your services, ensure that you've removed the running nginx-server
container by pressing CTRL-C before running the command below:
Navigate back to your browser, access http://localhost and refresh the page a
couple of times.
You can then view the processed logs with:
If you have jq installed, you can pipe the
output to jq while ignoring non-JSON objects with:
You will see the following output representing an access log:
The context property contains the original JSON object from Nginx as parsed by
the parse_json() function we used earlier. The other properties were added by
Vector when collecting the logs from the Docker container.
To what see a parsed error log, you can make a request for a non-existent file with:
You will subsequently observe the following entry in the Docker logs:
With structured JSON logs for both access and error events, you're now well-equipped to gain valuable insights into your Nginx server's behavior and performance.
Vector is much more capable than what we've covered here, so ensure to check out its documentation and read our comprehensive guide to get a quick overview.
Now that you've configured and structured your Nginx logs, let's elevate your log management by centralizing them with a dedicated service. This will empower you to view, search, and analyze your logs effortlessly, uncovering valuable insights and identifying potential issues.
Better Stack is an excellent solution for centralized log management. It offers a user-friendly interface, powerful search capabilities, and the ability to set up alerts for critical events.
There are multiple approaches to send your Nginx logs to Better Stack:
The video below demonstrates how the Better Stack Collector works with containerized applications, showing the automatic log collection process:
For this tutorial, we'll demonstrate the Vector approach since it allows you to see how log transformation works. However, if you're running Nginx in a Kubernetes cluster or need to collect metrics and traces alongside logs, the Better Stack Collector is the simpler option.
Let's see how to integrate your Nginx logs with Better Stack using Vector as a log forwarder.
Sign up for a free Better Stack account, then navigate to the Logs & Metrics dashboard. From the left-hand menu, choose Sources and click on Connect source:
Name your source Nginx Logging Tutorial and choose Vector as the platform,
then click Create source:
Upon creating the source, you’ll receive a source token (e.g., qU73jvQjZrNFHimZo4miLdxF) and an ingestion host (e.g., s1315908.eu-nbg-2.betterstackdata.com). Be sure to copy both—these are essential for configuring log forwarding:
Return to your editor, and update your vector.yaml file with the following configuration, replacing <your_betterstack_source_token> and <your_ingesting_host> with the values you copied:
Instead of printing the processed logs to the console, this updated configuration instructs Vector to transmit them into Better Stack over HTTP.
You may now restart your running Docker Compose services with:
Once the services are relaunched, return back to your browser, access
http://localhost and refresh the homepage a couple of times.
Return to your Better Stack tab and access the Live tail view by clicking the link under your source name, or select Live tail from the left menu and use the dropdown filter at the top left to view your Nginx logs:
After a few seconds, you'll start seeing the Nginx logs arriving in Live tail:
You can click on any log entry to view its detailed properties and JSON structure:
To explore Live tail's advanced features for filtering, searching, and analyzing your logs, watch this walkthrough:
Congratulations! You've successfully centralized your Nginx logs with Better Stack. You now have a powerful platform to monitor, search, and analyze your log data, helping you keep your web server and applications running smoothly and efficiently.
Feel free to explore the various features and capabilities of Better Stack to gain deeper insights into your Nginx logs and application behavior.
In this guide, you learned how to locate, access, and interpret Nginx access and error logs, both on traditional servers and within Docker containers. You also learned to customize access logs, implement conditional logging, and format logs as structured JSON for easier analysis.
By following these techniques, you can now effectively monitor your Nginx server, troubleshoot issues, and gain valuable insights into your web traffic and application performance.
Thanks for reading, and happy logging!
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
We use cookies to authenticate users, improve the product user experience, and for personalized ads. Learn more.