README: Administration Essentials

Please visit our new Help Center for the current version of this article:
https://help.angelfishstats.com/helpdesk/KB/View/46517665-admin-essentials

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 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.

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

Profiles

• 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

Datasources

• 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

• 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!