Module mod_musical_log

The Module mod_musical_log module is contained in the mod_musical_log.c file. It provides for monitoring of the server Apache behavior through sound.

Summary

This module is a component of WebMelody system and its main goals are :

It provides directives that allow to configure the whole WebMelody system. They are enclosed in MusicalLog section.

MusicalLog section

This section is located between <Musical_Log> and </Musical_Log> directives. Only a section can be present in Apache configuration file. It's used to configure WebMelody. You must specify :

Channel section

This section is located between <Channel> and </Channel> directives. It can occur multiple times in MusicalLog section without nesting. In this section the WebMaster can introduce a set of rules describing which information are relevant and how they must be translated into sounds.

In a Channel section, the following information must be provided:

Our current implementation of the sonification module supports three types of event to specify in sonification patterns.

ComplexEvent section

This section is located between <ComplexEvent> and </ComplexEvent> directives. It can occur multiple times in Channel section without nesting. In this section the WebMaster can define a complex event.

Compatibility notes

This module has been tested with Apache 1.3.6.

Directives

These configuration parameters control the sonification Apache features.


<MusicalLog> directive

Syntax: <MusicalLog> ... </MusicalLog>
Context: server config
Module: mod_musical_log.

<MusicalLog> starts a subsection which is terminated with a </MusicalLog> directive. These directive takes no arguments and identify a MusicalLog section. They are used to enclose a group of directives which specify sonification patterns.
Only a MusicalLog section can be inserted in the configuration file.


MusicalPlayer directive

Syntax: MusicalPlayer addr
Context: MusicalLog
Module: mod_musical_log

With the MusicalPlayer directive you specify the address of a WebPlayer authorized to sonify the server activity. If you want to authorize multiple WebPlayers repeat the directive for each one.
Although addr can be hostname it is recommended that you always use an IP address, for example:

MusicalPlayer 111.22.33.44

EventsCollector directive

Syntax: EventsCollector addr[:port]
Default: EventsCollector localhost:7000
Context: MusicalLog
Module: mod_musical_log

With the EventsCollector directive you specify the address of the Collector. Default Collector port number is 7000.
Although addr can be hostname it is recommended that you always use an IP address, for example:

EventsCollector 111.22.33.44:8000
. If you don't specify this directive the Collector will be search at localhost:7000 address.

StatisticsFrequency directive

Syntax: StatisticsFrequency number
Default: StatisticsFrequency 30
Context: MusicalLog
Module: mod_musical_log

The StatisticsFrequency directive defines the amount of time (in seconds) the Collector will wait for processing logging data received from the server. Number is also the amount of time between two transmissions to WebPlayers.
If you don't specify this directive it will be assumed a 30 seconds value for this parameter.


<Channel> directive

Syntax: <Channel> ... </Channel>
Context: MusicalLog
Module: mod_musical_log.

<Channel> and </Channel> are used to enclose a group of directives that define a Channel section. Each section defines a server profile one want to monitor. It's possible to define more profiles, without nesting, using more Channel sections. It's necessary for each section specify a name, audio tracks number, location and type of a sample set, an event (simple, complex, workload) at least.
<Channel> takes no argument.


ChannelName directive

Syntax: ChannelName name
Context: Channel
Module: mod_musical_log.

ChannelName specifies the Channel name. This directive must be inserted in a Channel section exactly once. Infact a Channel section is identified by name.


ChannelDescription directive

Syntax: ChannelDescription description
Default: ChannelDescription channelname
Context: Channel
Module: mod_musical_log.

ChannelDescription specifies a description of the Channel. If it's not present the Channel name is taken as Channel description.


TracksNumber directive

Syntax: TracksNumber number
Context: Channel
Module: mod_musical_log.

TracksNumber directive sets the desidered maximum number of musical tracks you want use to sonify events. For each event to monitor a musical track must be available.


SampleSet directive

Syntax: SampleSet URL
Context: Channel
Module: mod_musical_log.

