Man Page

Here is the main doc. All the details about GoAccess…

Name

goaccess — Fast web log analyzer and interactive viewer.

Synopsis

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

Description

goaccess is an open source, real-time web log analyzer and interactive viewer that runs in a terminal on *nix systems or directly in your browser. Designed with system administrators, DevOps engineers, and security professionals in mind, it delivers fast, actionable HTTP statistics and visual server reports on the fly. GoAccess parses your web server logs in real time and presents the data directly in the terminal or via a live HTML dashboard, making it easy to monitor traffic, detect anomalies, and troubleshoot issues instantly.

Features include the following panels:

  • General Statistics Summary of several metrics: valid/invalid requests, time taken to analyze the dataset, unique visitors, requested files, static files, HTTP referrers, 404s, size of the parsed log file and bandwidth consumption.
  • Unique Visitors Hits, unique visitors and cumulative bandwidth per date. HTTP requests containing the same IP, same date, and same user agent are considered a unique visitor. Optionally, date specificity can be set to the hour level using --date-spec=hr (e.g., 05/Jun/2016:16) or minute level (05/Jun/2016:16:59).
  • Requested Files The most highly requested non-static files, showing hits, unique visitors, percentage, cumulative bandwidth, protocol, and request method.
  • Requested Static Files Frequently requested static files such as JPG, CSS, SWF, JS, GIF, and PNG. Additional static files can be added to the configuration file.
  • 404 or Not Found All pages that were not found on the server (404 status code).
  • Hosts Detailed information on the hosts — great for spotting aggressive crawlers. Expanding the panel can display reverse DNS lookup result, country of origin and city. If -a is enabled, a list of user agents can be displayed by selecting the desired IP and pressing ENTER.
  • Operating Systems Which operating system the host used when hitting the server, with the most specific version possible.
  • Browsers Which browser the host used, with the most specific version possible.
  • Visit Times Hourly report with 24 data points. Optionally, set to tenth-of-a-minute level using --hour-spec=min.
  • Virtual Hosts All different virtual hosts parsed from the access log. Displayed if %v is used in the log-format string.
  • Referrers URLs The full URL they were referred from. Disabled by default — see --ignore-panel in your configuration file to enable it.
  • Referring Sites Only the host part of the referring URL.
  • Keyphrases Google search queries that led to your server. Currently supports Google search via HTTP only. Disabled by default — see --ignore-panel to enable.
  • Geo Location Where an IP address is geographically located, broken down by continent and country. Requires GeoLocation support at compile time.
  • HTTP Status Codes Numeric status codes to HTTP requests.
  • ASN Autonomous System Numbers data for GeoIP2 and legacy databases. Great for detecting and blocking malicious traffic.
  • Remote User (HTTP authentication) The userid of the person requesting the document as determined by HTTP authentication. Not enabled unless %e is given within the log-format variable.
  • Cache Status Whether a request is being cached and served from cache. Can be MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, or HIT. Not enabled unless %C is in log-format.
  • MIME Types Media types and subtypes. Not enabled unless %M is in log-format. See IANA MIME types.
  • Encryption Settings SSL/TLS protocol and cipher suites. Not enabled unless %K is in log-format.
Note
Optionally and if configured, all panels can display the average time taken to serve the request.

Storage

In-memory storage provides better performance at the cost of limiting the dataset size to the amount of available physical memory. GoAccess uses in-memory hash tables with very good memory usage and performance. This storage has support for on-disk persistence.

Default Hash Tables

In-memory storage provides better performance at the cost of limiting the dataset size to the amount of available physical memory. GoAccess uses in-memory hash tables. It has very good memory usage and pretty good performance. This storage has support for on-disk persistence.

Configuration

Multiple options can be used to configure GoAccess. For a complete up-to-date list of configure options, run ./configure --help.

