Auxiliary Classes

nagiosplugin’s auxiliary classes are not strictly required to write checks, but simplify common tasks and provide convenient access to functionality that is regularly needed by plugin authors.

Note

All classes that plugin authors typically need are imported directly into the nagiosplugin name space. For example, use

import nagiosplugin
# ...
with nagiosplugin.Cookie(path) as cookie:
   # ...

to get a cookie.

nagiosplugin.cookie

Persistent dict to remember state between invocations.

Cookies are used to remember file positions, counters and the like between plugin invocations. It is not intended for substantial amounts of data. Cookies are serialized into JSON and saved to a state file. We prefer a plain text format to allow administrators to inspect and edit its content. See LogTail for an application of cookies to get only new lines of a continuously growing file.

Cookies are locked exclusively so that at most one process at a time has access to it. Changes to the dict are not reflected in the file until Cookie.commit() is called. It is recommended to use Cookie as context manager to get it opened and committed automatically.

class nagiosplugin.cookie.Cookie(statefile=None)

Creates a persistent dict to keep state.

After creation, a cookie behaves like a normal dict.

Parameters:statefile – file name to save the dict’s contents

Note

If statefile is empty or None, the Cookie will be oblivous, i.e., it will forget its contents on garbage collection. This makes it possible to explicitely throw away state between plugin runs (for example by a command line argument).

__enter__()

Allows Cookie to be used as context manager.

Opens the file and passes a dict-like object into the subordinate context. See open() for details about opening semantics. When the context is left in the regular way (no exception raised), the cookie is commit()ted to disk.

Yields:open cookie

close()

Closes a cookie and its underlying state file.

This method has no effect if the cookie is already closed. Once the cookie is closed, any operation (like commit()) will raise an exception.

commit()

Persists the cookie’s dict items in the state file.

The cookies content is serialized as JSON string and saved to the state file. The buffers are flushed to ensure that the new content is saved in a durable way.

open()

Reads/creates the state file and initializes the dict.

If the state file does not exist, it is touched into existence. An exclusive lock is acquired to ensure serialized access. If open() fails to parse file contents, it truncates the file before raising an exception. This guarantees that plugins will not fail repeatedly when their state files get damaged.

Returns:Cookie object (self) Raises ValueError:  if the state file is corrupted or does not deserialize into a dict

Cookie example

Increment a connection count saved in the cookie by self.new_conns:

with nagiosplugin.Cookie(self.statefile) as cookie:
   cookie['connections'] = cookie.get('connections', 0) + self.new_conns

Note that the new content is committed automatically when exiting the with block.

nagiosplugin.logtail

Access previously unseen parts of a growing file.

LogTail builds on Cookie to access new lines of a continuosly growing log file. It should be used as context manager that provides an iterator over new lines to the subordinate context. LogTail saves the last file position into the provided cookie object. As the path to the log file is saved in the cookie, several LogTail instances may share the same cookie.

class nagiosplugin.logtail.LogTail(path, cookie)

Creates new LogTail context.

Parameters:

• path – path to the log file that is to be observed
• cookie – Cookie object to save the last file position

__enter__()

Seeks to the last seen position and reads new lines.

The last file position is read from the cookie. If the log file has not been changed since the last invocation, LogTail seeks to that position and reads new lines. Otherwise, the position saved in the cookie is reset and LogTail reads from the beginning. After leaving the subordinate context, the new position is saved in the cookie and the cookie is closed.

Yields:new lines as bytes strings

LogTail example

Calls process() for each new line in a log file:

cookie = nagiosplugin.Cookie(self.statefile)
with nagiosplugin.LogTail(self.logfile, cookie) as newlines:
   for line in newlines:
      process(line.decode())