SampleSet directive specifies musical tracks sample network location.
Each Channel must specify exactly a SampleSet URL. This URL is used by WebPlayer to download musical tracks sample to sonify server events. This sample is made by a tracks number specified by TracksNumber directive.


SampleType directive

Syntax: SampleType type
Context: Channel
Module: mod_musical_log.

SampleType directive sets the audio format of sample set specified by SampleSet directive. It must occur first than sampleSet in a Channel section.
Actually type can be only MIDI.


Load directive

Syntax: Load [min-max] step
Context: Channel
Module: mod_musical_log.

Load directive allows to define how to monitor load factors of the server. Load factor is expressed in terms of number of requests currently being processed by server.
min,max indicate the musical tracks range to use for monitoring the server workload. step indicates how to associate load factors to musical tracks in the established range.
In particular, if LOAD = number of requests currently being processing then:

    
                     min       if LOAD/step + min <= min
     
       trackNo =     max       if LOAD/step + min >= max      

                     LOAD/step + min   otherwise  

when trackNo is the track number to play.

Throughput directive

Syntax: Throughput [min-max] step window_size window_increment
Context: Channel
Module: mod_musical_log.

Throughput directive allows to define how to monitor throughput, i.e. number of served HTTP requests within a sliding temporal window, of the server.
min,max and step indicate the musical tracks range and the step to make associations, the same as Load .
window_size is a number that indicates the size of a sliding window where calculate throughput values.
window_increment is another number that specifies how to slide the window.
Tracks to sound for a throughput value is determinated in the same manner as Load directive; the only difference is LOAD is equal to the number of requests served in the current sliding window.
For example the directive:

Throughput [0-8] 5 10 1
evaluates throughput by counting the number of requests within a sliding temporal window of 10 seconds moved each second to the right. Tracks used for sonification are in range [0-8] in steps of 5.

StatusCode directive

Syntax: StatusCode [!] regex track_no [threshold [time_slice] ]
Context: Channel
Module: mod_musical_log.

