diff options
author | Tomas Bzatek <tbzatek@redhat.com> | 2013-10-25 14:34:05 +0200 |
---|---|---|
committer | Tomas Bzatek <tbzatek@redhat.com> | 2013-10-25 14:34:05 +0200 |
commit | 6214d015849713f3e91ae33d6c0bfb97de089021 (patch) | |
tree | 76b695220c68e4877d6d800fb1023bf0f115e9db /doc/admin | |
parent | b2493fe1e0afec52e6e78a5a8a3a7877214cdfd9 (diff) | |
download | openlmi-providers-6214d015849713f3e91ae33d6c0bfb97de089021.tar.gz openlmi-providers-6214d015849713f3e91ae33d6c0bfb97de089021.tar.xz openlmi-providers-6214d015849713f3e91ae33d6c0bfb97de089021.zip |
journald: Documentation tweaks and additions
Diffstat (limited to 'doc/admin')
-rw-r--r-- | doc/admin/journald/index.rst | 49 |
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 |