GoAccess Manual Page

https://goaccess.io/man
Admin
GoAccess is a real-time web log analyzer and interactive viewer that runs in a terminal or browser,...
Tokens:12,629
Snippets:68
Trust Score:9.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### GoAccess Real-time HTML Output Configuration

Source: https://goaccess.io/man/index

Configuring GoAccess for real-time HTML reports, including specifying the WebSocket URL, port, and address binding for the server. Also mentions TLS/SSL setup.

```shell
# goaccess access.log -o /usr/share/nginx/html/site/report.html --real-time-html
```

```shell
# goaccess access.log -o report.html --real-time-html --ws-url=goaccess.io
```

```shell
# goaccess access.log -o report.html --real-time-html --port=9870
```

```shell
# goaccess access.log -o report.html --real-time-html --addr=127.0.0.1
```

--------------------------------

### GoAccess Date and Timezone Configuration

Source: https://goaccess.io/man/index

Examples for processing logs based on specific dates, date ranges, and converting timezone information. Utilizes `sed` for date filtering and GoAccess options for timezone settings.

```shell
# goaccess access.log --log-format='%h %^[%x] "%r" %s %b "%R" "%u"' --datetime-format='%d/%b/%Y:%H:%M:%S %z' --tz=Europe/Berlin --date-spec=min
```

```shell
# sed -n '/05\/Dec\/2010/,$ p' access.log | goaccess -a -
```

```shell
# sed -n '/'$(date '+%d\/%b\/%Y' -d '1 week ago')'/,$ p' access.log | goaccess -a -
```

```shell
# sed -n '/5\/Nov\/2010/,/5\/Dec\/2010/ p' access.log | goaccess -a -
```

--------------------------------

### GoAccess Report Generation

Source: https://goaccess.io/man/index

Examples for generating interactive terminal reports, static HTML, JSON, and CSV files using GoAccess. Specifies output files and formats.

```shell
# goaccess access.log
```

```shell
# goaccess access.log -a -o report.html
```

```shell
# goaccess access.log -a -d -o report.json
```

```shell
# goaccess access.log --no-csv-summary -o report.csv
```

--------------------------------

### GoAccess Date Filtering and Data Retention

Source: https://goaccess.io/man/index

Examples for filtering logs within a specific date range and retaining data for a specified number of days. Uses `--keep-last` to manage storage.

```shell
# goaccess access.log --keep-last=5
```

--------------------------------

### Filter Log by No File Extension

Source: https://goaccess.io/man/index

This example shows how to parse page views that do not have a file extension (e.g., /contact, /profile/user) by using awk to exclude lines with a dot followed by characters in the request field, and piping to GoAccess.

```shell
# awk '$7!~/..*$/' access.log | goaccess -
```

--------------------------------

### Filter Log by Multiple Status Codes

Source: https://goaccess.io/man/index

This example shows how to parse logs for multiple HTTP status codes (e.g., 3xx and 5xx) using a regular expression in awk. It also includes an option to output the report to an HTML file.

```shell
# tail -f -n +0 access.log | awk '$9~/3[0-9]{2}|5[0-9]{2}/' | goaccess -o out.html -
```

--------------------------------

### Run GoAccess Remotely via SSH

Source: https://goaccess.io/man/index

This example shows how to run GoAccess on a local machine while processing logs from a remote server via SSH. The '-n' option for ssh prevents it from reading from stdin, allowing GoAccess to process the piped log data.

```shell
# ssh -n root@server 'tail -f /var/log/apache2/access.log' | goaccess -
```

--------------------------------

### GoAccess Configuration Options

Source: https://goaccess.io/man/index

Lists various compile-time configuration options for GoAccess. These options enable specific features or modify build behavior. Use './configure --help' for a full list.

```shell
./configure --help
```

```shell
--enable-debug
:   Compile with debugging symbols and turn off compiler optimizations.
```

```shell
--enable-utf8
:   Compile with wide character support. Ncursesw is required.
```

```shell
--enable-geoip=<legacy|mmdb>
:   Compile with GeoLocation support. MaxMind's GeoIP is required. `legacy` will utilize the original GeoIP databases. `mmdb` will utilize the enhanced GeoIP2 databases.
```

```shell
--with-getline
:   Dynamically expands line buffer in order to parse full line requests instead of using a fixed size buffer of 4096.
```

```shell
--with-openssl
:   Compile GoAccess with OpenSSL support for its WebSocket server.
```

--------------------------------

### Download and Unpack GeoIP Legacy Databases

Source: https://goaccess.io/man/index

Instructions for downloading and decompressing legacy GeoIP databases (.dat files) for use with GoAccess.

