Logger

Overview

This component goal is to centralize the logging of all communication within the Telepathy framework. This prevents the UIs from having to implement their own solution that would end up into having multiple incomplete database.

Telepathy Logger is a session daemon that should be activated whenever telepathy is being used (similar to mission control lifetime). For performance reason, the database is accessible directly through an API instead of D-Bus channel.

Current Status

The repository was recently moved to FreeDesktop git server

It stores its logs to 

 ${XDG_DATA_HOME}/share/TpLogger

which usually expands to at 

 ${HOME}/.local/share/TpLogger/

See specs for more XDG_DATA_HOME details.

Roadmap

0.2.X

Telepathy Logger 0.2 was released after a big redesigned of the external API. The external API is not compatible with previous 0.1.X branch. It as been decided that 0.2.X should maintain API stability for it's own lifetime, which mean 0.3.X will be allowed to break API again.

0.3.X

Internals

Overview

The Logger's main part is an observer, which implements the Observer interface. A client read-only API is published to query the log data base and retrieve log events. A DBus interface is published to configure the observer and retrieve small data.

The observer instance intercepts events and translates them to a log event (TplEvent). The log entry is stored in the default TplLogStore

A client can query using a shared library the logged entries.

How it works

The logger is composed by two main parts:

Observer
which reacts to any raised signal and translates them to log entries
LogManager
which stores log entries using a specific back-end and give the stored data back when requested by clients

When a observed signal is received, the signal's data is processed and transformed to a log entry.

A log entry is an object defining all the interesting part of a log (who, what, when, how, why). A log entry is passed to the LogManager, which transforms it to the selected log format.

Several TplEvent objects will be present, one for each type of log event (ie, for Text interfaces, for Calls, for file trasfers, etc).

Such object extends the base TplEvent class which implements all the common methods to a log event.

Data Flow

Observer (tpl-observer.c) is a GLib object implementing TP's Observer iface.

When observe_channel receives a new channel notification, it waits for the channel (and other objects) to be ready and then, instantiates a TplChannel object -representing a logged channel.

Each channel type is managed by a module (i.e.: text-channel.c for Text channels) which implements a GObject representing the logger's actions/interesting information about the related channel. For channel type "Text" it's TplTextChannel. Each channel type's object (TplTextChannel) is instantiated right after TplChannel - and keeps a reference to it - and recorded in a HashTable with key the DBus channel's object path.

Each channel type module translates the signal data into a TplEvent and will pass the event to the LogManager

TplEvent is a base class for all event, keeping the information related to any log event and a pointer to another object, channel type specific (ie TplLogEntryText for Text channels).

The LogManager will store the log entry into the default log store, currently LogStoreXml.

APIs

Due to D-Bus slowness, it's not a good idea to send big amount of data (logs) through D-Bus to clients requesting it.

The chosen approach is the following:

Use shared library API to access logs directly.

Publish a Logger's D-Bus API in order to configure the logger and accessing the logger for very small amount of data (i.e. last 5-lines chat info).

Library API

It's directly accessed (queried) by client mainly to retrieve big amount of data (logs), read-only. Clients will use the library with queries involving data (log) passing in their results.

It doesn't need to be D-Bus aware, APIs will allow to access log DB (initially plain text, see phase4).

GConf can be used for shared configurations (ie, chosen data back-end).

What to log

TplEvent is the main log event object, which contains a sub-object for the actual log type. Currently TplTextEvent has been implemented to represent Text channels (1-1 and room chats).

Here a list taken from http://people.collabora.co.uk/~danni/telepathy-book/chapter.channel.html of interfaces interesting to be logged:

Almost any event raised by each interface is interesting to be logged.

Log structure

The current default LogStore is LogStoreXml. Its log structure reflects the current empathy's log structure.

A schema for logs might be the following tree:

So the following

would represent that I have two gabble accounts: the first is a work one, for Collabora and I have logs relative to two colleagues of mine. Then I have a Jabber.org account with which I chatted with a friend and a relative of mine.

Each contact will have (no implemented yet) an entry named last_buddy_info containing the last known contat's inforamtion (XMPP's vCard or similar) so that, in case the buddy will be removed from the ContactList, the logger will still have the last known infos about him/her. This entry will be connected to any event related to buddy's information changes.

Each contact will have also a log_data entry which will contain the actual logs. Every known events, according to the logger configuration, will be logged here, including the buddy's information changes also logged in last_buddy_info.