Documentation: Chapter 4
Report Parameters

---

FlashStats is a CGI program and is accessed via an HTML form on a web page. This chapter lists all of the available FlashStats parameters that can be specified in the form. Some parameters can also be specified in the FlashStats configuration file. The description of each parameter will tell you if the parameter can be included in the user account definition (in the configuration file) or in the report request form (in an html file), or both.

Creating A Report Request Form

---

A sample HTML file (index.htm on Windows, index.html on UNIX, stats.html on Mac) has been provided to enable you to quickly create a report request form used to run FlashStats. If you edit this file you will notice HTML comments letting you know where to change the file to customize the report to your site. You're welcome to take out reports that you don't want to see or perhaps you don't want your customers to see. Or you might want to turn off or on some reports by default. You don't have to specify all of the FlashStats fields on the form for the reports to be run. Unspecified fields will use default values or be overridden with configuration information from the FlashStats configuration file.

When you've finished updating the HTML file containing the FlashStats Report Request form make sure that it is accessible on your webserver and you can run your first FlashStats report!

Helpful hint:
While only one form need be created, it may be helpful to create multiple forms for multiple users. This will enable you to create default values for multiple users that will enable them to access only the information relevant to their site.

The sample HTML provided also includes JavaScript to set the date range of the report to the current day each time you access the report page. To take advantage of this you need to view the report page in a web browser that is JavaScript capable such as Netscape 2.x and above or Internet Explorer 3.x and above.

Specifying Parameters

---

Most parameters are specified via checkboxes and text fields in an HTML form. In the HTML form, use <input> fields to specify parameters: put the parameter name into the name= part of an input field, and put the value of the parameter into the value= part of the field.

For example, if you wanted to use a checkbox to turn on and off the "Top URLs Requested" report, you would set the name= to the FlashStats parameter "requests" and set the value= to "1". In an HTML <form> tag it would look like this:

  <input type="checkbox" name="requests" value="1" CHECKED>Top URLs Requested
  

The result would look like this:

Top URLs Requested

The word "CHECKED" causes the checkbox to be checked automatically. If the checkbox is unchecked then the parameter will not be sent to FlashStats, and therefore the report won't be generated. If the checkbox is checked, then the parameter "requests" will be sent to FlashStats with a value of "1", and therefore the report will be generated. See the sample HTML file included with the FlashStats distribution for more examples of how to specify parameters in an HTML form.

FlashStats Parameters

---

The following are parameters that FlashStats recognizes. Most of these are normally specified in an HTML form used to run FlashStats reports but some of them can also be specified in the user account definition in the FlashStats configuration file (see the User Accounts section of Chapter 3).

AccessLog

