journald: Documentation tweaks and additions

1 files changed, 44 insertions, 5 deletions

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 <http://freedesktop.org/wiki/Software/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<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<LMI-JournalMessageLog>` class
+reference for detailed description of available iterator-related methods.
+Implemented iterator methods are :ref:`PositionToFirstRecord()<LMI-JournalMessageLog-PositionToFirstRecord>`,
+:ref:`PositionAtRecord()<LMI-JournalMessageLog-PositionAtRecord>`,
+:ref:`GetRecord()<LMI-JournalMessageLog-GetRecord>` and
+:ref:`CancelIteration()<LMI-JournalMessageLog-CancelIteration>`. Only relative movement
+is supported by the :ref:`PositionAtRecord()<LMI-JournalMessageLog-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()<LMI-JournalMessageLog-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()<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