```shell
# IPv4 Country database:
# Download the GeoIP.dat.gz
# gunzip GeoIP.dat.gz
#
# IPv4 City database:
# Download the GeoIPCity.dat.gz
# gunzip GeoIPCity.dat.gz
```

--------------------------------

### Download and Unpack GeoIP2 Databases

Source: https://goaccess.io/man/index

Instructions for downloading and decompressing GeoIP2 databases (.mmdb files) from sources like MaxMind.

```shell
# For GeoIP2 City database:
# Download the GeoLite2-City.mmdb.gz
# gunzip GeoLite2-City.mmdb.gz
#
# For GeoIP2 Country database:
# Download the GeoLite2-Country.mmdb.gz
# gunzip GeoLite2-Country.mmdb.gz
```

--------------------------------

### General GoAccess Options

Source: https://goaccess.io/man/index

Commonly used command-line flags for GoAccess, including help, version display, and storage method information.

```APIDOC
-h --help
  The help.

-V --version
  Display version information and exit.

-s --storage
  Display current storage method. i.e., B+ Tree, Hash.
```

--------------------------------

### GoAccess File Input/Output Options

Source: https://goaccess.io/man/index

Lists common command-line options for specifying input log files, configuration files, and outputting debug or invalid request logs.

```shell
-f, --log-file=<logfile>
  Specify the path to the input log file.

-p, --config-file=<configfile>
  Specify a custom configuration file to use.

--debug-file=<filename>
  Send all debug messages to the specified file.

--invalid-requests=<filename>
  Log invalid requests to the specified file.

--unknowns-log=<filename>
  Log unknown browsers and OSs to the specified file.

- (stdin)
  Read the log file from stdin.
```

--------------------------------

### GoAccess Basic Server Configuration

Source: https://goaccess.io/man/index

Configures fundamental server settings for GoAccess, including IP address binding, daemonization, user execution, and port selection for the WebSocket server.

```APIDOC
--addr=<address>
  Specify IP address to bind the server to. Otherwise it binds to 0.0.0.0.
  Usually there is no need to specify the address, unless you intentionally would
  like to bind the server to a different address within your server.

--daemonize
  Run GoAccess as daemon (only if --real-time-html enabled).

--user-name=<username>
  Run GoAccess as the specified user.
  Note: It's important to ensure the user or the users' group can access the input and output files as well as any other files needed. Other groups the user belongs to will be ignored. As such it's advised to run GoAccess behind a SSL proxy as it's unlikely this user can access the SSL certificates.

--origin=<url>
  Ensure clients send the specified origin header upon the WebSocket handshake.
  The specified origin should look exactly to the origin header field sent by the
  browser. e.g., --origin=http://goaccess.io

--pid-file=<path/goaccess.pid>
  Write the daemon PID to a file when used along the --daemonize option.

--port=<port>
  Specify the port to use. By default GoAccess listens on port 7890 for the WebSocket server. Ensure this port is opened.

--real-time-html
  Enable real-time HTML output.
```

--------------------------------

### GoAccess Real-time Monitoring and Filtering

Source: https://goaccess.io/man/index

Demonstrates real-time log monitoring and filtering using pipes with `tail`, `grep`, `awk`, and `sed`. Allows dynamic analysis of live or filtered log streams.

```shell
# tail -f access.log | goaccess -
```

```shell
# tail -f access.log | grep -i --line-buffered 'firefox' | goaccess --log-format=COMBINED -
```

```shell
# tail -f -n +0 access.log | grep --line-buffered 'Firefox' | goaccess -o out.html --real-time-html -
```

--------------------------------

### GoAccess Configuration File Path

Source: https://goaccess.io/man/index

Displays the path to the default configuration file when no specific configuration file is provided via arguments.

```APIDOC
--dcf
  Display the path of the default config file when `-p` is not used.
```

--------------------------------

### GoAccess SSL/TLS Configuration

Source: https://goaccess.io/man/index

Details the options required for enabling TLS/SSL support in GoAccess, specifically the paths to the certificate and private key files.

```shell
--ssl-cert=<path/cert.crt>
  Path to TLS/SSL certificate.

--ssl-key=<path/priv.key>
  Path to TLS/SSL private key.

Note: Both options must be used together to enable TLS/SSL, and require GoAccess to be configured with --with-openssl.
```

--------------------------------

### GoAccess Persistence Storage Options

Source: https://goaccess.io/man/index

Options for managing data persistence, including enabling persistence, restoring data from disk, and specifying the database directory.