The AccessLog parameter is the filename of the current (ie, today's) access log file. Specify the full path and filename. Each brand of web server names the log file differently; common log filenames are "access.log" for Windows 95 and Windows NT platforms, and "access_log" for Unix platforms. If you are unsure of the name used by your web server, consult the web server's documentation. The AccessLog parameter can only be specified in the FlashStats configuration file on a user account definition line. This parameter works in conjunction with the Logs parameter. Use the Logs parameter to specify all rotated (archived) log files. If the path and filename pattern used in the Logs parameter also match the path and filename for the current log file, then you can omit the AccessLog parameter. However, if the current log file is in a different directory or has a very different filename, then you will need to use the AccessLog parameter to specify the full path and filename of the current log file. For example, if your FlashStats configuration file had the following two parameters on the same user account definition line: logs=C:\Program Files\WebSite\logs\access.* accesslog=C:\Program Files\WebSite\logs\access.log then you could omit the AccessLog parameter, since it specifies a file which is also matched by the Logs parameter. However, if your FlashStats configuration file had the following two parameters on the same user account definition line: logs=C:\Program Files\Netscape\Server\oldlogs\access.* accesslog=C:\Program Files\Netscape\Server\httpd-hostname\logs\access then you would need to keep the AccessLog parameter, since it specifies a file which is not matched by the Logs parameter. Note that when using Microsoft IIS or PWS log files, the AccessLog parameter is usually omitted, since the Logs parameter should also match the current log path and filename. Syntax example: AccessLog=C:\Program Files\WebSite\logs\access.log

AuthRealm

If your log file contains hits for many different log sites, you can use the AuthRealm parameter to instruct FlashStats to only analyze hits made to a particular web server. The web server must log a unique piece of data for different web server, usually that web server's IP address or host name. For example, if you are using Microsoft Internet Information Server to host several different web sites, each of which has their own IP address, you can specify the parameter AuthRealm=1.2.3.4 and only requests made to the web server running at IP address 1.2.3.4 will be counted. The most common way to use the AuthRealm parameter is to include it in a user account definition line in the FlashStats configuration file. Add the AuthRealm parameter to each user account definition, using a different IP address for each user account to match the web server for that user account. The AuthRealm parameter can also be specified by a field in the report request form, but a value in the configuration file will always take precedence. If no AuthRealm parameter is specified, then FlashStats will not filter by authenticated realm, thus effectively including all realms and web servers. You can also use the AuthUser parameter to filter by authenticated user. Syntax example: AuthRealm=1.2.3.4

AuthUser

You can use the AuthUser parameter to instruct FlashStats to only analyze requests made by a specific authenticated user. Of course, the web server must support user authentication, and log the authenticated user name to the log file. (The standard type of user authentication is called "basic" authentication; Microsoft Internet Explorer also provides an NT Domain-based authentication scheme.) If you specify the AuthUser parameter on a user account definition line in the FlashStats configuration file, then any reports run under that user account will only include hits made by the specified authenticated user. The AuthUser parameter can also be specified by a field in the report request form, but a value in the configuration file will always take precedence. If no AuthUser parameter is specified, then FlashStats will not filter by authenticated user, thus effectively including all users (authenticated or not). You can also use the AuthRealm parameter to filter by authenticated realm. Syntax example: AuthUser=admin

BadReferrers

If set to "1" the Bad Referrers report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the badreferrers_top and badreferrers_greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

BadReferrers_Greater

This value specifies that bad referrers with hits greater or equal to this value will be displayed in the Bad Referrers report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

BadReferrers_Top

This value specifies the maximum number of bad referrers to display within the Bad Referrers report. A value of zero displays all bad referrers. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

BadUrls

If set to "1" the Bad URLs report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the badurls_top and badurls_greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

BadUrls_Greater

This value specifies that bad URLs with hits greater or equal to this value will be displayed in the Bad URLs report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

BadUrls_Top

This value specifies the maximum number of bad URLs to display within the Bad URLs report. A value of zero displays all bad URLs. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

BadUrl_Referrers

If set to "1" the Bad URLs report will list the referrers for each bad URL; otherwise, FlashStats will not show the referrers for each bad URL. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Browsers

If set to "1" the Most Common Browsers report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the browsers_top and browsers_greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

Browsers_Greater

This value specifies that browsers with hits greater or equal to this value will be displayed in the Most Common Browsers report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Browsers_Top

This value specifies the maximum number of browsers to display within the Most Common Browsers report. A value of zero displays all browsers. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

DailyTotals

If set to "1" the Daily Totals report will be generated. Otherwise, FlashStats will not create this report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Date

This parameter specifies the range of days to be analyzed by the report, separated by a comma. The dates should be in the MMDDYY,MMDDYY format, where the first date is the start date and the second date is the ending date. Each date must be 6 digits. Alternatively, you may specify the date range with the sm, sd, sy, em, ed, ey parameters. If you provide all six of those parameters, then the date parameter is not needed and will be ignored. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

DateFormat

This parameter specifies the format of dates within your log files, and how dates should be formatted in the reports that FlashStats generates. For users in the United States, the default of MDY will work fine. The most common non-U.S. format is DMY. When specified in the configuration file on a line all by itself, this parameter applies to all user accounts. If necessary, an individual user account can be overridden with a different value by including a DateFormat= parameter in the user account definition line. This usually isn't necessary. The possible valid values are DMY, DYM, MDY, MYD, YDM, and YMD. This parameter may be specified in either the configuration file or in a form. It is usually defined in the configuration file.

Domains

If set to "1" the User Domain Analysis report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the domains_top and domains_greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

Domains_Greater

This value specifies that domains with hits greater or equal to this value will be displayed in the User Domain Analysis report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Domains_Top

This value specifies the maximum number of domains to display within the User Domain Analysis report. A value of zero displays all domains. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

DomainTypes

If set to "1" the Types Of Domains report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the domaintypes_top and domaintypes_greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

DomainTypes_Greater

This value specifies that domain types with hits greater or equal to this value will be displayed in the Types Of Domains report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

DomainTypes_Top

This value specifies the maximum number of domain types to display within the Types Of Domains report. A value of zero displays all domain types. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Em, Ed, Ey

These three parameters are the ending month, day and year of the log files to analyze. The year must be two digits (e.g., 97). This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

ExtraFooter

You can use this parameter to specify some extra HTML code which will be output at the end of the FlashStats report. ISPs tend to use this capability to customize their installation of FlashStats. This parameter may be specified in either the configuration file or in a form. It is usually defined in the configuration file. Example: ExtraFooter=<a href="/">Home Page</a>

ExtraHeader

You can use this parameter to specify some extra HTML code which will be output at the top of the FlashStats report. ISPs tend to use this capability to customize their installation of FlashStats. This parameter may be specified in either the configuration file or in a form. It is usually defined in the configuration file. Example: ExtraHeader=<img src="/images/isplogo.gif">

Filter_Domains

List all domain names and IP's which need to be filtered out of the report results. Any hits coming from the specified domains will be ignored. Do not use any spaces, and use a comma to separate each entry. This parameter is typically used to specify internal addresses so that your reports show only external hits to your site. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. This string also may be used to filter out referrers from the Top Referrers To Your Site report. If you set the parameter filterreferrers to "1" then the filter string will be used to filter the referrers. This is useful for filtering out referrals from within your site so that you see only referrers from outside your site. Example: filter_domains=mydomain.com,myotherdomain.com,204.182.161

Filter_FileTypes

Use this field to provide a list of file types (i.e., filename extensions) which should be filtered out of the report results. Any requests for files with a specified extension will be ignored. Do not use any spaces, and use a comma to separate each entry. Each extension can begin with a period, or you can omit the period. This parameter is typically used to specify file types such as "gif,jpg,jpeg" so that you can ignore the large volume of hits to graphics files. Please note that requests for files with the specified extension will be ignored when generating reports, except for the following reports: Search Phrases Bad URLs Bad Referrers This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. Example: filter_filetypes=gif,jpg,jpeg

Filter_Referrers

This parameter works in conjunction with the filter_domains parameter. If you are generating the Top Referrers To Your Site report (i.e., referrers is set to "1") and you have set the filter_domains parameter to a list of domains to filter out, then any referrers which match the filter_domains list will not be included in the Top Referrers To Your Site report. This is very useful for when you want to see only external referrers. However, if you want to see internal referrers as well as outside referrers, then you should not set the filter_referrers parameter, so that it defaults to a value of "0". This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Find

This is where you specify the URL for FlashStats to analyze. Note that FlashStats will look for URLs that exactly match the URL that you specify here. In other words, this parameter is an exact match. However, by default the subdirs parameter is equal to "1" (because the Analyze Subdirs checkbox is checked), and therefore FlashStats will match any string starting with the URL specified in the Find parameter. (The Subdirs parameter is misnamed; it really should be named something like MatchStartString.) The value that you specify in the Find parameter should be the part of the URL after the host name (and port if present), beginning with a slash. For example, if the full URL to your web site's home page is http://www.domain.com then the value to specify for the Find parameter is /. If you store your graphics in a directory called images in the root document directory, and you want FlashStats to find all requests for documents starting with http://www.domain.com/images then specify a Find parameter of /images. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. You can also specify it in both the configuration file and in a form in order to restrict analysis to certain subdirectories. For example, if you are an ISP hosting many customers, each of whom shares the same domain name but has their own top-level directory (such as /~cust1/, /~cust2/, and so on), then you can specify a value for the Find parameter in the user account definition (in the FlashStats configuration file) such as Find=/~cust1/. FlashStats will then only analyze hits that begin with /~cust1/. If the user (ie, ISP customer) then fills out a form and specifies a Find parameter value of /images, then FlashStats will only count requests for documents starting with /~cust1/images. More details on this usage are in Chapter 5.

HitsPerDayOfWeek

If set to "1" the Hits Per Day report will be generated. Otherwise, FlashStats will not create this report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

HitsPerHour

If set to "1" the Hits Per Hour report will be generated. Otherwise, FlashStats will not create this report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

LogFormat

You can use this parameter to specify a custom log format so that FlashStats can correctly analyze your log files. For full details, see Chapter 9 (Custom Log Formats). This parameter may be specified in either the configuration file or in a form. It is usually defined in the configuration file.

Logs

Use this parameter to specify the location of the old (or "rotated," or "archived") log files for the user account. See the AccessLog parameter for more information. This parameter must be specified in a user account definition in the configuration file. The user must enter the correct password on the report request form.

Password

This is the password for the user account. This parameter is optional. If you want an account not to have a password, then you can either specify password= or just omit the parameter entirely. This parameter must be specified in a user account definition in the configuration file. The user must enter the correct password on the report request form.

Priority

Use this parameter to specify an alternate priority of execution for the FlashStats CGI program, so that it runs faster or slower than it normally would. If you want FlashStats to run more quickly then you should increase the priority, although you need to keep in mind that if FlashStats has a higher priority then other tasks running on the same computer will run more slowly. On the other hand, if other tasks seem to slow down too much when FlashStats is running, then you should reduce FlashStats' priority. For UNIX systems, this value is equivalent to the "nice" command. Valid values are from 1 to 19 (inclusive). 1 is highest priority (runs fastest, yields to other processes less), 19 is lowest priority (runs slowest, yields to other processes more). The default is 10. Numbers between 1 and 9 are only valid if FlashStats is running as super-user (which it shouldn't be, for security reasons). For Windows systems, this value can range from -2 to 2 (inclusive). The default is 0, which makes FlashStats run at default priority. -2 runs slowest (and yields to other processes more); 2 runs fastest (but yields to other processes less). For Macintosh systems, this parameter is ignored. This parameter may be specified in either the configuration file or in a form. It is usually defined in the configuration file.

