previous next

Chapter 17: Custom Logging

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.

Understanding Custom Logging

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.

The Helix Universal Server Registry

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:

http://address:AdminPort/admin/regview.html

Registry Variables

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

Global Variables

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.

Global Variables
Variable Description
%Date% Indicates the current date in the format MM/DD/YY.
%Time% Provides the current time of day in the local time zone in the format HH:MM:SS.
%GMTime% Displays the current Greenwich Mean Time in the format HH:MM:SS.
%TZDiff% Indicates the difference between local time and Greenwich Mean Time. For example, the output for Pacific Standard Time is -0800.
%Hour% Displays the current hour by local time zone in the format HH.
%Min% Indicates current minute in the format MM.
%Sec% Adds the current second in the format SS.
%% Creates a percent sign (%).

Template Types

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:

Report Formats

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
is using %Server.Bandwidth.Output% bits per second of bandwidth.

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
is using 2,800,000 bits per second of bandwidth.

Using Session Templates

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.

Choosing a Watch Type

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.

Watch Types
Watch Type Value Registry Values Watched
Client Session [Client.Session] Client connections.
Client Stream [Client.Session.Stream.*] Individual media player streams.
Broadcast Receiver [BroadcastReceiver.Statistics] Splitting receivers.
Broadcast Transmitter [BroadcastDistribution.Statistics] Splitting transmitters.
Broadcast [LiveConnections] Live connections.
Broadcast Archiver [LiveArchiving.Archiver] Live broadcast archiving.
Distributed Licensing[DistributedLicensing.
Publishers.Subscribers]
Distributed licensing.

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.

Selecting the Output Format Type

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:

Session Added Output Format Generate a report with the specified variables when the watched component connects.
Session Deleted Output Format Generate a report with the specified variables when the component disconnects.

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.

Defining Output Methods

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.

Console

The Std Error (Standard Error) and Std Out (Standard Output) options both publish the report to the command line console. No configuration is required.

File

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:

File name The log file name. The default location is the main Helix Universal Server installation directory. You can specify a relative or absolute path using the syntax appropriate for your operating system.
Log Rolling Frequency How many hours, days, weeks, or months pass before a new log file is created (optional).
Log Rolling Size Maximum size in Megabytes that the log file can become before a new file is created (optional).

Using Log File Rolling

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.

Log Rolling Methods

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.

Timestamps

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.

HTTP Post

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.

TCP Broadcast

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.

UDP Broadcast

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:

Destination Host name or IP address of the computer where the report should be published. For Multicast UDP, enter a Class D IP multicast address.
Port Number of an open port on the specified computer.

UNIX Pipe and System Log

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:

Windows NT Event 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:

Creating Logging Templates

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:

  1. Click Logging & Monitoring>Custom Logging.
  2. To create a new template, click the "+" icon in the Templates area, and edit the name in the Template Name box. This name is for your reference only. To select an existing template, highlight its name in the Templates area.
  3. In the Template Type list box, select 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.
  4. For More Information: See "Template Types".

  5. From the Template Status box, select 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.
  6. Optionally, you can enter a description in the Template Description box. This is for your own reference only, but is highly recommended.
  7. You next select one or more output types for the report to determine where Helix Universal Server sends the report information:
    1. Select an output type from Add Output Type pull-down list.
    2. Optionally, edit the name in the Output Name box. This name is for your reference only.
    3. For the selected output type, enter the necessary configuration parameters, as described in "Defining Output Methods".

  8. If you chose a 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.
  9. 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:

  10. If you chose 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.
  11. If you chose 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.
  12. In the Output Format area, click Property List to pick the variables from the Helix Universal Server registry included in the template. If you're setting up a Session Template, you can specify up to two output formats, one for Session Added Output Format, and one for Session Deleted Output Format.
    1. In the property list window, navigate to the variable that you want to include in the template.
    2. When you click on a variable, a string identifying that variable appears in the Output Format text box. Helix Universal Server reports values for variables in the exact order the variables appear in the text box. To organize the order of variables, cut and paste them in the order that you want them to appear in your report.
    3. 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.

    4. Optionally, format the report output by adding boilerplate text.Two tags help with formatting the output sting. Use a \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.

  13. Click Apply.

Sample Templates

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.

Using the Preconfigured Templates

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.

Errors Template

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.

Extended Logging Template

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)

Server Stats Template

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)
Uptime: 1234274 seconds
CPU Percent Usage: 5
Players Connected: 32
Players Connected in the Last 10 Seconds: 2
Players Connected by Protocol: 0 PNA, 22 RTSP, 10 MMS, 0 HTTP (0 Cloaked)
Players Connected by Transport: 0 TCP, 32 UDP, 0 MCast
Total Subscribed Bandwidth Output: 9385984 bps
Total Actual Bandwidth Output: 9244432 bps
Average Bandwidth Output Per Player: 293312 bps
Memory Stats: 14294824 Bytes In Use

Creating a Client Statistics Log

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]

Connection Statistics Boilerplate and Variables

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****
Date and Time: %Date%, %Hour%:%Min%.%Sec%
**CLIENT INFORMATION**
Type: %Client.*.User-Agent%
Address: %Client.*.Addr%
Total Bandwidth: %Client.*.Bandwidth%
Preferred Language: %Client.*.Language%
**CLIP INFORMATION**
Requested URL: %Client.*.Session.*.PlayerRequestedURL%
Clip Size in Bytes: %Client.*.Session.*.FileSize%
Title: %Client.*.Session.*.FileHeader.Title%
Author: %Client.*.Session.*.FileHeader.Author%
Copyright: %Client.*.Session.*.FileHeader.Copyright%
Stream Count: %Client.*.Session.*.FileHeader.StreamCount%
**TRANSPORT INFORMATION**
Protocol: %Client.*.Protocol%
Port: %Client.*.Port%
UDP used (0=no, 1=yes): %Client.*.IsUDP%

Disconnect Statistics Boilerplate and Variables

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****
Date and Time: %Date%, %Hour%:%Min%.%Sec%
Type: %Client.*.User-Agent%
Address: %Client.*.Addr%
Requested URL: %Client.*.Session.*.PlayerRequestedURL%

Report Output

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****
Date and Time: 06/19/02, 14:53.51
**CLIENT INFORMATION**
Type: RealMedia Player Version 6.0.9.1349 (win32)
Address: 207.188.7.125
Total Bandwidth: 57600
Preferred Language: es, *
**CLIP INFORMATION**
Requested URL: rtsp://208.147.89.157:554/video1.rm
Clip Size in Bytes: 2479645
Title: Introductory Video
Author: RealNetworks, Inc.
Copyright: ©2002 RealNetworks, Inc.
Stream Count: 1
**TRANSPORT INFORMATION**
Protocol: RTSP
Port: 7180
UDP used (0=no, 1=yes): 1

****CLIENT DISCONNECT****
Date and Time: 06/19/02, 14:59.15
Type: RealMedia Player Version 6.0.9.1349 (win32)
Address: 207.188.7.125
Requested URL: rtsp://208.147.89.157:554/video1.rm


RealNetworks, Inc. © 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.
previous next