Roxen LogView 1.0 Manual Contents Publishing rights Creators Programming Manual Acknowledgements About this manual Conventions Overview Installing LogView Configuring LogView Event log Configure Viewing LogView statistics Statistics Report Advanced The <logview> tag LogView options LogView example Troubleshooting Publishing rights Copyright © Idonex AB 1998. All rights reserved. No part of this document may be reproduced, in any form or by any means, without the written permission of Idonex AB. Roxen and Pike are trademarks or registered trademarks of Idonex AB. All product names are trademarks or registered trademarks of their respective holders and recognized as such. Creators Programming Fredrik Noring Manual Leif Stensson, Fredrik Noring Acknowledgements Many thanks to Francesco Chemolli and Matthew Brookes and of course all the other testers. Thanks! About this manual Conventions Monospace is used for: representing examples of code HTML and RXML tags and attributes command lines and options that should be typed on the screen filenames and directories Italics is used for: Internet addresses such as domain names and URLs to emphasize a term or expression When you have to fill in a value we indicate this by writing a dummy value between »...«. Replace the dummy value and the »...« with the proper value.
	Note: presents interesting pieces of information related to the surrounding discussion.
	Tip: a tip offers advice or teaches an easier way to do something.
	Warning: advises you about potential problems and helps you steer clear of disaster.
	To make it easier for you to spot the examples we have put them in light-grey boxes; Example We suggest that you best use the examples by studying and experimenting with them. Overview The Roxen LogView module gathers and displays various statistics for a Roxen WWW server. LogView is also capable of importing Common Log Format files produced by other WWW servers. The LogView module is installed once on the main server, and then enabled or disabled separately for each virtual server managed by this (main) server. Each virtual server can have its own LogView administrator and LogView viewer account, each with separate passwords. Once installed and enabled, LogView gathers statistics for its virtual server, and compiles it into one or more statistics databases. The statistics data from the databases are then processed by one or more statistics groups, allowing for merging statistics from several servers. Installing LogView Before use on any virtual Roxen server, the Roxen LogView module needs to be installed on the main server. This is done as follows: Create a suitable directory and unpack the LogView distribution into it. Alternatively, unpack the LogView distribution into a module directory already in Roxen's module path list. Start a Web browser and go to the configuration interface of the Roxen system, select Global Variables, and make sure the LogView module directory is in the list of module directory paths.
	Do not create a symbolic link to make it seem as if a LogView directory somewhere else is inside the server's directory tree -- this may confuse LogView when it analyses the site structure.
	Once installed on the Roxen server, LogView needs to be installed on each of the virtual servers for which statistics is desired. Repeat the following for each virtual server: Go to the configuration interface of the main Roxen server, and select configuration for the virtual server on which to enable LogView. Select Add Module and search the alphabetical list of modules for the entry 'LogView'. Click on the module name. The module will be installed. Go to the main server's configuration interface, select Virtual Servers, then the virtual server in question, then LogView, and check that the log directory path is correct. There, you can also change the mount point for the LogView access page and the administrator and viewer user names and passwords there, if necessary. The default values are: Administration user name The name is the same as for the Roxen general administration. Administration password The password is the same as for the Roxen general administration. Viewer user name None, making the viewer available to everyone, without need to log in. Viewer password None. Log path The virtual server's log directory. Mountpoint /logview/ Enable <logview> tag The <logview> tag is disabled by default. The installation should now be complete. Configuring LogView To configure LogView, start a WWW browser and go to the LogView access page for the server in question. The URL will typically be: http://server name:server port number/logview/admin/ although the "/logview/" part could be different if the administrator of the main server selected a different mount point. The virtual server's module configuration page for LogView has a link pointing to the appropriate page. When attempting going to the LogView access page, the server will ask for a user name and password. Enter the LogView administrator name and password (as entered in the installation above). The administration interface will have the same access pages available as the viewer interface, plus two separate administration pages: Event log and Configure. Event log Pressing the Event log button near the top of the page will lead to a page which will offer a choice between two different logs, the Admin log, and the Summary log. The Admin log gives you an overview of the server's performance. The Admin log will display a list of events that took place in the administration interface, such as the administrator logging in, and changes being made in the administration. The list also displays errors like when it failed to compile anything or any occurred errors. The informational messages are preceded by an information icon, while the warning and errors messages are preceded by the warning and error icon respectively: Information icon Warning icon Error icon The Summary log is much more detailed and will give a summary of automatic LogView activities, such as importing logs, updating the local server, updating statistics databases, etc. This log is mainly useful in tracking errors and other problems. Configure Pressing the Configure button near the top of any administration page will lead to the general configuration page. On this page, there are several options: Update LogView normally updates the databases once per hour; this option is provided for cases when the viewed statistics needs to be up-to-date to the last minute, and for testing. Logs... Find out what logs are available on the current virtual server, and update them if needed. By default, LogView gathers one plain file with all statistics for the current server, and processes it in one statistics group with the same name as the virtual server LogView is running on. More statistics files and statistics groups may be created through the 'Import Common Log Format' and 'Update' option. Statistics groups... Add new statistics groups, and configure how the groups will process and save data. Import Common Log Format... Import a Common Log Format log from another server (or older logs from this server). Note that the Common Log Format does not contain as much information as LogView's own log files. Imported logs will be tracked, so there is no need to explicitly import the logs when statistics are to be viewed. Delete log... Stop logging data to a log file, and remove the file. Configuration data associated with the log file may optionally be removed as well, which will make LogView forget the file ever existed. If configuration data is not removed, a new log file will be created when new log data becomes available. Delete statistics group... Stop processing data through this group, and delete the group database. Optionally, the groups configuration data will also be removed. If the configuration data is not removed, a new group database will be created whenever new log data becomes available in the log files associated with this group. Report maker... Edit an old, or create a new, report style for quick-and-easy reports to be created from the Report page. The report style is described as an RXML document, using the <logview> tag to generate individual statistics diagrams. Optionally, a report can be sent by email. Delete report... Remove report styles. Viewing LogView statistics To view statistics for a server, go to the LogView access page, and log in as either administrator or viewer. (The only major difference is the obvious one: that administration functions are not available to viewer users.) The URL for the viewer pages is: http://server name:server port number/logview/ although the "/logview/" part could be different if the administrator selected a different mount point. There are four different viewer pages: Statistics, Report, Advanced and Manual (which latter leading to a version of this manual). The Statistics page is the normal way of viewing various statistics, while the Report page provides a quick-and-easy way of getting a summary of recent activities in a statistics group. The Advanced page provides essentially the same functinality as the Statistics page, but with more control over details. Statistics If there are several statistics group, the Statistics page will offer a choice of group at the top of the page. If there is only one group, the selector will be absent. Next on the page will be a box labeled 'Period of time', which offers a choice of year or month, with the current year selected by default. When a month is selected, a calendar of individual days and weeks will appear, providing finer granularity in selecting which time period to examine. Select the desired period. Below the 'Period of time' box follows a menu of various categories of statistics to display, including 'Most active domains', 'Popular pages', 'Popular directories', 'Most common browser'. Select which one to view. Once selected, a summary will appear below the menu boxes, together with a menu allowing the user to choose the format of the summary. The following formats are available: Table The 'Table' format is what it sound like, a plain text document with the data presented as a table. This format is available for all summary types. Export 'Export' is essentially the same as 'Table', but presented as a plain ASCII file rather than HTML. The 'Export' format is suitable for automatic processing of digested statistics data, and has one item per line, and each line containing the item name, followed by a TAB character, followed by the quantity associated with that item (typically the number of hits/occurances). This format is available for all summary types. Line Chart The 'Line Chart' format is available for the kind of statistics that count a quantity per time period, such as 'Hits per month' and 'Bandwidth per day'. The data is presented as a graph with the time period on the X axis, and the quantities on the Y axis. Bar Chart 'Bar Chart' is much like the 'Line Chart' format, and available for the same kind of statistics as 'Line Chart'. The only difference is in appearance, where the quantities are indicated by vertical bars rather than a graph. Pie Chart and 3D Pie Chart Pie Charts are available for statistics where the number of categories is relatively small, such as the summary of return codes. Report The Report page provied a quick-and-easy means of obtaining summarized reports of the recent activities of the available statistics groups (as defined in the configuration). The ordinary user is given a choice between a number of report styles (typically one per statistics group, but this depends on the local configuration). The administrator can remove old report styles, and create new ones. Report styles are specified as headerless RXML documents which uses the <logview> tag to generate individual tables and diagrams in the report. Advanced The Advanced page allows interactive access to the same functinality as is provided by the <logview> tag (see below), which gives the user individual control of the various report format parameters. This feature is provided for mainly two kinds of users: Normal viewer users who wish to examine statistics in greater detail than most. RXML document writers who want a simple way of testing how different parameters to the tag affects the diagrams produced, without having to write a lot of test documents. The page is a simple fill-in form, where users fill in what statistcs group, report type, time periods etc that they are interested in. Once the information is selected, one of the "Display" buttons below the form is pressed to select the presentation style, and to generate the corresponding diagram. There is a special display mode, 'Tag', which produces the <logview> tag which would generate the selected report if inserted into a RXML document. The <logview> tag The LogView module provides a special RXML tag, <logview>, which provides an easy way for inserting simple statistics reports in ordinary RXML documents. The usage is simple: <logview options> where the options are some of the following: Troubleshooting The first thing to do in case of problems is to check LogViews error log files, and failing that, the main Roxen server's error log files. Both LogView and Roxen try to generate comprehensible reports of errors that occur. Specific problems: The installation of LogView failed Problem: The installation of LogView failed If the installation of LogView failed, it is typically due to one of the following things: The server may not have write permission to the log files directory, or may lack permission to read some of the files in the LogView distribution. (The main server's error log files will contain information about which file accesses failed, if any.) LogView was instructed to store its logs and groups files in a directory other than 'logview.data' (which is the default). In this case, the non-standard directory must be created manually. It is generally a good idea to check the main server's error log files when installation fails.