# Nginx

##
Access logs format string

###
Configuration file

The configuration file should be located at:

`/usr/local/etc/nginx/nginx.conf`

The line to configure access logs is the one starting with "log_format main" followed by the list of fields codes.

### Default logs formats

The default logs format string is:

`log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent"'`

### Suggested logs format

The suggested format string, to allow using the most of the functionalities of LogDoctor, is:

`log_format main '$time_iso8601 "$request" $status $request_length $bytes_sent $request_time "$http_referer" "$http_user_agent" $remote_addr'`

### Note the format strings

When copy-pasting the format string, please remove any identation (if present) and just paste the resulting format string only.

### Note on control-characters

Although Nginx does support some control-characters (a.k.a. escape sequences), it is reccomended to not use them inside format strings.
In particular, the carriage return will most-likely overwrite previous fields data, making it very difficult to understand where the current field ends (specially for fields like URIs, queries, user-agents, etc) and nearly impossible to retrieve the overwritten data, which will lead in having a wasted database, un-realistic statistics and/or crashes during execution.
About the new line character, it has no sense to use it, if not for testing purposes. The same is true for the horizontal tab, for which is better to use a simple whitespace instead.
The only control-characters supported by Nginx are \n, \t and \r. Any other character will be ignored and treated as text.

##
Access logs format fields

###
Fields considered by LogDoctor

Only the following fields will be considered, meaning that only these fields' data will be stored and used for the statistics.

Code | Informations
--- | ---
$time_local | Date and time in CLF (NCSA) format.
$time_iso8601 | Date and time in ISO 8601 format.
$msec | Time since epoch (in seconds, with a milliseconds resolution) at the time of the log write.
$request | First line of request, equivalent to: $request_method $request_uri $server_protocol.
$server_protocol | The request protocol (HTTP/v, HTTPS/v).
$request_method | The request method (GET, POST, HEAD, ...).
$request_uri | The requested URI, including the query string (if any).
$uri | The URI path requested, not including the query string.
$query_string | Query string (if any).
$status | HTTP status code.
$request_length | Number of bytes received (including request line, header, and request body).
$bytes_sent | The number of bytes sent to a client.
$request_time | Request processing time in seconds with a milliseconds resolution: time elapsed between the first bytes from the client were read and the log write after the last bytes were sent to the client.
$http_referer | Referrer hostname.
$cookie_NAME | Cookie of the request having the given NAME.
$http_user_agent | Web-browser or Bot identification string.
$remote_addr | IP Address of the visitor (client).
$realip_remote_addr | Original client IP address.

### Fields discarded by LogDoctor

Any field than the ones above won't be considered by LogDoctor.
When generating a log sample, these fields will appear as 'DISCARDED'.
If you aint using logs for any other purpose, please remove unnecessary fields to make the process faster and reduce the possibility of errors.

### References

- Nginx logs formats:
  https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format
  https://docs.nginx.com/nginx/admin-guide/monitoring/logging/#setting-up-the-access-log