From 6214d015849713f3e91ae33d6c0bfb97de089021 Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Fri, 25 Oct 2013 14:34:05 +0200 Subject: journald: Documentation tweaks and additions --- doc/admin/journald/index.rst | 49 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 44 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/admin/journald/index.rst b/doc/admin/journald/index.rst index ddb93e4..8834c5e 100644 --- a/doc/admin/journald/index.rst +++ b/doc/admin/journald/index.rst @@ -4,6 +4,12 @@ OpenLMI Journald Provider documentation OpenLMI Journald is a CIM provider exposing `systemd `_ journald log records and basic means of iteration and log writing. +Journald is a daemon working with journals. Journal is a log, a set of log +records, chronologically ordered. Records are structured, able to carry multiple +(custom) data fields. By implementation, journald is able to work with multiple +(separate) journals but we use the mixed way for the moment, which is typical +in production use. + Classes used by the provider were chosen to mimic the sblim-cmpi-syslog provider set of classes allowing drop-in replacement in production tools. We haven't been able to find a profile it conforms to though. There's a related DMTF profile @@ -38,11 +44,44 @@ simply too much for the CIMOM, exceeding memory and the resulting XML reply limits. An artificial limit has been set, currently to 1000 most recent records. This -limit is set by the ``JOURNAL_MAX_INSTANCES_NUM`` define in ``Journal.h`` source -file. - -The :ref:`LMI_JournalMessageLog` class provides several -methods for iterating and seeking in a complete log. +limit is defined by the ``JOURNAL_MAX_INSTANCES_NUM`` define in ``Journal.h`` +source file. Please use iterators instead to get access to all records. + + +Iteration and iterators +----------------------- + +Iteration is a different way of getting data through the log records. Comparing +to the usual instance enumeration, this is a sequential-like access with ability +to seek back and forth in the journal. Retrieving individual records might be +slower than direct random access though memory consumption is kept on a low +level. + +Please check the :ref:`LMI_JournalMessageLog` class +reference for detailed description of available iterator-related methods. +Implemented iterator methods are :ref:`PositionToFirstRecord()`, +:ref:`PositionAtRecord()`, +:ref:`GetRecord()` and +:ref:`CancelIteration()`. Only relative movement +is supported by the :ref:`PositionAtRecord()` method. + +A key element of the iteration process is the iteration identifier that is +typically passed in the methods listed above. Only the :ref:`PositionToFirstRecord()` +method is able to create new iteration identifier without the need of specifying +one. + +Iteration identifiers are specific to the provider and are opaque. They're are +persistent to some extent, surviving unexpected CIMOM runtime cleanup. The only +requirement for persistency to work is the journal record the iterator identifier +previously pointed to to be available at the time the iterator is reused. +I.e. it won't survive log rotation. + +A remark for the :ref:`LMI_JournalMessageLog.GetRecord()` +method: the outgoing RecordData argument carries string data encoded in an array +of uint8 elements as defined by the model. This is quite limiting and also still +very free-form on the other hand. To conform the definition, we put UTF-8 encoded +string split by characters in the array and is up to clients to decode it back +to a readable form. New log records writing security concerns -- cgit