This directive allows to associate a musical track to one or more HTTP status code values.
You can use extended regular expressions, i.e. regex, to indicate an HTTP status code set to associate the musical track indicated with track_no. Track_no is a number in the range [0-(tracks_number-1)] (tracks_number is the value specified with TracksNumber directive.

Regex may or may not be preceded by `!'. Thus, `400|501' matches 400 errors and 501 errors (Bad Request, Not Implemented) only; `! 400|500' matches all HTTP status codes different by 400 or 500 errors.
Optionally you can specify a number, i.e. threshold, to express the minimum number of events to occur in a time slice to play the track. A time slice value can be specified with a number, i.e. time_slice; if you specify a threshold without a time_slice value, then we assume as time slice the value specified with StatisticsFrequency directive. For example with:

StatusCode 5.. 4 5 10
track 4 is played when 5 occurrences of server errors (HTTP status codes 5xx) happen within 10 seconds.

RequestHeader directive

Syntax: RequestHeader header_name [!] regex track_no [threshold [time_slice]]
Context: Channel
Module: mod_musical_log.

This directive allows to associate a musical track to one or more values of an HTTP header (general, request and entity header), i.e. header_name, that can be present in an HTTP request.
regex is a regular expression to specify a set of values for header_name header. Note that the regular expression string is case-insensitive so it provides for case-insensitive matching
The use of tracks_no, threshold, time_slice is the same of StatusCode directive.

For example with:

RequestHeader Authorization ".*" 4
track 4 is played for each HTTP request with non-empty value for the Authorization header. If you want to sonify this event only when occurs three time in 5 seconds then you can use:
RequestHeader Authorization ".*" 4 3 5


ResponseHeader directive

Syntax: ResponseHeader header_name [!] regex track_no [threshold [time_slice]]
Context: Channel
Module: mod_musical_log.

This directive allows to associate a musical track to one or more values of an HTTP header (general, response and entity header), i.e. header_name, that can be present in an HTTP response.
regex is a regular expression to specify a set of values for header_name header. Note that the regular expression string is case-insensitive.
The use of tracks_no, threshold, time_slice is the same of StatusCode directive.

For example with:

ResponseHeader content-type "text/.*" 4
track 4 is played whenever an HTTP response with Content-Type header value with MIME type text (including therefore html and plain text, for example) is served to the client.

HttpVersion directive

Syntax: HttpVersion [!] regex track_no [threshold [time_slice]]
Context: Channel
Module: mod_musical_log.

This directive allows to associate a musical track to one or more values of HTTP protocol version of an HTTP request.
regex is a regular expression to specify a set of values for HTTP protocol version. Note that the regular expression string is case-insensitive.
The use of tracks_no, threshold, time_slice is the same of StatusCode directive.

For example with:

HttpVersion "http/1.0 4
track 4 is played whenever an HTTP request with protocol version equals to http/1.0 is served to the Web client.

Method directive

Syntax: Method [!] regex track_no [threshold [time_slice]]
Context: Channel
Module: mod_musical_log.

This directive allows to associate a musical track to one or more values of HTTP method of an HTTP request.
regex is a regular expression to specify a set of HTTP method. Note that the regular expression string is case-insensitive.
The use of tracks_no, threshold, time_slice is the same of StatusCode directive.

For example with:

Method "POST|PUT" 4
track 4 is played whenever an HTTP request with POST or PUT method is served to the client.

RequestUri

Syntax: RequestUri [!] regex track_no [threshold [time_slice]]
Context: Channel
Module: mod_musical_log.

This directive allows to associate a musical track to one or more URI requested by clients.
regex is a regular expression to specify a set of URI. Note that the regular expression string is case-insensitive.
The use of tracks_no, threshold, time_slice is the same of StatusCode directive.

For example with:

RequestUri "^/~vitsca/" 4 3 5
track 4 is played when in 5 seconds 3 accesses to directory ~vitsca are made by clients.

RemoteHost

Syntax: RemoteHost [!] regex track_no [threshold [time_slice]]
Context: Channel
Module: mod_musical_log.

This directive allows to associate a musical track to one or more remote hosts that made an HTTP request.
regex is a regular expression to specify a set of IP addresses or a set of host names. Note that the regular expression string is case-insensitive.
The use of tracks_no, threshold, time_slice is the same of StatusCode directive.

For example with:

RemoteHost "\.(it|de)$" 4
track 4 is played whenever an HTTP request from domains thar are in .it or .de is served.

<ComplexEvent> directive

Syntax: <ComplexEvent> ... </ComplexEvent>
Context: Channel
Module: mod_musical_log.

<ComplexEvent> and </ComplexEvent> are used to enclose a group of directives which identify a ComplexEvent section that you will use to define a complex event. It's possible to define more complex events in a Channel without nesting.
A complex event is an event obtained through the composition of simple events with AND operators.
Simple events that can be appear in ComplexEvent section are:


When you use these directives in ComplexEvent section, you must omit track_no and optional parameters, i.e. threshold, time_slice. A track number (and a threshold with time slice) must be associate with complex event with Track directive.

Track directive

Syntax: Track track_no [threshold [time_slice] ]
Context: ComplexEvent
Module: mod_musical_log.

This directive allows to associate a musical track, a threshold and a threshold time slice with a complex event.
You must use exactly an occurrence of this directive in a ComplexEvent section.
For example :

          <ComplexEvent> 
             StatusCode  "403|5.." 
             RequestUri "/cgi-bin/*"  
             RemoteHost  ".*\.it"   
             Track  4 5 10 
          </ComplexEvent> 
The complex event is represented by Status Code is 403 (Forbidden) or any server error (5xx) AND, the requested URI was a cgi-bin script AND the request came from an italian IP domain. In this way, we can listen when many (more than 5 in 10 seconds) italian clients accessing cgi-bin scripts fail for lack of authorization or for malformed parameters that can cause severe errors in the cgi-bin script.