```APIDOC
--persist
  Persist parsed data into disk. If database files exist, files will be overwritten. This should be set to the first dataset.

--restore
  Load previously stored data from disk. If reading persisted data only, the database files need to exist. See `--persist` and examples below.

--db-path <dir>
  Path where the on-disk database files are stored. The default value is the `/tmp` directory.
```

--------------------------------

### Run GoAccess at Lower Priority

Source: https://goaccess.io/man/index

This command executes GoAccess with a lower system priority using the 'nice' utility. The '-n 19' option sets the niceness level to the lowest, ensuring GoAccess consumes fewer CPU resources.

```shell
# nice -n 19 goaccess access.log -a
```

--------------------------------

### GoAccess UI and Mouse Support Options

Source: https://goaccess.io/man/index

Options to control the GoAccess terminal user interface, including configuration dialogs, header highlighting, and mouse support.

```CLI
--config-dialog
  Prompt log/date configuration window on program start.

--hl-header
  Color highlight active panel.

--with-mouse
  Enable mouse support on main dashboard.
```

--------------------------------

### GoAccess Parse Options: Agent List and Output Resolver

Source: https://goaccess.io/man/index

Enables listing user-agents per host for faster parsing and resolves IPs in HTML or JSON output.

```APIDOC
-a --agent-list
  Enable a list of user-agents by host. For faster parsing, do not enable this flag.

-d --with-output-resolver
  Enable IP resolver on the `HTML` or `JSON` output.
```

--------------------------------

### GoAccess Command Line Usage

Source: https://goaccess.io/man/index

This section details the primary command-line syntax for executing GoAccess. It specifies the required log file input and the structure for applying various command-line options to customize analysis and output.

```shell
goaccess [filename] [ options ... ] [-c][-M][-H][-q][-d][...]
```

--------------------------------

### GoAccess Interactive Keys

Source: https://goaccess.io/man/index

Defines the interactive keybindings used to navigate and control the GoAccess program. These keys allow users to access help, redraw the screen, quit, expand/collapse modules, scroll, change color schemes, search, and manage module focus.

```APIDOC
GoAccess Interactive Keys:

Navigation & Control:
  F1 or h: Main help.
  F5: Redraw main window.
  q: Quit the program, current window, or collapse active module.
  o or ENTER: Expand selected module or open window.
  j: Scroll down within expanded module.
  k: Scroll up within expanded module.
  ^f: Scroll forward one screen within active module.
  ^b: Scroll backward one screen within active module.
  TAB: Iterate modules (forward).
  SHIFT + TAB: Iterate modules (backward).
  g: Move to the first item or top of screen.
  G: Move to the last item or bottom of screen.

Module Management:
  0-9 and Shift + 0: Set selected module to active.
  s: Sort options for active module.

Search & Filtering:
  /: Search across all modules (regex allowed).
  n: Find position of the next occurrence.

Customization:
  c: Set or change scheme color.
```

--------------------------------

### GoAccess Parse Options: Static Files and Browsers File

Source: https://goaccess.io/man/index

Includes static files with query strings and allows specifying a custom list of browsers/crawlers for enhanced parsing.

```APIDOC
--all-static-files
  Include static files that contain a query string.

--browsers-file=<path>
  By default GoAccess parses an "essential/basic" curated list of browsers & crawlers. If you need to add additional browsers, use this option.
  Include an additional tab delimited list of browsers/crawlers/feeds etc. See [config/browsers.list](https://raw.githubusercontent.com/allinurl/goaccess/master/config/browsers.list).
  Note: The SIZE of the list is proportional to the run time. Thus, the longer the list, the more time GoAccess will take to parse it.
```

--------------------------------

### GoAccess Predefined Log Formats

Source: https://goaccess.io/man/index

Specifies the log format string, supporting predefined names for common log formats. Values with spaces or special characters require quotes. Piping data requires pre-configuration of formats.

```APIDOC
--log-format <logformat>

Supported Predefined Formats:

COMBINED     | Combined Log Format
VCOMBINED    | Combined Log Format with Virtual Host
COMMON       | Common Log Format
VCOMMON      | Common Log Format with Virtual Host
W3C          | W3C Extended Log File Format
SQUID        | Native Squid Log Format
CLOUDFRONT   | Amazon CloudFront Web Distribution
CLOUDSTORAGE | Google Cloud Storage
AWSELB       | Amazon Elastic Load Balancing
AWSS3        | Amazon Simple Storage Service (S3)
AWSALB       | Amazon Application Load Balancer
CADDY        | Caddy's JSON Structured format (local/info format)
TRAEFIKCLF   | Traefik's CLF flavor

Note: For CADDY, the default is 'local/info' format, but custom formats can be used.
```

--------------------------------

### Panel Sorting Configuration

