7.4 Chronicle Requirement Pattern

7.4 Chronicle Requirement Pattern

Basic Details

Related patterns:	Transaction
Anticipated frequency:	Between one and twenty requirements
Pattern classifications:	None

Applicability

Use the chronicle requirement pattern to specify that a certain type or range of types of event (occurrence) in the life of the system must be recorded.

Do not use the chronicle requirement pattern to record anything that has a financial role of any kind; use the transaction requirement pattern for them.

Discussion

One dictionary defines a chronicle as "a record or register of events in chronological order." As a verb, it means "to record in or as if in a chronicle." These match perfectly this requirement pattern's uses of the word: a chronicle is a place where events are permanently stored. You can avoid using the word "chronicle" in requirements, though, so you don't have to explain it to your readers. The aim of chronicling is to build up a picture of anything that happens in the day-to-day life of the system and might be of future interest: like built-in closed-circuit television cameras. Its primary use is to assist investigation when something goes wrong-whether it be a software problem, employee fraud, attack by hackers, or hardware or other kind of failure. Chronicles can also yield a wide range of statistics, based on the volumes of different types of events.

This requirement pattern uses the terms event and occurrence interchangeably to mean anything that occurs within the system while it's running and which the system is aware of and is able to act upon. We can chronicle any event (occurrence)-which means pretty much whatever we choose to; it's not restricted to events that trigger some kind of system action. Events can include database updates, errors detected by the system, user actions, milestones in system processes (such as starting up and shutting down), and passing preset thresholds (such as when free disk space goes below a certain level). We also use the verbs to record and to store when talking about what we do with an event; it means the permanent storage of information about the event, which is to remain unmodified and unmodifiable (a faithful snapshot of the event).

Anything that's recorded in a transaction (in the sense used by the transaction requirement pattern) needn't be recorded in a chronicle as well. Conversely, a chronicle requirement merely states that an event must be recorded, not how-so it's quite acceptable to record it in the form of a transaction (provided it is never subsequently modified).

The key features of a chronicle are that it must be:

1. Chronological It records event in the order in which they happened.

2. Faithful It records exactly what happened. Record the details correctly, and don't let them be tampered with afterwards.

3. Complete It records all events of any type being chronicled, because to record some but not others would be misleading. Also, don't allow events to be deleted.

4. Reliable It is not susceptible to system failure. Among other things, this prevents a wrong-doer from covering their tracks by causing the system to crash.

This requirement pattern makes no judgment about how many distinct chronicles a system has: it might put everything in one, or it might use different chronicles for different things (or separate them for other reasons, such as per company in a multi-company system); that's an implementation matter. Chronicle requirements should do likewise. Nor do we stipulate in what form chronicles are to be stored (such database tables or flat files), though the "Extra Requirements" section suggests demands that may render some forms unacceptable. That's one reason why we don't use the terms "log" or "logging" here, because it might lead your readers (especially developers) to make inappropriate assumptions-both about what does and doesn't belong in a log and about the implied use of a logging product (which might in fact not satisfy our requirements). Use the words "log" and "logging" in requirements if you choose, but bear in mind that this could influence the implementation by implying a particular kind of solution. For similar reasons, we don't talk about "audit trails," because readers might interpret that in different ways.

It's useful to recognize the difference between occurrences that are related to a living entity and those that aren't, because of their relative volumes. (We'll have a lot more of the former.) Think about how many occurrences of each type are likely to occur.

It's possible (and often convenient) to incorporate the need to record each use of a function in the requirement for that function, but strictly speaking, they are separate requirements (as demonstrated by the fact that verifying the resulting records is a separate testing step). Writing a separate requirement also prompts you to give proper thought to what information should be recorded. You can also write a chronicle requirement that applies to a set of functions. (This, too, sounds like lumping separate requirements together, but they are all of the same nature. It's better to add several apples together than an apple and an orange.) Make a conscious decision at the start of the requirements specification process about which approach you wish to take. Being consistent throughout has the benefit of reducing the chances of some kinds of chronicle entries being neglected.

