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!
- 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.
System & Hardware Requirements
Installation Instructions (Windows)
Installation Instructions (Linux)
- 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 http://192.168.5.33:9000
- 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.
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.
Moving the Data Directory
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.
- 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.
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!
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!
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!