Source: https://goaccess.io/man/index

Allows sorting of panels based on specified metrics and order. Users can define how panels are initially sorted by providing a comma-separated string of panel name, metric, and sort order (ASC/DESC).

```APIDOC
--sort-panel=<PANEL,FIELD,ORDER>
  Sort panel on initial load. Sort options are separated by comma. Options are in the form: PANEL,METRIC,ORDER
  **Available Metrics**

  + BY_HITS `Sort by hits`
  + BY_VISITORS `Sort by unique visitors`
  + BY_DATA `Sort by data`
  + BY_BW `Sort by bandwidth`
  + BY_AVGTS `Sort by average time served`
  + BY_CUMTS `Sort by cumulative time served`
  + BY_MAXTS `Sort by maximum time served`
  + BY_PROT `Sort by http protocol`
  + BY_MTHD `Sort by http method`**Available orders**
  + ASC
  + DESC
```

--------------------------------

### Incremental Log Processing: Persist and Restore

Source: https://goaccess.io/man/index

Demonstrates GoAccess's incremental processing. First, persist the dataset from a log file using '--persist'. Then, load and append new data from another log file using '--restore --persist'.

```shell
# last month access log
# goaccess access.log.1 --persist
```

```shell
# append this month access log, and preserve new data
# goaccess access.log --restore --persist
```

--------------------------------

### Configure GeoIP Database Path

Source: https://goaccess.io/man/index

Specifies the path to GeoIP database files (e.g., MMDB format). Supports IPv4/IPv6 files and can be specified multiple times for different databases. `--geoip-city-data` is an alias.

```APIDOC
--geoip-database=<geocityfile>
  Specify path to GeoIP database file. i.e., GeoLiteCity.dat. File needs to be downloaded from maxmind.com. IPv4 and IPv6 files are supported as well. Note: `--geoip-city-data` is an alias of `--geoip-database`. This option can be specified multiple times, once for each database file you wish to use.

  Example:
  geoip-database /mmdb/dbip-asn-lite-2024-04.mmdb
  geoip-database /mmdb/dbip-city-lite-2024-01.mmdb
```

--------------------------------

### GoAccess Multiple Log File Processing

Source: https://goaccess.io/man/index

Shows how to parse multiple log files, including compressed files and logs read from pipes. Demonstrates combining static files with piped input.

```shell
# goaccess access.log access.log.1
```

```shell
# cat access.log.2 | goaccess access.log access.log.1 -
```

```shell
# zcat access.log.*.gz | goaccess access.log -
```

--------------------------------

### GoAccess Virtual Host Processing

Source: https://goaccess.io/man/index

Demonstrates how to process logs containing virtual hosts, append them to requests for analysis, and exclude specific virtual hosts using `awk` and `grep`.

```shell
# awk '$8=$1$8' access.log | goaccess -a -
```

```shell
# grep -v "`cat exclude_vhost_list_file`" vhost_access.log | goaccess -
```

--------------------------------

### Time Specificity Setting

Source: https://goaccess.io/man/index

Configures the time granularity for the time distribution panel. It allows switching between hourly and minute-level (tenth of an hour) specificity for more detailed traffic peak tracking.

```APIDOC
--hour-spec=<hour|min>
  Set the time specificity to either hour (default) or min to display the tenth of an hour appended to the hour.

  This is used in the time distribution panel. It's useful for tracking peaks of traffic on your server at specific times.
```

--------------------------------

### Real OS Name Display

Source: https://goaccess.io/man/index

Enables the display of actual operating system names (e.g., 'Windows XP', 'Snow Leopard') instead of generic classifications in the reports.

```APIDOC
--real-os
  Display real OS names. e.g, Windows XP, Snow Leopard.
```

--------------------------------

### GoAccess Output Formatting and Filtering

Source: https://goaccess.io/man/index

Options to control output formatting, such as JSON pretty-printing, maximum items displayed per panel, and filtering for specific data like crawlers.

```CLI
--crawlers-only
  Parse and display only crawlers (bots).

--json-pretty-print
  Format JSON output using tabs and newlines.

--max-items=<num>
  The maximum number of items to display per panel. The maximum can be a number between 1 and n.
  Note: Only static HTML, CSV, and JSON outputs allow a maximum greater than the default value of 366 (or 50 in real-time HTML output) items per panel.

--no-column-names
  Don't write column names in the terminal output. By default, it displays column names for each available metric in every panel.

--no-csv-summary
  Disable summary metrics on the CSV output.

--no-progress
  Disable progress metrics [total requests/requests per second] when parsing a log.

--no-tab-scroll
  Disable scrolling through panels when TAB is pressed or when a panel is selected using a numeric key.

--no-parsing-spinner
  Do not show the progress metrics and parsing spinner.

--tz=<timezone>
  Outputs the report date/time data in the given timezone. Uses canonical timezone names (e.g., Europe/Berlin, America/Chicago). If an invalid timezone name is given, output will be in GMT.
```

