README: Administration Essentials

Please visit our new Help Center for the current version of this article:

This document is a reference for Angelfish administrators. If you're new to Angelfish, we recommend taking a few minutes to familiarize yourself with the concepts listed on this page.

Angelfish is a lot more fun to use once you understand how it works!

The Basics

  • Angelfish is on-premises web analytics software that can track any of your websites or web-based applications.
  • Angelfish is entirely self-contained: it uses an embedded database & web server.
  • You can install Angelfish on any 64-bit Windows or Linux instance: server, virtual machine, cloud container, or desktop/laptop.
  • Angelfish doesn't need to be installed directly on your web server. It can be installed anywhere, as long as it's able to access your web server log files.
  • Angelfish processes these log files and stores the important bits in an internal database.
  • When someone accesses the reports, the report data is loaded from the internal database.
  • Angelfish can generate reports from JavaScript page tags or by analyzing the existing data in your log files.

More Information:

System & Hardware Requirements
Installation Instructions (Windows)
Installation Instructions (Linux)
Angelfish Definitions

Accessing Angelfish

  • You access the Angelfish interface via a web browser. The default username / password is admin / Angelfish123
  • Angelfish uses port 9000 by default, e.g. http://localhost:9000 or
  • You can change the port Angelfish uses in agf.conf (restart required). 
  • On Linux systems, ports lower than 1024 are reserved by the OS and are unvailable for Angelfish.
  • Windows systems can use any port that isn't already in use.
  • The Angelfish interface supports SSL - it must be enabled in agf.conf.
  • You can force Angelfish to only respond to a certain IP address. Again, this is configured in agf.conf.

More Information:

First Login and Changing the Admin Password
Activate SSL for the Angelfish Webserver

Data Processing & Storage

  • By default, all configuration and report data is stored in the data folder under the root Angelfish folder.  e.g. C:\Angelfish\data\
  • You can move the Angelfish data folder to another location by editing agf.conf and copying the folder. Full instructions are linked below.
  • The report data files are stored in a folder for each profile ID: ../data/<profile-id>/
  • Each profile's data folder contains 2 data files: agfs-vs.db and agfs-it.db
  • The agfs-vs.db file contains visit-level data, shown in the Traffic / Content / Dashboards sections. (visitors, visits, pageviews, goals, marketing variables, etc.)
  • The agfs-it.db file contains hit-level data, shown in the IT Reports section.
  • Two processes are spawned during data processing: one process is mapped to each db file.
  • Data can't be edited after it's written to the db files. However, you can delete data for a date range, edit the profile, and reprocess the logs for the date range.
  • You can't open the db files directly - please use the API to view data in the db files.

More Information:

Moving the Data Directory
API Overview
How To Optimize Angelfish Performance


  • A Profile contains the config settings and the report data for a website, and is the basic licensing element for Angelfish.
  • Typically, you will use one Profile for each website or subsite you want to track.
  • Angelfish installs a "Sample Profile" with every version - it contains config examples and two month's worth of report data. You can keep it or delete it.
  • When you create a Profile, you must specify the Tracking Method the Profile will use.
  • The tracking methods in Angelfish are JavaScript-based (AGF and UGA) or log-based (SID, USR, IPUA, and IP).
  • JavaScript-based tracking methods require tracking code on each page of your site, and generate one tracking request for each pageview.
  • Log-based tracking methods require you to specify the file types to count as pageviews.
  • The Hostname(s) field is used to differentiate between internal and external referrals - this is important for log-based tracking methods, and for the Broken Links and Stolen Bandwidth reports.
  • Query Parameters are disabled by default, but you can specify a list of query fields to include / exclude on the Settings tab of the profile's config.
  • To see all query parameters, use the Exclude option with an empty field (i.e. exclude nothing).
  • After you create a Profile, you must process data in order for the reports to be populated.
  • In order to process data, a Profile needs at least one Datasource. Filters are not required but are highly recommended.
  • If you want to add a Filter or Datasource to a Profile, the Profile, Datasource, and Filter must be in the same Profile Group.
  • Data processing can be scheduled for each Profile. Options are hourly / daily / weekly / monthly / never. 
  • A Profile's processing schedule should match the web server log rotation, e.g. daily processing for daily log rotation.
  • For large environments, you can create Profiles / Filters / Datasources via provisioning.
  • If you need more Profiles, you can purchase more to add your Angelfish instance.

More Information:

Profiles Overview
Tracking Methods Overview


  • A Datasource contains the settings, filename(s), and location of log files to be processed. 
  • A Profile can have one or more Datasources, and single Datasource can be used by many Profiles. 
  • SharePoint customers should create a Datasource for each WFE (Web Front End)
  • A Datasource can reference logs on the local server, or on a remote server via SFTP, FTP, or a UNC path.
  • If you use Angelfish on Linux, your Datasources can access UNC paths if smbclient is installed.
  • Each Datasource uses a defined log format (i.e. the name and order of fields in the log file). IIS logs use the W3C format, Apache logs usually use NCSA or CLF.
  • Open a support ticket if you need help - we can usually figure out the log format by looking at a few lines from your log file.
  • Angelfish is easier to administer when the filename contains a date stamp (e.g. u_ex150725). IIS does this by default, but Apache must be configured to do this.
  • We recommend using Date Substitution in the Datasource's Location field - it makes Angelfish look for each new daily log.
  • Once a log file has been processed, Angelfish "remembers" the log file has been processed. This feature is called Log Tracking and it's enabled by default.
  • Datasources (and Filters) are easier to work with once you learn basic RegEx - it's easy!

More Information:

Datasources Overview
Date Substitution and Wildcards in Datasources
Basic RegEx: Regular Expressions


  • Filters are applied during processing and allow you to edit or ignore data before it is written to the report data files.
  • If you add a filter to a profile or change an existing filter, it will not be applied to your existing report data.
  • You must delete data and reprocess in order for a new filter to be applied to your report data.
  • Angelfish includes a handful of predefined filters - you can use / edit / delete them as you see fit.
  • You can assign the order in which filters are applied in the Filters tab of each Profile. However...Raw filter types are processed before any other filter types.
  • Raw filters are the only filter types that affects hit-level data (i.e. reports in the IT Reports section).
  • Sample filter ideas: only show traffic in a subdirectory, remove the Windows domain from a username, exclude traffic from internal employees.
  • Filters are easier to work with once you learn basic RegEx - it's easy!

More Information:

Filters Overview
Basic RegEx: Regular Expressions

Tips and Tricks

  • Tooltips are everywhere - look for the small gray circles with a question mark. Tooltips are clickable and contain brief explanations of concepts.
  • Use the Admin Notes field to add a brief explanation for any Profile / Filter / Datasource. You can also use tags to categorize any Profile / Filter / Datasource.
  • You can double-click Datasources & Filters to move them from the Available column to the Selected column. You can also shift-doubleclick to select and move a list.
  • It's a good idea to save your web logs - you can always recreate or fix your data if you have the logs.
  • Logs don't use much storage when compressed, and Angelfish reads compressed logs. Supported formats: zip / gzip / bzip2
  • If you use the AGF tracking method, you can centralize gif collection or track hosted applications like SharePoint Online or SalesForce.  Just use the tracking_host variable in angelfish.js to send the tracking gif to a single location. 
  • Angelfish reports are the most useful when they're configured correctly. If you have questions about how to do this, Open a Support Ticket!


Was this article helpful?
0 out of 0 found this helpful


Article is closed for comments.