Individual chronicle requirements concern what events are recorded and what information is recorded about each one. (Functions that enable us to make use of this information are covered in the "Extra Requirements" section later in this pattern.)

Content

A chronicle requirement should contain:

1. The type(s) of occurrence to record A chronicle requirement can specify the recording of a specific type of event or the recording of a range of types of events-in ways that can be defined quite broadly. It's attractive to be specific, but in doing so, we risk both missing certain things and also causing an explosion in the number of requirements. The best answer is to specify classes of events (defining their scope in terms of criteria that let someone test whether something fits or not), and if necessary, write another chronicle requirement for each specific type of event that we definitely want recorded.

   A system cannot record things that it cannot perceive, so don't ask it to. Recording all break-ins and unauthorized access, for example, is impossible: a system can only record those it detects.

2. The information to record about each occurrence Every occurrence pertaining to a user action must include the ID of the user. Every one reflecting a change in data should enable both before and after values to be determined (which doesn't necessarily mean storing both in the change itself, so long as both can be obtained from somewhere-such as obtaining the before value from the previous change). Every one pertaining to an organization must identify that organization. Every one pertaining to a server machine must identify that machine.

3. Severity (Optionally.) If the occurrence indicates a problem, the severity tells how serious it is. Either identify a severity value defined in a separate severity scheme requirement (as explained in the "Extra Requirements" section later in this pattern), or describe it in general terms (to allow it to be mapped to a formal severity level when they are defined later). If you say nothing about severity, it means you're happy for it to be decided later, either by the development team or by whoever configures the system before it goes into production. If the occurrence is clearly not an error, don't mention its severity.

   In some cases, it's appropriate for the severity to depend not just on the type of event but also on one or more other values. For example, the severity of a low disk space event might become more serious as the free space dwindles.

Template(s)

Open table as spreadsheet

Summary	Definition
Record «Occurrence type(s) summary»	Every «Occurrence type(s) description» shall automatically be recorded. For each, the following shall be recorded: Date and time «Occurrence detail 1» «Occurrence detail 2» … [Each such event shall be treated as having a severity of «Severity description».]

Example(s)

A relatively extensive list of example requirements is given here to identify a number of types of events that a typical commercial system might want to chronicle and to demonstrate a few variations in approach. As a result, there is a degree of overlap and consequently repetition in these requirements.

Open table as spreadsheet

Summary	Definition
Store all order events	Every event that occurs during the life of an order shall be stored permanently. For each such event, at least the following information shall be recorded: Type of event Details of change (which will vary from one type of event to another) Date and time of change User ID of person who made the change (if relevant) User ID of person who approved the change (if relevant) Note that there is no implication that all events are stored in the same way or in the same place.
Record significant user actions	Every user action of business significance shall be recorded. The caveat "of business significance" is included to filter out trivial actions such as navigating the system's user interface. Nevertheless, even actions of small business significance still fall within the scope of this requirement. This requirement shall be read as including all the following types of actions: Use of any function described in this specification. Anything that causes a database change. An employee viewing or changing any sensitive data, including a customer's or an employee's details. A user logging in or logging out, including each unsuccessful attempt to log in. A system operator starting up or shutting down parts of the system, or changing system operational parameters (whether permanently or temporarily) (Some actions fall into more than one of these categories.) The information recorded for any such action shall include at least the following (when, who, what): Date and time. The identity of the user who performed the action (user ID and company ID). Identifying the company is particularly important if action affecting one company is taken by an employee of another (for example the system operating company's action affecting a Web shop company). Details of the action. Note that this requirement does not suggest that all actions are stored in the same way or in the same place. If a particular type of transaction is stored in its own database table, that would suffice, provided it recorded the details listed. Note also that nothing is said about which details of the action are to be recorded-and we do not demand that all details be recorded. This is left for resolution on a case-by-case basis.
Record significant system events	Every significant system event shall be recorded. By "significant system event," we mean things that affect the system's availability and important actions started on the initiative of the system itself-plus any other things that are worthy of showing on the system events report. These include (but are not limited to): Startup and shutdown of system components (such as server machines) Failure of any system component or interface The passing of any defined system threshold, including measures of performance and available resources (for example, to report reduction of available disk space to less than a critical level) This requirement excludes events that, by their very nature, are incapable of being recorded by the system (such as failure of the system itself). The information recorded for any event shall include at least the following (when, who, what): Date and time The identity of the system component in which the event occurred Details of the event
Record access to sensitive data	Each successful access by a user to an item of data deemed sensitive shall be recorded. "Sensitive data" is not defined. The information to be recorded shall include the date and time of access, the ID of the user, and details of what data was requested. (Note that unsuccessful accesses are covered by the next requirement and are not to be recorded again under the auspices of this requirement-to avoid recording the same event twice.)
Record unsuccessful data access	Each unsuccessful attempt by a user to access an item of data shall be recorded. This type of event shall be treated as having a low severity.
Record failed user actions	Each failed attempt by a user to perform an action shall be recorded. (This requirement excludes unsuccessful attempts to access data, which is covered by the previous requirement.) This type of event shall be treated as having a low severity.
Record errors	All error conditions detected by the system shall be recorded. Validation errors and other minor conditions pertaining to a single user, that can occur through normal use of the system and which are reported directly to the user, are expressly excluded from this requirement. It shall be possible to assign a severity level to each type of error.
Record security violations	All security violations that the system detects shall be recorded. Every security violation shall be regarded as serious, but some kinds could be more serious than others.
Record incorrect password entry	Each entry of an invalid password (or any other secret information used to authenticate a user) shall be recorded. This requirement applies to every function that asks a user to enter their password or other secret information.
Record configuration changes	Each change to configuration parameters shall be recorded. For each change, the following shall be recorded: The before image. (The after image is not explicitly recorded for the change, because it is held in either the current value or the before image of the next change.) The ID of the user making the change. The date and time of the change.
Record software changes	Each change to the software loaded on production server machines shall be recorded. This covers both server software and software which is available to be downloaded to client machines. The information recorded shall include what was installed and what version.
Record number of active users	The system shall periodically record the number of active users. The frequency at which this is to happen shall be a configuration parameter.
Record report run request	Each request to run a report shall be recorded. At least the following shall be recorded: User ID of the requester. Date and time of the request. Report name. Report selection criteria. (That is, the parameters that control the report and determine what information it shows.) This requirement serves two purposes: first, to make it possible to see which users requested what information, and second, for report usage analysis-to facilitate study of which reports are used most frequently and which are used rarely or never.
Record report design changes	The addition of a new report definition and any change to an existing report definition shall be recorded.