--------------------------------

### GoAccess WebSocket Server URL Configuration

Source: https://goaccess.io/man/index

Explains the `--ws-url` option for specifying the WebSocket server address, including scheme, host, and port.

```shell
--ws-url=<[scheme://]url[:port]>

Examples:
- ws://goaccess.io
- wss://goaccess.io
- goaccess.io:9999
```

--------------------------------

### GoAccess Parse Options: Jobs and HTTP Protocol/Method

Source: https://goaccess.io/man/index

Configures the number of parallel processing threads and controls whether to include HTTP request protocol and method in request keys.

```APIDOC
-j --jobs=<1-6>
  This specifies the number of parallel processing threads to be used during the execution of the program. It determines the degree of concurrency when analyzing log data, allowing for parallel processing of multiple tasks simultaneously. It defaults to 1 thread. It's common to set the number of jobs based on the available hardware resources, such as the number of CPU cores. See `--chunk-size` for more info.

-H --http-protocol=<yes|no>
  Set/unset HTTP request protocol. This will create a request key containing the request protocol + the actual request.

-M --http-method=<yes|no>
  Set/unset HTTP request method. This will create a request key containing the request method + the actual request.
```

--------------------------------

### GoAccess Log and Date Format Configuration

Source: https://goaccess.io/man/index

Details on configuring GoAccess to parse custom log formats, including time and date formatting specifiers. Configuration can be done interactively or via config files.

```APIDOC
time-format
  Specifies the log-format time containing any combination of regular characters and special format specifiers starting with '%'. See `man strftime`. Example: `%T` or `%H:%M:%S`. Use `%f` for microseconds and `%*` for milliseconds.

date-format
  Specifies the log-format date containing any combination of regular characters and special format specifiers starting with '%'. See `man strftime`. Use `%f` for microseconds and `%*` for milliseconds.

log-format
  Specifies the log format string, which can be a predefined format (CLF, Combined, W3C, CloudFront) or a custom string. Use `\t` for tab-delimited.
```

--------------------------------

### GoAccess WebSocket Authentication Configuration

Source: https://goaccess.io/man/index

Demonstrates how to configure GoAccess for JWT-based WebSocket authentication, specifying the secret key source.

```shell
--ws-auth=jwt:verify:<secret>

Where <secret> can be:
+ A path to a file containing the secret key (e.g., /path/to/secret.key)
+ An environment variable name holding the secret (e.g., $JWT_SECRET)
+ The actual HS256 secret key as a string (e.g., mysecretkey123)

Example:
--ws-auth=jwt:verify:/path/to/secret.key
```

--------------------------------

### GoAccess Terminal Color Customization

Source: https://goaccess.io/man/index

Defines how to specify custom colors for terminal output, including foreground, background, attributes, and panel-specific coloring. It also covers selecting predefined color schemes.

```APIDOC
--color=<fg:bg[attrs, PANEL]>
  Specify custom colors for the terminal output.
  Color Syntax:
  DEFINITION space/tab colorFG#:colorBG# [attributes,PANEL]

  Parameters:
    fg: Foreground color number [-1...255] (-1 = default term color).
    bg: Background color number [-1...255] (-1 = default term color).
    attrs: Comma-separated color attributes (e.g., bold,underline,normal,reverse,blink).
    PANEL: Optional panel identifier for panel-specific colors.

  Example Color Constants:
  + COLOR_MTRC_HITS
  + COLOR_MTRC_VISITORS
  + COLOR_MTRC_DATA
  + COLOR_MTRC_BW
  + COLOR_MTRC_AVGTS
  + COLOR_MTRC_CUMTS
  + COLOR_MTRC_MAXTS
  + COLOR_MTRC_PROT
  + COLOR_MTRC_MTHD
  + COLOR_MTRC_HITS_PERC
  + COLOR_MTRC_HITS_PERC_MAX
  + COLOR_MTRC_VISITORS_PERC
  + COLOR_MTRC_VISITORS_PERC_MAX
  + COLOR_PANEL_COLS
  + COLOR_BARS
  + COLOR_ERROR
  + COLOR_SELECTED
  + COLOR_PANEL_ACTIVE
  + COLOR_PANEL_HEADER
  + COLOR_PANEL_DESC
  + COLOR_OVERALL_LBLS
  + COLOR_OVERALL_VALS
  + COLOR_OVERALL_PATH
  + COLOR_ACTIVE_LABEL
  + COLOR_BG
  + COLOR_DEFAULT
  + COLOR_PROGRESS

--color-scheme <1|2|3>
  Choose among terminal color schemes.
  1: Monochrome scheme.
  2: Green scheme.
  3: Monokai scheme (requires terminal support for 256 colors).
```

