Helix Universal Server's custom logging feature allows you to monitor specific types of events and information that occur on Helix Universal Server. You can thereby create reports about any type of activity you choose. This chapter explains how to use the custom logging feature, which supplements the main log files described in Chapter 16.
Custom logging is a highly flexible feature that allows you to gather the exact information you want, reporting it at any time to different outputs such as the screen or a text file. You can use this feature to gather information about current Helix Universal Server client connections, for example. Custom logging is designed to supplement the access and error logging described in Chapter 16, but you may find that custom logging is adequate for all of your logging requirements.
To get information for reports, custom logging relies on information stored in the Helix Universal Server registry, which is distinct from the main registry on Windows operating systems. The registry contains information about most aspects of Helix Universal Server. Although the registry is an extension of Helix Administrator, there is no link to it from any Helix Administrator page. However, you can display the registry by opening the following URL in a browser:
|
The Helix Universal Server registry stores information in variables such as
LiveConnections.Count. Each variable reports a specific type of value or setting,
from real-time data on client connections and server health, to configuration
and license information. When you create a custom logging template, you add
variables to your report by selecting them from a pop-up HTML list. Within a
report template, variables are always preceded and followed by percent signs,
as in %LiveConnections.Count%.
Through the variables list, you can also choose global variables, such as the time of day, that are derived from the operating system rather than extracted from the Helix Universal Server registry. The following table lists the global variables that you can include in reports.
You add the registry variables that you want to track to a report template, which defines how often the selected information is reported, as well as where the report is delivered, such as to a file or to the console. You can use three types of templates:
Interval templates log information at regular intervals, such as every hour. You can define exactly how much time elapses between report output. Interval reports are useful for producing regular status reports about Helix Universal Server health, for example.
With a watch template, you can set a watch on a certain variable, or group of variables, generating a report when information changes. A watch template is useful for reporting errors, for example, because a report is generated only when an error occurs.
As system activity occurs, Helix Universal Server dynamically adds and deletes variables from its registry. When a media player requests a clip, for example, Helix Universal Server creates a unique registry entry for that player, storing information such as the player address and the requested URL. A session template reports on this dynamic activity as it happens.
| For More Information: See "Using Session Templates" for more information about these templates. |
Through the report template, you format a report, adding boilerplate text around selected variables if you wish. For example, you might create an entry like the following:
With a total of %LiveConnections.Count% player connections, Helix Universal Server |
In this example, %LiveConnections.Count% and %Server.Bandwidth.Output% are
variables, and the rest of the text is boilerplate. When Helix Universal Server
generates the report, it replaces the variable entries with values from its
registry. The resulting report looks like this:
With a total of 50 player connections, Helix Universal Server |
A session template reports on dynamically added and deleted registry variables. Helix Universal Server creates registry variables when media players, encoders, transmitters, and other components connect to it. These variables store information about the component. Using a session template, you can create a report when one of these components connects, disconnects, or both. This lets you record statistics about each media player, for example, such as the player's IP address, its request URL, its bandwidth, and so on.
When you create a session template, you select a watch type, which specifies the type of component connection that generates the report. The following table describes the possible values that you can choose.
For example, if you choose Client Session [Client.Session] as the watch type, you
can generate a report every time a client connects or disconnects. In this case,
clients can be media players requesting clips, as well as browsers displaying
Helix Administrator HTML pages. In your report, you then choose which
registry variables from that client connection you want to log.
| Tip: The section "Creating a Client Statistics Log" provides an example of how to gather client statistics. |
For each session template, you can choose whether to generate the report when the watched component connects, when it disconnects, or both. When you set up the template, you choose an output format from a pull-down list:
The two output formats allow you to report on different variables when a component session begins, then when it ends. When a client connects, for example, you may want to record several variables, including the client's IP address, request URL, streaming protocol, transport protocol, and so on. When it disconnects, though, you might want to record just the time and IP address.
The custom logging output methods determine how Helix Universal Server publishes the report. There are several options, and you can select multiple delivery methods for each custom log report. Additionally, multiple report templates can write to the same output, such as the same file. Most outputs require configuration. For example, if you send your report to a file and a local TCP port, you specify a file name and a port number.
The Std Error (Standard Error) and Std Out (Standard Output) options both
publish the report to the command line console. No configuration is required.
When you select the File output method, Helix Universal Server publishes the
report to a text file, continuously appending new results to the end of the file
unless you set up log rolling. You configure the following variables:
Log rolling is optional, but recommended if you expect to report statistics frequently. If multiple templates write to the same file log file, define log rolling in just one template.
Generally, you limit log files by frequency or size. You can select both methods, however, to create log files according to the first limit reached. For example, you can create a new log file whenever the preceding file reaches 10 Megabytes in size, or has recorded 3 days of activity, whichever comes first.
When you implement log rolling, Helix Universal Server appends a timestamp
to the end of the file name to indicate when the file was created. Suppose that
you specify the file name serverstats.txt. Your log directory may contain several
files with the same base file name, but each with a unique timestamp that
looks like this:
serverstats.txt.20020622134953 |
The timestamp is in the format YYYYMMDDHHMMSS, using a 24-hour clock.
Hence, the file in the preceding example was created on June 22, 2002, at
1:49.53 P.M.
With the HTTP Post method, Helix Universal Server publishes the report to a
Common Gateway Interface (CGI) program. You configure the following
variables:
URL |
URL location of the CGI program. |
Port |
Number of the HTTP port on the Web server receiving the log. |
The Outbound TCP and Inbound TCP output destinations let you send the report
to an application listening on a specific TCP port. The Outbound TCP method
publishes the log on a remote computer. For this method, you configure the
following variables:
Destination |
Host name or IP address of the computer that receives the log. |
Port |
Number of an open port on the specified computer. |
The Inbound TCP method publishes the log on the local computer. You
configure the following variable:
Port |
Number of an open port on the local computer. |
The Outbound UDP and Multicast UDP methods publish the report to a UDP
socket on a remote computer using unicast or multicast UDP, respectively. You
configure the following variables:
On UNIX operating systems, the Pipe and Syslog methods make the log
available to another process, or publish the information to the system log,
respectively. For Pipe, you configure the following variable:
Command |
Pipe command to the application or script where the information can be post-processed. |
For Syslog, you choose one the following priorities, each of which corresponds
to an entry type in the UNIX system log:
If you choose NT Event Log, Helix Universal Server publishes the report to the
event log that corresponds to the priority selected. Each option corresponds
to an entry type in the Windows NT Event Log:
The following procedure explains how to create a new custom logging template, or modify an existing one. You'll need to be familiar with the information in the preceding sections to set up your custom template. Preconfigured templates are ready to use, but must be turned on. These templates are described in the section "Using the Preconfigured Templates".
| To create or modify a custom logging template: |
Watch, Session, or Interval to set the overall type of template. The option you choose affects other options that appear on the page, as described in Step 7 through Step 9.| For More Information: See "Template Types". |
On or Off to enable or disable the custom logging report, respectively. An existing template starts or stops reporting as soon as you change its status and click Apply.Watch template in Step 3, follow this step. Otherwise, skip to the next step. Click Property List in the Watches area. In the list that appears, choose the variable or variables that you want to watch for changes.| Note: Place each watched variable on a separate line in the Watches list. Helix Universal Server determines which variables to watch by matching the string that appears on each line of the Watches list. |
The optional minimum and maximum output intervals for the Watch template let you generate the report at regular intervals. If you do not define either field, Helix Universal Server creates the report only when a watched registry variable changes:
This field holds a number in the format HH:MM:SS that defines the smallest possible time that must pass between log outputs. Changes to the watched variables are not reported until the minimum interval has elapsed. If you set 00:05:00, for example, watched variables that change are reported every five minutes. If no watched variable changes its value in five minutes, though, the report is not created until a variable changes, or the maximum interval is reached.
This entry contains a number in the format HH:MM:SS that defines the longest possible time allowed to pass before the report output is generated. Changes to variables being watched will generate the report output even if the maximum interval has not been reached, however. If you set 01:00:00, for instance, and no watched variable changes within an hour after the last report, Helix Universal Server generates the report when the hour elapses.
Session in Step 3, select the appropriate watch type from the Watch Type list box. Otherwise, skip to the next step. As described in "Choosing a Watch Type", the watch type you select determines which dynamic event triggers the report output.Interval in Step 3, set the appropriate combination of hour, minute, and seconds for the report interval in the Output Interval boxes. If you leave a box blank, the setting for that box is considered to be 0.Session Template, you can specify up to two output formats, one for Session Added Output Format, and one for Session Deleted Output Format.Tip:
A variable added to the Output Format text box is
surrounded by percentage signs (%Server.Bandwidth.Output%). If
you reorganize the order of the variables, make sure to include
the percent signs that surround each variable name.
|
\n tag to move output to a new line. Carriage returns you enter in the box are also recognized as new lines. Use a \t tag to insert a tab.This section explains how to use the preconfigured templates that come with Helix Universal Server. It then provides an example of setting up your own template to log client statistics.
Helix Universal Server comes preconfigured with three templates that illustrate the interval, watch, and session template types. Each template reports output to the console, but is turned off initially. To use a template, you must enable it and, optionally, customize it by changing the output destination or modifying the reporting variables. You can also ignore these templates and create your own. The following sections explain these templates.
The preconfigured Errors template is a watch-type template. Whenever Helix
Universal Server encounters an error, the Errors template writes the message to
the console. You may want to modify this template to send the output to a
file, for example. As well, you can establish minimum and maximum intervals
instead of reporting each time an error occurs.
The preconfigured Extended Logging template is an example of a session
template. It gathers information about client sessions, including media
players and Helix Administrator activity, and publishes the report to the
console when a client session ends. A single line of the report output looks like
this:
09:55:28 127.0.0.1 RTSP GET real9video.rm RealMedia Player Version 6.0.9.1349 (win32) |
The preconfigured Sever Stats template is an example of an interval template.
It is designed to send basic server statistics to the output console every hour.
Optionally, you can modify the variables it reports, write the information to a
file, or change its boilerplate text. The report output looks like this:
Server Stats (06/17/02 10:33:52) |
This example illustrates how to log information about each client request, including media players requesting clips and browsers requesting Helix Administrator pages. This sample template also logs information when each client disconnects. In your template, you would set up the following basic parameters:
| Template Name: | any |
| Template Type: | Session |
| Template Status: | on |
| Template Outputs: | any |
| Watch Type: | Client Session [Client.Session] |
For Session Added Output Format, you define the report information you want
to collect when a client connects. You create a report using boilerplate text and
variables chosen from the pop-up property list. Note that \n adds a new line to
the report. You can also use \t to insert tabs. Here's an example:
\n\n****CLIENT REQUEST**** |
For Session Deleted Output Format, you define the report information you want to collect when a client disconnects. Here's an example:
\n\n****CLIENT DISCONNECT**** |
Once you've defined your template and applied the changes, Helix Universal Server sends the custom logging information to the chosen output each time a client connects or disconnects. The following is an example of a single media player connecting, then disconnecting.
****CLIENT REQUEST**** |
|
|
© 2002 RealNetworks, Inc. All rights reserved.
For more information, visit RealNetworks Click here if the Table of Contents frame is not visible at the left side of your screen. |