--enable-debug
Compile with debugging symbols and turn off compiler optimizations.
--enable-asan
Enable Address Sanitizer for debugging purposes.
--enable-utf8
Compile with wide character support. Ncursesw is required.
--enable-geoip=<legacy|mmdb>
Compile with GeoLocation support. MaxMind's GeoIP is required. legacy uses the original GeoIP databases; mmdb uses the enhanced GeoIP2 databases.
--with-getline
Dynamically expands line buffer to parse full line requests instead of using a fixed 4096-byte buffer.
--with-openssl
Compile GoAccess with OpenSSL support for its WebSocket server.
--with-zlib
Enables optional zlib support to allow parsing of compressed log files (e.g., .gz) directly without manual decompression.

Options

The following options can be supplied via the command line or through the configuration file as long options.

Log / Date / Time Format

--time-format <timeformat>

Specifies the log format time containing any combination of regular characters and special format specifiers beginning with %. See man strftime. e.g., %T or %H:%M:%S.

Note
If a timestamp is given in microseconds, %f must be used as time-format. For milliseconds, use %*.
--date-format <dateformat>

Specifies the log format date containing any combination of regular characters and special format specifiers beginning with %. See man strftime.

Note
If your access log contains English dates such as 12/Jan/2021 but your locale is not English, set your LC_TIME:
# LC_TIME="en_US.UTF-8" bash -c 'goaccess access.log --log-format=COMBINED'
For microsecond timestamps use %f; for millisecond timestamps use %*.
--datetime-format <date_timeformat>

Combines date and time into a single option, with the ability to get the timezone from a request and convert it. e.g., %d/%b/%Y:%H:%M:%S %z.

Note
If --datetime-format is used, %x must be passed in the log-format variable.
Important
If --datetime-format is used, ensure --date-format and --time-format are NOT used.
--log-format <logformat>

Specifies the log format string. Followed by a space or \t for tab-delimited. In addition to raw formats, the following predefined names are available:

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
Notes
  • Generally, you need quotes around values that include white spaces, commas, pipes, quotes, and/or brackets. Inner quotes must be escaped.
  • Piping data into GoAccess won't prompt a log/date/time configuration dialog — define it in your configuration file or command line.
  • The default GoAccess format for CADDY is the 'local/info' format. See this post for custom formats.

User Interface Options

-c --config-dialog

Prompt log/date configuration window on program start.

-i --hl-header

Color highlight active panel.

-m --with-mouse

Enable mouse support on main dashboard.

--color=<fg:bg[attrs, PANEL]>

Specify custom colors for the terminal output. Syntax: DEFINITION space/tab colorFG#:colorBG# [attributes,PANEL] where FG/BG values range from -1 (default term color) to 255.

Optional attributes (comma-separated): bold, underline, normal, reverse, blink.

Custom colors can be applied per panel. Available color definitions:

  • 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_SUBBARS
  • COLOR_CHART_AXIS
  • COLOR_CHART_VALUES
  • 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

See the configuration file for a sample color scheme.

--color-scheme <1|2|3>

Choose among terminal color schemes. 1 = monochrome, 2 = green, 3 = Monokai (requires 256-color terminal).

--crawlers-only

Parse and display only crawlers/bots.

--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 (1–60). Default: 1 second.

--html-prefs=<JSON>

Set HTML report default preferences as a one-line JSON string. Example:

--html-prefs='{"theme":"bright","perPage":5,"layout":"horizontal","showTables":true,"visitors":{"plot":{"chartType":"bar"}}}'
--json-pretty-print

Format JSON output using tabs and newlines.

--max-items=<num>

Maximum number of items to display per panel (1 to n). Only static HTML, CSV, and JSON output allow more than the default of 366 items (or 50 in real-time HTML).

--no-color

Turn off colored output. Default on terminals that don't support colors.

--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-html-last-updated

Do not show the last updated field in the generated HTML report.

--no-parsing-spinner

Do not show the progress metrics and parsing spinner.

--tz=<timezone>

Output report date/time data in the given canonical timezone name, e.g., Europe/Berlin, America/Chicago, Africa/Cairo. Invalid names default to GMT. See --datetime-format to properly specify a timezone in the date/time format.