--------------------------------

### GoAccess Parse Options: Output Format

Source: https://goaccess.io/man/index

Specifies the output file and format (JSON, CSV, HTML). Supports writing to stdout and simultaneously saving multiple output formats.

```APIDOC
-o --output=<json|csv|html>
  Write output to stdout given one of the following files and the corresponding extension for the output format:

  + /path/file.csv - Comma-separated values (CSV)
  + /path/file.json - JSON (JavaScript Object Notation)
  + /path/file.html - HTML
  Note that one can parse the log in a single GoAccess run and simultaneously save two outputs, for example, HTML and JSON, e.g., `--output /path/to/report.html` `--output /path/to/report.json`
```

--------------------------------

### GoAccess Parse Options: Date Specificity and Double Decode

Source: https://goaccess.io/man/index

Sets the date specificity for visitor tracking (date, hour, or minute) and enables double decoding of URLs.

```APIDOC
--date-spec=<date|hr|min>
  Set the date specificity to either date (default), hr to display hours or min to display minutes appended to the date.

  This is used in the visitors panel. It's useful for tracking visitors at the
  hour level. For instance, an hour specificity would yield to display traffic as
  `18/Dec/2010:19` or minute specificity `18/Dec/2010:19:59`.

--double-decode
  
```

--------------------------------

### GoAccess Parse Options: Status Code and Visitor Counts

Source: https://goaccess.io/man/index

Configures how non-standard status codes are treated and whether 4xx client errors contribute to unique visitor counts.

```APIDOC
--444-as-404
  Treat non-standard status code 444 as 404.

--4xx-to-unique-count
  Add 4xx client errors to the unique visitors count.
```

--------------------------------

### Panel Management Options

Source: https://goaccess.io/man/index

Options to enable or ignore specific panels in GoAccess reports. Panels control which data visualizations are displayed. Both options accept the same list of panel names.

```APIDOC
--enable-panel=<PANEL>
  Enable parsing/displaying the given panel. List of panels:

  + VISITORS
  + REQUESTS
  + REQUESTS_STATIC
  + NOT_FOUND
  + HOSTS
  + OS
  + BROWSERS
  + VISIT_TIMES
  + VIRTUAL_HOSTS
  + REFERRERS
  + REFERRING_SITES
  + KEYPHRASES
  + STATUS_CODES
  + REMOTE_USER
  + CACHE_STATUS
  + GEO_LOCATION
  + MIME_TYPE
  + TLS_TYPE

--ignore-panel=<PANEL>
  Ignore parsing/displaying the given panel. List of panels:

  + VISITORS
  + REQUESTS
  + REQUESTS_STATIC
  + NOT_FOUND
  + HOSTS
  + OS
  + BROWSERS
  + VISIT_TIMES
  + VIRTUAL_HOSTS
  + REFERRERS
  + REFERRING_SITES
  + KEYPHRASES
  + STATUS_CODES
  + REMOTE_USER
  + CACHE_STATUS
  + GEO_LOCATION
  + MIME_TYPE
  + TLS_TYPE
```

--------------------------------

### Log Parsing Test Lines

Source: https://goaccess.io/man/index

Specifies the number of log lines GoAccess should test against the provided log format to validate its correctness. Setting this to 0 parses the entire log, making processing less strict but potentially slower.

```APIDOC
--num-tests=<number>
  Number of lines from the access log to test against the provided log/date/time format. By default, the parser is set to test 10 lines. If set to 0, the parser won't test any lines and will parse the whole access log and thus making the processing less strict.

  If a line matches the given log/date/time format before it reaches `number`, the parser will consider the log to be valid, otherwise GoAccess will return `EXIT_FAILURE` and display the relevant error messages.
```

--------------------------------

### Custom Static File Extensions

Source: https://goaccess.io/man/index

Enables the addition of custom file extensions to be recognized as static files. This allows GoAccess to correctly categorize and potentially filter out traffic associated with these file types.

```APIDOC
--static-file=<extension>
  Add static file extension. e.g.: `.mp3`. Extensions are case sensitive.
```

--------------------------------

### GoAccess Parse Options: Query String and Terminal Resolver

Source: https://goaccess.io/man/index

Options to ignore request query strings for memory efficiency and to disable IP resolution in terminal output.