Referrers

If set to "1" the Top Referrers To Your Site report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the referrers_top and referrers_greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

Referrers_Greater

This value specifies referrals with hits greater or equal to this value to be displayed in the Top Referrers To Your Site report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Referrers_Top

This value specifies the maximum number of referrals to display within the Top Referrers To Your Site report. A value of zero displays all referrals. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Requests

If set to "1" the Top URLs Requested report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the requests_top and requests_greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

Requests_Greater

This value specifies top URLs with hits greater or equal to this value to be displayed in the Top URLs Requested report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Requests_Top

This value specifies the maximum number of top URLs to display within the Top URLs Requested report. A value of zero displays all URLs requested. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Search

If set to "1" the Search Phrases report will be generated; otherwise, FlashStats will not create this report. If you set this parameter to "1" then you must also set the Search_Top and Search_Greater parameters to control the number of results displayed in the report. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

Search_Greater

This value specifies that search phrases with hits greater or equal to this value will be displayed in the Search Phrases report. The default value is 0. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Search_Top

This value specifies the maximum number of search phrases (from each supported search engine) to display within the Search Phrases report. A value of zero displays all search phrases found. The default value is 10. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

ShowQuery

If set to "1" (usually by a checkbox) the Top URLs Requested report will show the query string submitted with the HTTP request. Use this option if you care about the contents of the query string. The default value for this parameter is "0", which means that the query string is stripped from the request URL. This is the preferable option for most users. Please note that the default report request form shipped with FlashStats includes some commented-out code that you can use to have a Show Query checkbox on your report request form. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. If you want to prevent the user from generating this type of report, then set this parameter equal to 0 in their user account definition in the FlashStats configuration file.