Server Options

--addr=<address>

Specify IP address to bind the server to. Default: 0.0.0.0.

--daemonize

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

--user-name=<username>

Run GoAccess as the specified user.

Note
Ensure the user can access all input/output files needed. Other groups the user belongs to will be ignored. It's advised to run GoAccess behind an SSL proxy as this user is unlikely to access SSL certificates.
--origin=<url>

Ensure clients send the specified origin header upon WebSocket handshake. e.g., --origin=http://goaccess.io

--pid-file=<path/goaccess.pid>

Write the daemon PID to a file when used with --daemonize.

--port=<port>

Specify the WebSocket server port. Default: 7890. Ensure this port is open.

--real-time-html

Enable real-time HTML output.

--unix-socket=<addr>

Specify UNIX-domain socket address to bind the server to.

--ws-auth=<jwt[:secret]> | jwt:verify:secret

Enable WebSocket authentication using a JSON Web Token (JWT). Two formats are supported:

--ws-auth=jwt[:secret] # Local JWT (static or env variable secret) --ws-auth=jwt:verify:secret # External JWT verification with a provided secret

When using jwt[:secret], GoAccess generates a JWT locally. If only jwt is given, the secret is read from the GOACCESS_WSAUTH_SECRET environment variable. A secret can be provided directly or as a file path.

When using jwt:verify:secret, GoAccess verifies an externally fetched JWT (e.g., via --ws-auth-url). The secret can be a direct key, file path, or environment variable name.

When this option is used, the HTML report will only display if authentication succeeds.

Important
Requires GoAccess to be built with --with-openssl.
--ws-auth-expire=<secs>

Set JWT expiry time. Default: 8 hours (28800 seconds). Supported formats:

"3600" → 3600 seconds "120s" → 2 minutes "24h" → 24 hours = 86,400 seconds "10m" → 10 minutes = 600 seconds "10d" → 10 days = 864,000 seconds
--ws-auth-url=<url>

URL where GoAccess fetches the initial JWT via a GET request. The JSON response must contain status, access_token, refresh_token, and expires_in fields. Uses credentials: 'include' for secure token retrieval based on the user's existing session.

--ws-auth-refresh-url=<url>

URL where GoAccess fetches a new JWT when the current one is about to expire. GoAccess proactively refreshes 60 seconds before expiration via a POST with the refresh_token. Defaults to --ws-auth-url if not set.

WebSocket Authentication Flow

GoAccess supports both stateless and stateful authentication approaches. The stateful approach issues JWTs along with a csrf_token stored in the session; refresh requests then perform a CSRF check via the X-CSRF-TOKEN header.

Initial auth response format:

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

On failure:

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

After refreshing, GoAccess confirms the updated JWT's validity by sending {"action": "validate_token", "token": "current-jwt"} to the WebSocket server.