```APIDOC
-q --no-query-string
  Ignore request's query string. i.e., www.google.com/page.htm?query => www.google.com/page.htm
  Note: Removing the query string can greatly decrease memory consumption, especially on timestamped requests.

-r --no-term-resolver
  Disable IP resolver on terminal output.
```

--------------------------------

### Process and Exit Mode

Source: https://goaccess.io/man/index

Instructs GoAccess to parse the log file and then exit without generating any output. This mode is useful for data ingestion into a database or for performing background processing without immediate display.

```APIDOC
--process-and-exit
  Parse log and exit without outputting data. Useful if we are looking to only add new data to the on-disk database without outputting to a file or a terminal.
```

--------------------------------

### GoAccess Color and Output Disabling

Source: https://goaccess.io/man/index

Options to disable specific visual features like color output or progress indicators, providing a cleaner or more basic display.

```CLI
--no-color
  Turn off colored output. This is the default output on terminals that do not support colors.
```

--------------------------------

### Filename to Virtual Host Mapping

Source: https://goaccess.io/man/index

Use log filenames as virtual hosts. A POSIX regular expression is used to extract the virtual host from the filename, allowing GoAccess to associate logs with specific domains based on their file names.

```APIDOC
--fname-as-vhost=<regex>
  Use log filename(s) as virtual host(s). POSIX regex is passed to extract the virtual host from the filename, e.g., `--fname-as-vhost='[a-z]*.[a-z]*'` can be used to extract from the file `awesome.com.log` the vhost of `awesome.com`.
```

--------------------------------

### GoAccess Time Formatting

Source: https://goaccess.io/man/index

Specifies the log format time using strftime specifiers. Use %f for microseconds and %* for milliseconds. Refer to `man strftime` for available specifiers.

```shell
--time-format <timeformat>
```

--------------------------------

### Referrer Filtering Options

Source: https://goaccess.io/man/index

Options to manage how referrers are processed. One option hides referrers while still counting them, and the other completely ignores them. Wildcards are supported for pattern matching.

```APIDOC
--hide-referrer<NEEDLE>
  Hide a referrer but still count it. Wild cards are allowed in the needle. i.e., *.bing.com.

--ignore-referrer=<referrer>
  Ignore referrers from being counted. Wildcards allowed. e.g., `*.domain.com` `ww?.domain.*`
```

--------------------------------

### GoAccess Datetime Formatting

Source: https://goaccess.io/man/index

Combines date and time formatting into a single option, allowing timezone conversion. Use %x in log-format to represent the datetime field. Ensure --date-format and --time-format are not used when this option is active. Refer to `man strftime` for specifiers.

```shell
--datetime-format <date_timeformat>
```

--------------------------------

### Filter Log for Bots

Source: https://goaccess.io/man/index

This command helps identify and parse requests from bots or crawlers. It uses grep to filter lines containing 'bot' (case-insensitive) and pipes the output to GoAccess for analysis.

```shell
# tail -F -n +0 access.log | grep -i --line-buffered 'bot' | goaccess -
```

--------------------------------

### Crawler and Bot Classification

Source: https://goaccess.io/man/index

Options to control how crawlers and bots are handled. One option ignores all known crawlers, while another classifies unknown operating systems and browsers as crawlers to improve bot detection accuracy.

```APIDOC
--ignore-crawlers
  Ignore crawlers.

--unknowns-as-crawlers
  Classify unknown OS and browsers as crawlers. As an attempt to detect non-humans more accurately, an option to classify unknown OS and browsers and crawlers help.
```

--------------------------------

### GoAccess Date Formatting

Source: https://goaccess.io/man/index

Specifies the log format date using strftime specifiers. Requires setting LC_TIME to English locale (e.g., en_US.UTF-8) if logs contain English dates and the system locale differs. Use %f for microseconds and %* for milliseconds.

```shell
--date-format <dateformat>
```

```shell
LC_TIME="en_US.UTF-8" bash -c 'goaccess access.log --log-format=COMBINED'
```

--------------------------------

### GoAccess WebSocket JWT Authentication Flow

Source: https://goaccess.io/man/index

Details the JSON structures for successful and failed initial JWT authentication requests, as well as the format for token refresh and validation requests sent to a specified URL.