Sm, Sd, Sy

These three parameters are the starting month, day and year of the log files to analyze. The year must be two digits (e.g., 97). This parameter may be specified in either the configuration file or in a form. It is usually defined in a form.

Subdirs

This parameter work in conjunction with the find parameter. If subdirs is set to "1" then FlashStats will analyze requests for the URL as specified by the find parameter, plus requests for URLs in subdirectories of the specified URL. But if subdirs is not specified or is set to "0", then FlashStats will only analyze requests that exactly match the URL specified in the find parameter. This parameter may be specified in either the configuration file or in a form. It is usually defined in a form. For example, if you set find=/products and subdirs=1, then the following requests would be analyzed by FlashStats: GET /products GET /products/ GET /products/flashstats/ But if you set find=/products and subdirs=0, then only one request would be analyzed by FlashStats: GET /products

Title

This parameter provides a short title for the web site or user account. The title is printed at the top of the FlashStats reports. This parameter must be specified in a user account definition in the configuration file. The user must enter the correct password on the report request form.

Url

This is the URL for the root of the web site being analyzed. This value is shown at the top of the FlashStats reports, and is also pre-pended to all items displayed in the Top Requests and Bad Requests reports in order to form clickable hyperlinks. The URL should end with a slash. This parameter must be specified in a user account definition in the configuration file. The user must enter the correct password on the report request form.

User

This parameter specifies the user account to be used for generating reports. The user parameter appears in two places. The first is in the FlashStats configuration file, where it is the first parameter on each user account definition line. The second place that the user parameter is used is in the Report Request Form filled out by the end-user to generate FlashStats reports. In this case, the user field indicates which user account should be used to generate statistics; there must be a user account with a matching user parameter in the FlashStats configuration file.

Version 1.5 -- Last update: 2/8/01

---