Log module retrieves log entries from system-wide log facilities, or specified log files.

Module name: “log”

Module version: 1.0

See Modules - Common API for general module description.

Module parses log files based on following criteria:
- what log files (defaults to /var/log/messages and /var/log/syslog)
- age of log entries (so one can retrieve logs from previous 4 days, or a month)
- tags (similar to keywords) none, one or multiple. If none, everything matches; if one, matching match; if more than one, either their union or intersection match (see next bullet)
- union or intersection, union being the default. Even if union is selected, returned log entries have matching tags attached; UI can group or intersect them in the cache, reducing number of round trips.

As module processes log files, each entry is assigned multiple tags. First tag will be a process name that logged entry. Second is a PID (if supplied). Simple algorithm tries to extract as much of tags as possible. Those tags are matched against named groups of keywords, and if found, group name is attached to log entry as yet another tag. Purpose of tags is to group log entries.
Search is performed on these tags.
For example, ccsd log entry will get assigned “ccsd” and “cluster” tags; GFS entries will get “gfs”, “storage” and “cluster” tags; dlm entries will get “dlm”, “cluster” and “kernel” tags, ...

Defined tag groups:
- “cluster” - matches all log entries from Cluster Suite (includes “cluster service manager”, cman, gulm, ccsd, GFS and LVS, among others)
- “cluster service manager” - matches all log entries from Cluster Service Manager (clurgmgr for now)
- “lvs” - matches all log entries from Linux Virtual Server: ipvs, ipvsadm, piranha, ...
- “storage” - matches all log entries about storage
- “selinux” - matches selinux log entries (audit, pam_*, selinux)

Log entry format:

<logentry domain="what it is about" pid=”process ID” age="age in seconds" msg="log message">
<match tag=”matching tag1”/>
<match tag=”matching tag2”/>
</logentry>

- “age” - age of entry in seconds (relative time was chosen, so that UI can display logs using user's time settings, and to remedy differences in clock settings)
- “pid” - PID that generated this log entry. Not every process logs its PID, so “pid” attribute might end up empty
- <match> - a tag this entry was successfully matched against (there could be multiple, eg. if search was performed on “kernel” and “cluster”, dlm log will be matched against both – could be used by UI to group or to find intersections within result – eg. “cluster” and “kernel”).

Functions:

• APIs

  Get supported API versions. See Modules - Common API for description.

• get

  Retrieve union of matching log entries that are at most 'age' seconds old. To retrieve intersection, use “intersection” variable. If no tags are specified, all entries of matching age are returned.
  Log files to be searched are, optionally, specified using “paths” variable. Files rotated by logrotate are picked up automatically, eg. if /var/log/cron was specified, /var/log/cron.1 2 3 ... will get picked up automatically.

  Input variables:
  - “age” (int) – maximum age, in seconds, of log entries to retrieve
  - “tags” (list_str) – optional, list of tags whose matching log entries are to be retrieved
  - “intersection” (boolean) – optional (default=false), return intersection instead of union
  - “paths” (list_str) – optional, list of paths to log files or directories. Directories are searched recursively. Relative and non-existent paths are discarded. If not specified, or empty, /var/log/messages and /var/log/syslog are processed (along with .1 .2 .3 ... extensions).

  Output variables:
  - “log_entries” (list_xml) – list of matching entries (see above for <logentry/> format)

  On failure:
  - No special errors defined, only generic ones might get returned