```APIDOC
GoAccess WebSocket JWT Authentication:

**Initial Authentication (Successful Response)**

This is the expected JSON format for a successful GET request to the `--ws-auth-url` endpoint.

```json
{
  "status": "success",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "csrf_token": "3RRjNeR4RTXHmrV1cECkyUmmKeRxm4lzkI0eq41o",
  "refresh_token": "refresh123xyz",
  "expires_in": 3600
}
```

- `status`: Indicates the authentication status, "success" for valid credentials.
- `access_token`: The JWT access token for WebSocket connections.
- `csrf_token`: A token used for CSRF protection in stateful authentication.
- `refresh_token`: A token used to obtain new access tokens.
- `expires_in`: The lifetime of the access token in seconds.

**Initial Authentication (Failed Response)**

This is the expected JSON format for a failed GET request to the `--ws-auth-url` endpoint.

```json
{
  "status": "error",
  "message": "User not authenticated"
}
```

- `status`: Indicates the authentication status, "error" for invalid credentials.
- `message`: A human-readable error message.

**Token Refresh Request**

GoAccess sends a POST request to the `--ws-auth-refresh-url` (or `--ws-auth-url` if not set) to refresh the JWT.

```json
{
  "refresh_token": "refresh123xyz"
}
```

- `refresh_token`: The token obtained during initial authentication.

**Periodic Token Validation Request**

After refreshing, GoAccess sends the updated JWT to the WebSocket server for validation.

```json
{
  "action": "validate_token",
  "token": "current-jwt"
}
```

- `action`: Specifies the validation action.
- `token`: The current access token to validate.
```

--------------------------------

### Filter Log by File Extension

Source: https://goaccess.io/man/index

This snippet demonstrates how to parse specific file types like HTML or PHP from an access log using awk to filter requests ending with .html, .htm, or .php, and then piping the output to GoAccess.

```shell
# awk '$7~/.html|\.htm|\.php/' access.log | goaccess -
```

--------------------------------

### Static File Request Handling

Source: https://goaccess.io/man/index

Controls how static file requests are treated. It can either ignore static requests only from valid requests or ignore them from all panels, though they will still contribute to the total request count.

```APIDOC
--ignore-statics=<req|panel>
  Ignore static file requests.

  + req = Only ignore request from valid requests
  + panel = Ignore request from panels.Note: It will count them towards the total number of requests.
```

--------------------------------

### Read Persisted Data Only

Source: https://goaccess.io/man/index

This command allows you to view previously processed and persisted GoAccess data without parsing any new log files. It uses the '--restore' flag to load the existing dataset.

```shell
# goaccess --restore
```

--------------------------------

### Check Request Field Number

Source: https://goaccess.io/man/index

This command helps identify the correct field number for the request in your access log format. It tails the last 10 lines of the log and prints the 8th field, which is often the request field when Virtual Hosts are included.

```shell
# tail -10 access.log | awk '{print $8}'
```

--------------------------------

### GoAccess Parse Options: Chunk Size

Source: https://goaccess.io/man/index

Determines the number of log lines that form a chunk for parallel processing. Affects efficiency and resource usage, with guidance on low vs. large values.

```APIDOC
--chunk-size=<256-32768>
  This determines the number of lines that form a chunk. This parameter influences the size of the data processed concurrently by each thread, allowing for parallelization of the file reading and processing tasks. The value of chunk-size affects the efficiency of the parallel processing and can be adjusted based on factors such as system resources and the characteristics of the input data.

  **Low Values:**

  If chunk-size is set too low, it might result in inefficient processing. For instance, if each chunk contains a very small number of lines, the overhead of managing and coordinating parallel processing might outweigh the benefits.

   **Large Values:**

  Conversely, if chunk-size is set too high, it could lead to resource exhaustion. Each chunk represents a portion of data that a thread processes in parallel. Setting chunk-size to an excessively large value might cause memory issues, particularly if there are many parallel threads running simultaneously.
```

--------------------------------

### GoAccess HTML Report Customization

Source: https://goaccess.io/man/index

Options to customize the generated HTML reports, including custom CSS/JS, report titles, refresh intervals, preferences, and disabling specific elements.

```APIDOC
--html-custom-css=<path.css>
  Specifies a custom CSS file path to load in the HTML report.

--html-custom-js=<path.js>
  Specifies a custom JS file path to load in the HTML report.

--html-report-title=<title>
  Set HTML report page title and header.

--html-refresh=<seconds>
  Refresh the HTML report every X seconds. Value must be between 1 and 60 seconds.

--html-prefs=<JSON>
  Set HTML report default preferences. Supply a valid JSON object containing the HTML preferences to customize each panel plot.
  Note: The JSON object must be a one-line string.
  Example:
  --html-prefs='{"theme":"bright","perPage":5,"layout":"horizontal","showTables":true,"visitors":{"plot":{"chartType":"bar"}}}'

--no-html-last-updated
  Do not show the last updated field displayed in the HTML generated report.
```
Tokens:
Raw