Important
These options require --ws-auth=jwt:verify:<secret> where <secret> can be a file path, environment variable, or HS256 secret string.
--ws-url=<[scheme://]url[:port]>

URL to which the WebSocket server responds. Optionally specify the scheme (ws:// or wss://). e.g., wss://goaccess.io or goaccess.io:9999 to connect behind a proxy on a custom port.

--ping-interval=<secs>

Enable WebSocket ping with specified interval in seconds, to prevent idle connections from being disconnected.

--fifo-in=<path/file>

Creates a named pipe (FIFO) that reads from the given path/file.

--fifo-out=<path/file>

Creates a named pipe (FIFO) that writes to the given path/file.

--ssl-cert=<path/cert.crt>

Path to TLS/SSL certificate. Both --ssl-cert and --ssl-key are required to enable TLS/SSL support. Only available if configured with --with-openssl.

--ssl-key=<path/priv.key>

Path to TLS/SSL private key. Both --ssl-cert and --ssl-key are required. Only available if configured with --with-openssl.

File Options

-

Read the log file from stdin.

-f --log-file=<logfile>

Specify the path to the input log file. If set in the config file, it will take priority over -f from the command line.

-l --debug-file=<filename>

Send all debug messages to the specified file. Requires --enable-debug at compile time.

-p --config-file=<configfile>

Specify a custom configuration file to use. Takes priority over the global configuration file.

--invalid-requests=<filename>

Log invalid requests to the specified file.

--external-assets

Output HTML assets to external JS/CSS files (goaccess.js and goaccess.css) in the same directory as your report. Great for Content Security Policy (CSP) setups.

--unknowns-log=<filename>

Log unknown browsers and OSes to the specified file.

--no-global-config

Do not load the global configuration file (normally under /etc/, /usr/etc/, or /usr/local/etc/).

Parse Options

-a --agent-list

Enable a list of user-agents by host. Disable for faster parsing.

-d --with-output-resolver

Enable IP resolver on the HTML or JSON output.

-e --exclude-ip <IP|IP-range>

Exclude an IPv4 or IPv6 from being counted. Ranges supported with a dash between IPs (start-end). e.g.:

  • exclude-ip 127.0.0.1
  • exclude-ip 192.168.0.1-192.168.0.100
  • exclude-ip ::1
  • exclude-ip 0:0:0:0:0:ffff:808:804-0:0:0:0:0:ffff:808:808
-j --jobs=<1-6>

Number of parallel processing threads. Defaults to 1. Set based on available CPU cores. See --chunk-size.

-H --http-protocol=<yes|no>

Set/unset HTTP request protocol. Creates a request key containing the request protocol + the actual request.

-M --http-method=<yes|no>

Set/unset HTTP request method. Creates a request key containing the request method + the actual request.

-o --output=<json|csv|html>

Write output to stdout given one of the following extensions: .csv, .json, or .html. Multiple outputs can be generated in a single run, e.g., --output /path/to/report.html --output /path/to/report.json.

-q --no-query-string

Ignore request's query string. e.g., www.google.com/page.htm?query → www.google.com/page.htm. Can greatly decrease memory consumption on timestamped requests.

-r --no-term-resolver

Disable IP resolver on terminal output.

--444-as-404

Treat non-standard status code 444 as 404.

--4xx-to-unique-count

Add 4xx client errors to the unique visitors count.

--anonymize-ip

Anonymize the client IP address. Sets the last octet of IPv4 and last 80 bits of IPv6 to zeros:

192.168.20.100 → 192.168.20.0 2a03:2880:2110:df07:face:b00c::1 → 2a03:2880:2110:df07::
--anonymize-level=<1|2|3>

Anonymization levels: 1 = default, 2 = strong, 3 = pedantic.

┌------------┬---------┬---------┬---------┐ │Bits-hidden │ Level 1 │ Level 2 │ Level 3 │ ├------------┼---------┼---------┼---------┤ │IPv4 │ 8 │ 16 │ 24 │ ├------------┼---------┼---------┼---------┤ │IPv6 │ 64 │ 80 │ 96 │ └------------┴---------┴---------┴---------┘
--chunk-size=<256-32768>

Number of lines forming a chunk for parallel processing. Influences the efficiency of multi-threaded parsing.

Notes
  • Low values: Too-small chunks increase coordination overhead, potentially outweighing parallelization benefits.
  • Large values: Too-large chunks may cause memory issues when many parallel threads run simultaneously.
--all-static-files

Include static files that contain a query string.

--browsers-file=<path>

Include an additional tab-delimited list of browsers/crawlers/feeds. See config/browsers.list. Note: the larger the list, the longer parsing will take.

--date-spec=<date|hr|min>

Set date specificity: date (default), hr to append hours (e.g., 18/Dec/2010:19), or min to append minutes (e.g., 18/Dec/2010:19:59).

--double-decode

Decode double-encoded values including user-agent, request, and referrer.

--enable-panel=<PANEL>

Enable parsing/displaying the given panel.

  • 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
--fname-as-vhost=<regex>

Use log filename(s) as virtual host(s). POSIX regex extracts the vhost from the filename. e.g., --fname-as-vhost='[a-z]*.[a-z]*' extracts awesome.com from awesome.com.log.

--hide-referrer=<NEEDLE>

Hide a referrer but still count it. Wildcards are allowed (e.g., *.bing.com).

--hour-spec=<hour|min>

Set time specificity to hour (default) or min to display the tenth of an hour. Used in the time distribution panel.

--ignore-crawlers

Ignore crawlers.

--unknowns-as-crawlers

Classify unknown OS and browsers as crawlers for more accurate non-human detection.

--ignore-panel=<PANEL>

Ignore parsing/displaying the given panel. Same panel names as --enable-panel.

--ignore-referrer=<referrer>

Ignore referrers from being counted. Wildcards allowed. e.g., *.domain.com, ww?.domain.*

--ignore-statics=<req|panel>

Ignore static file requests. req = only ignore from valid requests count; panel = ignore from panels. Note: they are still counted towards the total number of requests.

--ignore-status=<STATUS>

Ignore parsing and displaying one or multiple status codes. Use this option multiple times for multiple codes.

--keep-last=<ndays>

Keep the last specified number of days in storage, recycling older data. e.g., --keep-last=7 shows only the last 7 days.

--no-ip-validation

Disable client IP validation. Useful when IP addresses have been obfuscated before logging. The log still needs a placeholder for %h.

--no-strict-status

Disable HTTP status code validation. Some servers record - if a connection was not fully established.

--num-tests=<number>

Number of lines to test against the log/date/time format. Default: 10. Set to 0 to skip testing and parse the entire log without validation strictness.

--process-and-exit

Parse log and exit without outputting data. Useful for adding data to the on-disk database only.

--real-os

Display real OS names, e.g., Windows XP, Snow Leopard.

--sort-panel=<PANEL,FIELD,ORDER>

Sort panel on initial load. Format: PANEL,METRIC,ORDER.

Metrics:

  • BY_HITS
  • BY_VISITORS
  • BY_DATA
  • BY_BW
  • BY_AVGTS
  • BY_CUMTS
  • BY_MAXTS
  • BY_PROT
  • BY_MTHD

Orders: ASC, DESC

--static-file=<extension>

Add a static file extension. e.g., .mp3. Extensions are case-sensitive.

GeoLocation Options

GeoIP Legacy

Legacy GeoIP has been discontinued. Make sure to download the .dat files. Distributed with Creative Commons Attribution-ShareAlike 4.0.

# Download GeoIP.dat.gz → gunzip GeoIP.dat.gz (IPv4 Country) # Download GeoIPCity.dat.gz → gunzip GeoIPCity.dat.gz (IPv4 City)
-g --std-geoip

Standard GeoIP database for less memory usage.

GeoIP2

For GeoIP2 databases, use DB-IP Lite (licensed Creative Commons Attribution 4.0) or MaxMind (GeoLite2).

# Download GeoLite2-City.mmdb.gz → gunzip GeoLite2-City.mmdb.gz # Download GeoLite2-Country.mmdb.gz → gunzip GeoLite2-Country.mmdb.gz
--geoip-database=<geocityfile>

Specify path to GeoIP database file. --geoip-city-data is an alias. Can be specified multiple times for multiple databases:

geoip-database /mmdb/dbip-asn-lite-2024-04.mmdb geoip-database /mmdb/dbip-city-lite-2024-01.mmdb
Note
Cities are only shown in the hosts panel (per host).

Other Options

-h --help

Display help and exit.

-V --version

Display version information and exit.

-s --storage

Display current storage method (e.g., B+ Tree, Hash).

--dcf

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

Persistence Storage Options

--persist

Persist parsed data to disk. Existing database files will be overwritten. Should be set for the first dataset. See examples below.

--restore

Load previously stored data from disk. Database files must exist. See --persist and examples below.

--db-path <dir>

Path where on-disk database files are stored. Default: /tmp.

Custom Log / Date Format

GoAccess can parse virtually any web log format. Predefined options include Common Log Format (CLF), Combined Log Format (XLF/ELF), W3C (IIS), and Amazon CloudFront. Custom format strings are also fully supported.

Run GoAccess with -c to prompt a configuration window, or specify the format permanently in the configuration file at %sysconfdir%/goaccess.conf or ~/.goaccessrc (where %sysconfdir% is /etc/, /usr/etc/, or /usr/local/etc/).

time-format — specifies the log-format time. See man strftime. e.g., %T or %H:%M:%S. Use %f for microseconds, %* for milliseconds.

date-format — specifies the log-format date. See man strftime. Use %f for microseconds, %* for milliseconds.

log-format — the log format string, followed by a space or \t for tab-delimited.

Specifiers

  • %x Date and time field matching time-format and date-format. Used when a combined timestamp is given.
  • %t Time field matching the time-format variable.
  • %d Date field matching the date-format variable.
  • %v The server name according to the canonical name setting (Server Blocks or Virtual Host).
  • %e Userid of the person requesting the document as determined by HTTP authentication.
  • %C The cache status of the object the server served.
  • %h Host — the client IP address (IPv4 or IPv6).
  • %r The full request line from the client. Requires delimiters (quotes, etc.) to be parsable. Use either %r or the combination of %m, %U, %q, and %H — not both.
  • %m The request method.
  • %U The URL path requested. If the query string is in %U, %q is not needed.
  • %q The query string.
  • %H The request protocol.
  • %s The status code the server sends back to the client.
  • %b The size of the object returned to the client.
  • %R The "Referer" HTTP request header.
  • %u The user-agent HTTP request header.
  • %K TLS protocol used. (Apache: %{SSL_PROTOCOL}x)
  • %k TLS cipher suite. (Apache: %{SSL_CIPHER}x)
  • %M MIME-type of the requested resource. (Apache: %{Content-Type}o)
  • %D Time taken to serve the request, in microseconds.
  • %T Time taken to serve the request, in seconds with millisecond resolution.
  • %L Time taken to serve the request, in milliseconds as a decimal number.
  • %n Time taken to serve the request, in nanoseconds as a decimal number.
  • %^ Ignore this field.
  • %~ Move forward through the log string until a non-space character is found.
  • ~h The client IP address in an X-Forwarded-For (XFF) field.
XFF Specifier
GoAccess uses a tilde before the host specifier followed by the delimiter in curly braces. e.g., "~h{, }" parses "11.25.11.53, 17.68.33.17".
┌-------------------------------------------------┐ │XFF field │ specifier │ ├--------------------------------------┼-----------┤ │"192.1.2.3, 192.68.33.17, 192.1.1.2" │ "~h{, }" │ ├--------------------------------------┼-----------┤ │"192.1.2.12", "192.68.33.17" │ ~h{", } │ ├--------------------------------------┼-----------┤ │192.1.2.12, 192.68.33.17 │ ~h{, } │ ├--------------------------------------┼-----------┤ │192.1.2.14 192.68.33.17 192.1.1.2 │ ~h{ } │ └-------------------------------------------------┘
Note
To get average, cumulative and maximum time served, start logging response times in your web server. In Nginx add $request_time; in Apache use %D.
Important
If multiple time-served specifiers or hosts are used simultaneously, the first one specified in the format string takes priority.

GoAccess requires the following fields: a valid IPv4/6 %h, a valid date %d, and the request %r.

Interactive Keys

  • 1-9, 0 Jump to panel by position (1st–10th)
  • TAB Forward module
  • SHIFT+TAB Backward module
  • g Move to the top/beginning of screen
  • G Move to the bottom/end of screen
  • j Scroll down within expanded module
  • k Scroll up within expanded module
  • ^f Page down inside expanded module
  • ^b Page up inside expanded module
  • ENTER Expand module
  • o/O Expand selected module
  • + Expand selected item children
  • - Collapse selected item children
  • s Sort options for current module
  • p Reorder panels
  • / Search across all modules (regex allowed)
  • n Find next occurrence
  • m/M Cycle through chart metrics (forward/backward)
  • l/L Toggle logarithmic scale for current panel
  • r/R Toggle reverse chronological order in charts
  • c Set/change color scheme
  • q Quit (or collapse if inside module)
  • ? Open help

Examples

Different Outputs

Interactive terminal report:

# goaccess access.log

Generate an HTML report:

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

Generate a JSON report:

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

Generate a CSV file:

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

Monitor logs in real-time from stdin:

# tail -f access.log | goaccess -

Filter by pattern while keeping the pipe open:

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

Parse from the beginning while filtering:

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

Convert log date timezone to Europe/Berlin:

# 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

Multiple Log Files

# goaccess access.log access.log.1

Parse from a pipe while also reading regular files (append - for stdin):

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

process all compressed log files plus the current log:

# zcat access.log.*.gz | goaccess access.log -
Note
if goaccess was built with --with-zlib, it can parse .gz files directly without external decompression, e.g.:
# goaccess access.log access.log.1.gz access.log.2.gz
otherwise, use zcat (or gunzip -c on macos) to decompress logs before piping them into goaccess.

real-time html output

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

specify the websocket url explicitly:

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

custom port:

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

bind websocket to a specific address:

# goaccess access.log -o report.html --real-time-html --addr=127.0.0.1
Note
For TLS/SSL real-time output, use --ssl-cert=<cert.crt> and --ssl-key=<priv.key>.
If GoAccess is running behind a reverse proxy, set the WebSocket URL to include the proxy path and port, e.g., --ws-url=goaccess.io:8080/ws.

working with dates

all requests from a specific date to end of file:

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

using a relative date (one week ago):

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

parse a specific date range:

# sed -n '/5\/nov\/2010/,/5\/dec\/2010/ p' access.log | goaccess -a -

keep only the last 5 days of data:

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

virtual hosts

Use --concat-vhost-req to prepend the virtual host or server block (%v) to the request field.

Append virtual host to the request field manually:

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

Exclude a list of virtual hosts:

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

files, status codes & bots

parse only specific page types:

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

parse page views without extensions:

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

Filter by status code (e.g., 500):

# awk '$9~/500/' access.log | goaccess -

Multiple status codes:

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

Estimated bot traffic:

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

Server

Run at lower CPU priority:

# nice -n 19 goaccess access.log -a

Pipe from a remote server:

# ssh -n root@server 'tail -f /var/log/apache2/access.log' | goaccess -
Note
SSH requires -n so GoAccess can read from stdin. Use SSH keys for authentication.

Processing Logs Incrementally

GoAccess can process logs incrementally by persisting data to disk, then restoring it and appending new data. GoAccess tracks inodes, the last line parsed, and the last timestamp per file.

Note
If the inode doesn't match, all lines are parsed. If it matches, remaining lines are read and the count/timestamp updated. Log lines with a timestamp ≤ the stored timestamp are skipped. Piped data works off the timestamp of the last line read.
Important
Piped data may produce duplicate entries since multiple consecutive lines can share the same timestamp. Best practice is to parse directly with GoAccess rather than piping for incremental processing.

Persist last month's log:

# goaccess access.log.1 --persist

Append this month's log and preserve:

# goaccess access.log --restore --persist

Read persisted data only:

# goaccess --restore

Notes

Each active panel displays up to 366 items (or 50 in the real-time HTML report). This is customizable with --max-items, though only static HTML, CSV, and JSON output support values greater than 366.

A hit is a request (one line in the access log). HTTP requests with the same IP, date, and user agent are considered a unique visit.

For dual-stack support, use --addr=:: instead of the default --addr=0.0.0.0.

The generated report will attempt to reconnect to the WebSocket server after 1 second with exponential backoff, up to 20 attempts.

Bugs

If you think you have found a bug, please send an email to GoAccess' email.

Author

Gerardo Orellana. For more details or new releases, visit goaccess.io.