Subversion Repositories oidplus

OIDplus Logger Maskcodes

========================

What is a mask code?

--------------------

A "mask code" gives information about the log event.

It contains:

1. The severity (info, warning, error, critical)

2. In which logbook(s) the event shall be placed

Example:

Let's imagine the following event:

    "Person 'X' moves from house 'A' to house 'B'"

This event would affect:

- Person 'X'

- House 'A'

- House 'B'

Instead of logging into 3 logbooks separately, you would create a mask code that tells the system to put the message

into the logbooks of person X, house A, and house B.

Syntax rules

------------

In the code, mask codes would look like this:

	OIDplus::logger()->log("[INFO]OID(%1)", "RA of object '%1' changed from '%2' to '%3'", $oid, $old_ra, $new_ra);

As you can see, the maskcode and message can be parameterized like `sprintf()` does,

but with the difference that `%1`, `%2`, `%3`, ..., is used instead of `%s`.

Please note that the event message is not enclosed in `_L(...)`, because log-messages are always written in English,

and not in the front-end language of the user.

At the beginning of each mask code, you must define a severity, which is written in square brackets.

Valid severities:

- `[OK]`: Rule of thumb: YOU have done something and it was successful.

- `[INFO]`: Rule of thumb: Someone else has done something (that affects you) and it was successful.

- `[WARN]`: Rule of thumb: Something happened (probably someone did something) and it affects you.

- `[ERR]`: Rule of thumb: Something failed (probably someone did something) and it affects you.

- `[CRIT]`: Rule of thumb: Something happened (probably someone did something) which is not an error, but some critical situation (e.g. hardware failure), and it affects you.

A mask code can have multiple components which are split into single codes using `+` or `/`, e.g. `OID(x)+RA(x)` would

be split to `OID(x)` and `RA(x)` which would result in the message being placed in the logbook of OID x,

and the logbook of the RA owning OID x.

If you have a mask code with multiple components,  you don't have to place the severity for each component.

You can just leave it at the beginning. For example, `[WARN]OID(x)+RA(x)` is equal to `[WARN]OID(x)+[WARN]RA(x)`.

You can also put different severities for the components, e.g. `[INFO]OID(x)+[WARN]RA(x)` would be a info for the OID,

but a warning for the RA.

If you want to make the severity dependent on wheather the user is logged in or not,

prepend `?` or `!` and use `/` as delimiter

Example: `[?WARN/!OK]RA(x)` means: If RA "x" is not logged in, it is a warning; if it is logged in, it is an success.

With this technique you can achive that the RA gets warned if an admin changed some of their OIDs,

but receives an OK-Event if they did the change.

`OID(x)` means: Save the log entry into the logbook of: Object "x".

`SUPOID(x)` means: Save the log entry into the logbook of: Parent of object "x".

`OIDRA(x)!` means: Save the log entry into the logbook of: RA of object "x".

`OIDRA(x)?` means: Save the log entry into the logbook of: Logged in RA of object "x". If it is not logged in, nothing will be logged.

`SUPOIDRA(x)!` means: Save the log entry into the logbook of: RA that owns the superior object of "x".

`SUPOIDRA(x)?` means: Save the log entry into the logbook of: Logged in RA that owns the superior object of "x". If it is not logged in, nothing will be logged.

`RA(x)!` means: Save the log entry into the logbook of: RA "x".

`RA(x)?` means: Save the log entry into the logbook of: Logged in RA "x". If it is not logged in, nothing will be logged.

`A!` means: Save the log entry into the logbook of: The admin.

`A?` means: Save the log entry into the logbook of: The logged in admin. If it is not logged in, nothing will be logged.

Implementation

==============

You can find the implementation in `includes/classes/OIDplusLogger.class.php`.