Extra Requirements

There are various types of extra requirements that can be specified for chronicling. They are all easier to apply across the board to all chronicling in the system (or selected parts of it), rather than following on from an individual chronicle requirement. These types of extra requirements are:

1. Access control Who's allowed to see what in chronicles? This topic appears at the top of this list because the others need to take it into account-and access control requirements can have a significant bearing on what kinds of solutions are acceptable.

2. Common chronicle features What characteristics do we want our chronicles to demonstrate? The most important are the key features described in the "Discussion" section earlier in this pattern: to be chronological, faithful, complete, and reliable.

3. Chronicle view functions There's no point in creating chronicles if there's no way to see what's in them. See the "Chronicle View Functions" section that follows.

4. Severity levels For chronicles to work properly, the severity levels used in all events must be consistent: it's unacceptable for minor events to look as though they're severe. We can write requirements to define severity levels and others to assign levels to different types of events.

5. Purging chronicles For how long should chronicle data be kept? It's possible to retain different types of events for different lengths of time-particularly if they are stored in different chronicles-but this makes it harder to interpret what happened during those periods of time affected. To make sense of them, we certainly need to keep track of the date from which each type of event is present, so it's possible to tell whether omission of data could be due to it having been removed (which is covered in the third example requirement in the "Common Chronicle Features" section that follows).

