|
The Marratech Manager version 3.5 introduces media
activity logging functionality. It can be used to log chat
messages sent during a meeting, and log other media activity,
such as when someone started to send audio and / or video
and when they stopped.
This functionality is considered an advanced topic and should
not be used by anyone not confortable with administering server
software.
1. How to enable the media logging.
2. Syntax of the media log.
3. Syntax of the processed media log.
4. How to obtain the media logs.
5. The media log processing tool.
6. Known issues
Appendix A
Appendix B
Appendix C
The media logging functionality cannot be enabled from the
administration interface. Rather, to enable the logging or
changing any other of its settings the advanced configuration
must be used.
To find the configuration use this URL:
http://<address>:<port>/admin/config/advanced.jsp
and then follow the links through 'session engine' and finally
'medialogger'.
For each media that should have logging enabled change the
setting of the enable property to true.
Then restart the Manager for the settings to have effect.
Preferably logging of audio, video, mstarcontrol and wbbesteffort
is enabled, while logging of wbreliable and web is left disabled.
The web and wbreliable media may contain data sent fromone
client that is triggered by some other. For example an update
request of a whiteboard page. Thus, interpreting a resulting
log may be a daunting task.
The media logs are output from the server in an intermediate
format that needs some post processing in order to be adequatly
readable to a human. This saves the
server some resources at the time of the logged event.
A utility for post processing is bundled with the server.
The activity is logged as events. Commonly there is one event
generated upon start of some activity and then one
event when this specific activity stops. However, some events
are instantanious, thus there will be only a start event without
any corresponding stop event.
One single event consists of a set of fields separated by
a tab character (ascii 0x09) and the events are separated
by a carriage return (ascii 0x13) followed by a line feed
(ascii 0x10).
There are six types of events written to the media log;
- MEDIA CREATED
- MEDIA DISPOSED
- CLIENT JOINED
- CLIENT LEFT
- ACTIVITY STARTED
- ACTIVITY STOPPED.
MEDIA CREATED
Event logged when the e-meeting room is opened for
the
first user.
MEDIA DISPOSED
Event logged when the e-emeeting room is closed.
Commonly
one or a few minutes after the last user have left the
room.
Syntax:
<timestamp> <event type> <session id> <media
id> <session title> <media title> <service
uid>
CLIENT JOINED
Event logged when a remote client have successfully
connected to this media.
CLIENT LEFT
Event logged when a remote client have disconnected
from a specific media.
Syntax:
<timestamp> <event type> <session id> <media
id> <participant id> <ssrc> <login> <client
address> <client port> [attributes]
ACTIVITY STARTED
Event logged at start of an action triggered by some
user
activity; start sending audio, start sending video, chat
message sent, an action in the whiteboard etc. This event
will have a corresponding ACTIVITY STOPPED event logged,
except for chat messages.
ACTIVITY STOPPED
Event logged at end of an action triggered by some
user
activity; stop sending audio, stop sending video etc.
Syntax:
<timestamp> <event type> <session id> <media
id> <participant id> <client address> <client
port> <server address> <server port> [media
content]
The fields are described in appendix A.
The syntax of a processed log is quite similar to the unprocessed
log, except that the somewhat long and cryptic integer values
have been replaced with proper
date and time formatting, readable login names and soon.
The field and event separators are the same as in the unprocessed
media log.
MEDIA CREATED
MEDIA DISPOSED
<date and time> <event type string> <session
title> '{'<session id>'}' <media title> '{'<media
id>'}' <service uid>
CLIENT JOINED
CLIENT LEFT
<date and time> <event type string> <client
address and port> <session title> {<session id>}
<media title> '{'<media id>'}' <login> '{'<participant
id>'}' <ssrc> <attributes>
ACTIVITY STARTED
ACTIVITY STOPPED
<date and time> <event type string> <client
address and port> <server address and port> <session
title> '{'<session id>'}' <media title> '{'<media
id>'}' <login> '{'<participant id>'}' [recipient]
['{'<recipient id>'}'] [processed media content]
The event fields are described in Appendix B.
.
By default the media logs are written to the log- directory
of the Manager installation. If the media log files are copied
or processed from the log directory while the Manager is still
running, the files may not reflect the current state.
This since the internal I/O buffer of the Manager may not
have been recently flushed. If this is considered not to be
an issue, copying or processing the media log files directly
from the log directory is encouraged.
In addition to direct file access the Manager API can be
used to retreive the media log entries. A short self explanatory
program example have been put together to show how to do this.
See Appendix C.
Included in the server is a utility that post processes
the media logfiles from the intermediate format to more readable
format.
This tool can either be run from a console or used by an
application when accessing the server API. Running the tool
from the console requires a Java VM to be installed as well
as having the server.jar-file included in the CLASSPATH environment
variable of the console.
Since a Java VM is installed with the installation of the
Manager, the quickest way is to change current directory to
the root directory of the Manager and invoke
Windows
> jdk\jre\bin\java -classpath lib\server.jar marratech.emil.util.MediaLogFormatter
log
OSX
> java -classpath .MarratechManager.app/Contents/Resources/Java/server.jar
marratech.emil.util.MediaLogFormatter
Linux
> jdk/jre/bin/java -classpath lib/server.jar marratech.emil.util.MediaLogFormatter
log
If the log-directory resides elsewhere simply replace 'log'
with the path to the current location. All files with the
suffix '_media.log' of the 'log'- directory will be processed
and the result will be printed to the console.
Programmatic access to the tool is shown in the program
example in Appendix C.
The Media logging should be set to rotate log
files at sizes less than 1 GB. Issues have been discovered
after the software was released for sizes superior to 1 GB.
A set of participant attributes. These attributes are explained
in more detail at the end of this appendix.
client address The address of the client side sending socket
given as a 32-bit integer value.
client port
The port number of the client side sending socket given as
a 16-bit integer value.
event type
Event type identifier. The event type is an integer
value in the range 1 through 6. The values maps to the event
type strings as follows; 1 - CLIENT JOINED, 2 - CLIENT LEFT
, 3 - ACTIVITY STARTED, 4 - ACTIVITY STOPPED, 5 - MEDIA CREATED,
6 - MEDIA DISPOSED.
login
The login name of a user. May be null or anonynous
in case the user entered the room without logging in.
Common for public rooms. This is a string value.
media content
Chat message text, web address etc. As of now only
output for the mstarcontrol media that carries the chat information.
The content, if encrypted, is decrypted before logged. The
format of the logged data is highly media dependent. In the
case of the mstarcontrol media the content is logged as a
so
called control bus message. The processing tool will extract
the interesting information from this.
media id
The session unique media identifier given as a 32-bit
integer.
media title
The name or type of a media. For example audio. This
is a string value.
participant id
The identifier of an active user. One user may be
present in serveral sessions and/or multiple times in one
and the same session, each one of these are
represented by a participant. The value is a 64-bit integer.
server address
The address of the server side receiving socket given
as a 32-bit integer.
server port
The port of the server side receiving socket given
as a 16-bit integer.
service uid
The identifier of the hosting service of the Manager.
With this id it is possible to trace from which service, of
a multinode Manager, a logged event orginates. This identifier
consists of two 32-bit integer values separated by a ':'-character
where the first value is the service id and the second is
the node id.
session
An e-meeting room in its active state.
session id
The server unique identifier of a session given as
a 32-bit integer.
session title
The title/name of a session given as a string.
ssrc
Synchronization source. See RFC 3550 for more information.
timestamp
Time when the event occurred output as a 64 bit integer
giving the number of milliseconds past since 1970-01-01.
attributes address
The server address given as a dotted decimal ip address.
cname
Canoncial name of source. See RFC 3550 for more information.
disttype
The distribution type of the media, either multicast
or unicast.
emseid
The identifier of the server internal service handling
the data transport of this media. See
service uid.
marratech.user.agent
Name, version and other information of the client
application. See RFC 2616 for more information.
marratech.user.ssrc
See definition of ssrc above.
marratech.user.name
The full name of the user, possibly also including
title or rank.
marratech.user.remotehost
The host address of the client given as a dotted
decimal ip address.
marratech.user.nickname
Nickname of user.
marratech.user.login
The login name of the user.
marratech.user.remoteuser
Account name of user at remote host. For example
a user may login with one name at the computer where the client
application is run, but with another name when giving the
credentials to enter an e-emeeting room.
See description of attributes in Appendix A.
client address and port
The address of the client side sending socket given
as a dotted decimal ip address follwed by a ':'-character
and the port number of the client side sending socket given
as a 16-bit integer value.
date and time
Date and time with the format yyyy-MM-dd hh:mm:SS.ss
y - year, M - month, d - day, h - hour, m - minute, S - second,
s - millisecond.
Example: 2006-08-31 12:57:51.953
event type string
One of the following; CLIENT JOINED, CLIENT LEFT,
ACTIVITY STARTED, ACTIVITY STOPPED, MEDIA CREATED,
MEDIA DISPOSED. See event type of Appendix A.
login
media id
media title
See respectively descriptions in Appendix A.
recipient
Login of exclusive recipient, or the string 'public'
for media sent to all participants present.
recipient id
The participant id of a recipient or null in case
public.
processed media content
Only present for the mstarcontrol media. Either the
chat text sent or one of the control markers # or ! that indicates
start and stop of user typing.
participant id
session title
session id
See respectively descriptions in Appendix A.
server address and port
The address of the server side receiving socket given
as a dotted decimal ip address followed by a ':'-character
and then the port of the server side
receiving socket given as a 16-bit integer.
service uid
ssrc
See respectively descriptions in Appendix A.
import marratech.emil.access.Bootstrap;
import marratech.emil.platform.PlatformHandle;
import marratech.emil.service.ServiceHandle;
import marratech.emil.service.emse.SessionEngineHandle;
import marratech.emil.util.MediaLogFormatter;
/**
* Example code that shows how to obtain and format
* media log entries output from a session engine
* service.
*
* Created: Thu Mar 23 12:29:49 2006
*
* @author Mikael Persson
* @version $Name: $ $Revision: 1.3 $ $Date: 2006/09/06 15:42:40 $
*/
public class MediaLogTool
{
/**
* Initiates a connection to a remote manager.
*/
public MediaLogTool()
throws Throwable
{
Bootstrap.init();
}
/**
* Closes the connection to the remote manager.
*/
public void dispose()
throws Throwable
{
Bootstrap.dispose();
}
/**
* Retreives a reference to the session
* engine service of the remote system.
*/
private SessionEngineHandle getSessionEngine()
throws Throwable
{
ServiceHandle[] services = Bootstrap.getServiceManager().
getServices( PlatformHandle.CENTRAL, ServiceHandle.SESSION_ENGINE );
return (SessionEngineHandle)(services[0].getServiceEngine());
}
/**
* Prints entire media log available at the server.
*/
private void printEnrichedMediaLog()
throws Throwable
{
//
// fetch all media entries available
//
String[] mediaLogEntries = getSessionEngine().
getMediaLogEntries( 0, Long.MAX_VALUE, true );
//
// post processing
//
mediaLogEntries = MediaLogFormatter.
formatMediaLogEntries( mediaLogEntries );
//
// print it all to the console
//
for( int i = 0; i < mediaLogEntries.length; i++ )
{
System.out.print( mediaLogEntries[i] );
System.out.print("\r\n");
}
}
/**
* Use "java -Dmstar.accessorkit=<accessor.kit file> MediaLogTool"
* in case you need to explicitly specify the location of the
* accessor kit file.
*/
public static void main( String[] args )
{
MediaLogTool mlu = null;
try
{
mlu = new MediaLogTool();
mlu.printEnrichedMediaLog();
}
catch( Throwable t )
{
t.printStackTrace();
}
try
{
mlu.dispose();
}
catch( Throwable t )
{
t.printStackTrace();
}
}
} // MediaLogTool
|
