Redfish Event Logging in bmcweb

This guide is intended to help developers add new messages to the bmcweb Redfish event log.

Redfish Message Objects can be represented in different ways. In bmcweb, we have chosen to use Message Registries with Message Objects that are referenced using a MessageId and MessageArgs fields.

Additional details can be found in the Redfish Specification.

Message Registries

The first step when adding a new message to the Redfish event log is to find or add an appropriate message in a Message Registry.

The bmcweb Message Registries are located under "\redfish-core\include\registries" in source code, and they can be examined through Redfish under "/redfish/v1/Registries".

If an appropriate message exists, note the

1. Title of the Message Object (required as the MessageKey in the MessageId).
2. Args (notated as "%x") in the "Message" field (required for the MessageArgs).

If an appropriate message does not exist, new messages can be added as follows:

1. Choose a Message Registry for the new message
2. Choose a MessageKey to use as the title for the new Message entry
3. Insert a new Message entry (preferably with the title in alphabetical order)
4. Add a description and resolution
5. Set the severity to "Critical", "Warning", or "OK"
6. Define the message with any necessary args
7. Set the numberOfArgs and paramTypes to match the message args

Logging Messages

Logging messages is done by providing a Redfish MessageId and any corresponding MessageArgs to bmcweb.

A Redfish MessageId is represented in this format:

RegistryName.MajorVersion.MinorVersion.MessageKey

bmcweb will search the specified Message Registry for the MessageKey, construct the final message using the MessageArgs, and display that in the event log.

journal-based Redfish Logging

The journal is the current mechanism used to log Redfish Messages. bmcweb looks for two fields in the journal metadata:

• REDFISH_MESSAGE_ID: A string holding the MessageId
• REDFISH_MESSAGE_ARGS: A string holding a comma-separated list of args

These fields can be added to a journal entry using either the phosphor::logging::entry() command or directly using the sd_journal_send() command.

Examples

Logging a ResourceCreated event

The Resource Event Message Registry holds the ResourceCreated message:

{
    "ResourceCreated": {
        "Description": "Indicates that all conditions of a successful
        creation operation have been met.",
        "Message": "The resource has been created successfully.",
        "NumberOfArgs": 0,
        "Resolution": "None",
        "Severity": "OK"
    }
},

Since there are no parameters, no MessageArgs are required, so this message can be logged to the journal as follows:

phosphor::logging::log<log::level>(
        "journal text",
        phosphor::logging::entry("REDFISH_MESSAGE_ID=%s",
        "ResourceEvent.1.0.ResourceCreated"));

or

sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", <LOG_LEVEL>,
                "REDFISH_MESSAGE_ID=%s",
                "ResourceEvent.1.0.ResourceCreated", NULL);

Logging a ResourceErrorThresholdExceeded event

The Resource Event Message Registry holds the ResourceErrorThresholdExceeded message:

{
    "ResourceErrorThresholdExceeded": {
        "Description": "The resource property %1 has exceeded error
        threshold of value %2. Examples would be drive IO errors, or
        network link errors.",
        "Message": "The resource property %1 has exceeded error
        threshold of value %2.",
        "NumberOfArgs": 2,
        "ParamTypes": [
            "string",
            "value"
        ],
        "Resolution": "None.",
        "Severity": "Critical"
    }
},

This message has two parameters, %1 and %2, as indicated in the "NumberOfArgs" field. The meaning and types of these parameters are derived from the "Message" and "ParamTypes" fields in the Message Registry.

In this example, %1 is a string holding the property name and %2 is a number holding the threshold value.

The parameters are filled from a comma-separated list of the MessageArgs, so this message can be logged to the journal as follows:

phosphor::logging::log<log::level>(
        "journal text",
        phosphor::logging::entry("REDFISH_MESSAGE_ID=%s",
        "ResourceEvent.1.0.ResourceErrorThresholdExceeded"),
        phosphor::logging::entry("REDFISH_MESSAGE_ARGS=%s,%d",
        "Property Name", propertyValue));

or

sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", <LOG_LEVEL>,
                "REDFISH_MESSAGE_ID=%s",
                "ResourceEvent.1.0.ResourceErrorThresholdExceeded",
                "REDFISH_MESSAGE_ARGS=%s,%d", "Property Name",
                propertyValue, NULL);