6. Archiving chronicles If chronicles are archived and loaded into another database for study (let's say a "reporting system" database), care must be taken if actions on the secondary database are chronicled-because these events could pollute the chronicles. The answer is to have two distinct sets of chronicles that are strictly kept apart. If you're doing anything along these lines, carefully think through what might transpire, and specify suitable requirements to prevent trouble.

7. Triggering other actions It's useful to be able to notify people when a severe event occurs. The best way to do this is to build it into the chronicle mechanism itself, so it works for any type of event. This could be extended to allow other kinds of actions to be triggered by events. Work out what you want, and write requirements for it.

8. Turning chronicling on and off Recording events in chronicles can affect the system's performance, especially when recording a high volume of events. It can be useful to turn the chronicling of certain types of events on and off. Allow this only for non-error events. Being able to switch off low-volume events serves no purpose.

   Switching chronicling on and switching it off are themselves events that must be recorded, because they affect what we can expect to see in chronicles. Without doing so, we could never tell whether the absence of an event was due to an event not occurring or because chronicling was off at the time. (This point is dealt with by the third example requirement in the "Common Chronicle Features" section that follows.)

The first four of these topics are covered in more detail in the following subsections.

Chronicle Access Control

If we control which information each user can access, the same restrictions should apply when that information finds its way into chronicles. After all, we're wasting our time if a user can bypass access control restrictions by examining events recorded in chronicles. (This is in addition to control over who can access the chronicle view functions themselves.) Strangely, this loophole is common in systems, though rarely recognized as such (often because systems administrators keep chronicles to themselves, and chronicles commonly lack detailed information). Here's a requirement for plugging the gap:

Open table as spreadsheet

Summary

Definition

Access control for records of events

Any information recorded about an event shall be subject to access control rules at least as strong as those that apply to the original information. This requirement applies regardless of the form in which event information is stored (including flat files and "logs"). For example, if a user is not allowed to access a particular customer's details, they shall not be able to view details of an event that records changes to that customer's details (though it is acceptable for them to be made aware of the presence of the event).

The explicit reference to "logs" is just so there can be no misunderstandings on this point. This requirement might look innocuous, but it's likely to have a major impact on the implementation of chronicling: it makes it appreciably more complex and rules out many off-the-shelf products. So don't ask for "proper" access control of this sort unless you really need it-because it won't endear you to whoever has to implement it.

Common Chronicle Features

We can only expect chronicles to be chronological, faithful, complete, and reliable if we ask for these things in requirements, as these examples do:

Open table as spreadsheet

Summary	Definition
Event date and time	Every event recorded shall store the date and time at which it occurred. The event date and time shall always be determined by the system itself; any date and time originating externally is to be considered unreliable for this purpose.
Event records unmodifiable	No user (including a system administrator) shall be able to modify in any way, or to delete, any record of an event.
Event record sequence number	Every event recorded shall be assigned a sequential number that shall be one greater than the previous event recorded in the same place. The purpose of this requirement is to be able to detect whether an event has been deleted.
Record actions affecting event recording	Any action that affects which events are recorded (or which are still present-that is, not yet archived) shall itself be recorded. This requirement covers, but is not limited to, the following actions: Switching the recording of any types of event on or off Removing (archiving) any recorded events (due to their longevity) The purpose of this requirement is to make it possible to tell both which types of events are liable to be present at any point in time and also for how far back in time events are present.
Record events in database	Any record of an event shall be stored in a database. If the event itself records a database change, the record shall be in the same database and performed in the same database transaction. The purpose of this requirement is to provide protection against the failure of a disk drive.

Chronicle View Functions

Chronicles that store a wide variety of events are a rich resource that can tell you much about what the system-and consequently the business-has been doing. Functions for viewing chronicles can be divided into the detailed-which show individual events (and can be used for investigative purposes)-and the statistical, which summarize them into totals (for various purposes-including management, marketing, and system load analysis).

The number of chronicles a system has, and what events are recorded in which one, is an implementation matter that doesn't concern the requirements. Consequently, requirements for chronicle view functions cannot distinguish separate chronicles; they must limit themselves to the types of events that are to be shown. However, it is possible for chronicle view functions to include chronological-based information-especially transactions-from elsewhere in the database to give a more complete picture of what was going at the time. The case for doing this is strong if it's a close call whether to regard something as a transaction or a chronicle event.

Open table as spreadsheet

Summary

Definition

Recorded event inquiry

There shall be an inquiry that lists recorded events that match given selection criteria. The selection criteria shall include (but need not be limited to): Start and end date/time range Customer ID Whether to include customer-related events (yes or no) User ID (to select actions performed by this user) Company ID Machine ID Event type Severity level (to show all events with this or higher severity) The user shall be able to supply or omit whichever criteria they wish. Any item of information to which the user does not have access shall not be displayed. The user shall be warned if particular types of events requested are unavailable for some or all of the time period being shown (due to their having been archived).

Severity Levels

Should a requirements specification define event severity levels? Defining a complete set constrains the implementation, but defining none makes it hard to describe the severity of a type of event in the requirements. A middle course is best: define a few fundamental severity levels, but allow the implementation to have more. The bare minimum severity levels are "normal" and "severe." Normal is for something that can be expected to happen during the normal running of the system, which is not an error. Severe is for a problem that warrants attention by a person. But you should include at least one level in between these two. Choose different names for the levels if you wish. When devising severity levels, consider differentiating between errors that affect just a single entity (such as one customer) and those that affect the system as a whole-and have separate severity levels for the two types. (The example requirement that follows doesn't do this.) Write a requirement that identifies the severity levels you want. Every definition of a severity level must include a readable description of its meaning.

Take care when assigning the severity level of a type of event. Don't let severe events be neglected, but don't "cry wolf," either. The volume of severe events must be kept small, or their impact will be lost.

Chronicle requirements can specify the severity of particular types of events, but their severities can be defined in other ways-in particular, by making them configurable. This adds a degree of flexibility, but changing severity levels once the system is in production is potentially dangerous and can lead to confusion.

Open table as spreadsheet

Summary	Definition
Event severity levels	The system shall support at least the following event severity levels (or their equivalents): Normal-nothing is wrong. Warning-worth bringing to someone's attention, but no action is required. Moderate-corrective action is needed, but it's not urgent. Severe-immediate action is needed. Catastrophic-the system should be shut down immediately.
Event type severity	Each type of event that can be recorded shall have a severity defined for it.

Considerations for Development

Performance is a major consideration. It's straightforward enough to develop chronicle capabilities but much harder without having an appreciable impact on the processing time of the occurrence being recorded. If possible, use chronicle software already written for this purpose-provided you can find such software that satisfies all the requirements laid down.

Estimate the likely volume of each class of events. Base it on the sizing model, if there is one (and perhaps extend the model). Consider keeping high-volume and low-volume chronicles separate from each other.

Record all occurrences using a timestamp generated by the system itself- because if it came from elsewhere, we shouldn't trust it.

Considerations for Testing

Having as many as possible of a system's activities recorded is of great assistance during testing, because these records provide invaluable information about what happened in the system. So, when reviewing requirements, testers should press for as many types of events as possible to be recorded.

You should cause all the types of events for which chronicle requirements are specified. This can be difficult, especially for obscure error conditions. Insisting that every conceivable condition must be tested is rather picky in typical commercial systems; if you insist upon it, one option is to ask developers to modify the software to allow it to simulate them.

Separate broad-scope chronicle requirements (those that ask for a range of occurrences to be chronicled-according to specified criteria) from specific chronicle requirements; it's clear what to test for the latter. But the former are open-ended; to test such a requirement properly, identify within the delivered system all the functions and occurrences that satisfy the criteria, and then test each one in turn. Both the identifying and the testing could be very onerous.