1# Redfish Event Logging in bmcweb 2 3This guide is intended to help developers add new messages to the bmcweb 4Redfish event log. 5 6Redfish Message Objects can be represented in different ways. In bmcweb, we 7have chosen to use Message Registries with Message Objects that are referenced 8using a MessageId and MessageArgs fields. 9 10Additional details can be found in the 11[Redfish Specification](http://redfish.dmtf.org/schemas/DSP0266_1.6.1.html). 12 13## Message Registries 14 15The first step when adding a new message to the Redfish event log is to find 16or add an appropriate message in a Message Registry. 17 18The bmcweb Message Registries are located under 19"\redfish-core\include\registries" in source code, and they can be examined 20through Redfish under "/redfish/v1/Registries". 21 22If an appropriate message exists, note the 23 241. Title of the Message Object (required as the MessageKey in the MessageId). 252. Args (notated as "%x") in the "Message" field 26(required for the MessageArgs). 27 28If an appropriate message does not exist, new messages can be added as follows: 29 301. Choose a Message Registry for the new message 312. Choose a MessageKey to use as the title for the new Message entry 323. Insert a new Message entry (preferably with the title in alphabetical order) 334. Add a `description` and `resolution` 345. Set the `severity` to "Critical", "Warning", or "OK" 356. Define the `message` with any necessary args 367. Set the `numberOfArgs` and `paramTypes` to match the message args 37 38## Logging Messages 39 40Logging messages is done by providing a Redfish MessageId and any 41corresponding MessageArgs to bmcweb. 42 43A Redfish MessageId is represented in this format: 44 45`RegistryName.MajorVersion.MinorVersion.MessageKey` 46 47bmcweb will search the specified Message Registry for the MessageKey, 48construct the final message using the MessageArgs, and display that in the 49event log. 50 51### journal-based Redfish Logging 52 53The journal is the current mechanism used to log Redfish Messages. bmcweb 54looks for two fields in the journal metadata: 55 56- `REDFISH_MESSAGE_ID`: A string holding the MessageId 57- `REDFISH_MESSAGE_ARGS`: A string holding a comma-separated list of args 58 59These fields can be added to a journal entry using either the 60`phosphor::logging::entry()` command or directly using the 61`sd_journal_send()` command. 62 63### Examples 64 65#### Logging a ResourceCreated event 66 67The 68[Resource Event Message Registry](https://redfish.dmtf.org/registries/ResourceEvent.1.0.0.json) 69holds the ResourceCreated message: 70 71```json 72{ 73 "ResourceCreated": { 74 "Description": "Indicates that all conditions of a successful 75 creation operation have been met.", 76 "Message": "The resource has been created successfully.", 77 "NumberOfArgs": 0, 78 "Resolution": "None", 79 "Severity": "OK" 80 } 81}, 82``` 83 84Since there are no parameters, no MessageArgs are required, so this message 85can be logged to the journal as follows: 86 87```cpp 88phosphor::logging::log<log::level>( 89 "journal text", 90 phosphor::logging::entry("REDFISH_MESSAGE_ID=%s", 91 "ResourceEvent.1.0.ResourceCreated")); 92``` 93 94or 95 96```cpp 97sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", <LOG_LEVEL>, 98 "REDFISH_MESSAGE_ID=%s", 99 "ResourceEvent.1.0.ResourceCreated", NULL); 100``` 101 102#### Logging a ResourceErrorThresholdExceeded event 103The 104[Resource Event Message Registry](https://redfish.dmtf.org/registries/ResourceEvent.1.0.0.json) 105holds the ResourceErrorThresholdExceeded message: 106 107```json 108{ 109 "ResourceErrorThresholdExceeded": { 110 "Description": "The resource property %1 has exceeded error 111 threshold of value %2. Examples would be drive IO errors, or 112 network link errors.", 113 "Message": "The resource property %1 has exceeded error 114 threshold of value %2.", 115 "NumberOfArgs": 2, 116 "ParamTypes": [ 117 "string", 118 "value" 119 ], 120 "Resolution": "None.", 121 "Severity": "Critical" 122 } 123}, 124``` 125 126This message has two parameters, `%1` and `%2`, as indicated in the 127`"NumberOfArgs"` field. The meaning and types of these parameters are derived 128from the `"Message"` and `"ParamTypes"` fields in the Message Registry. 129 130In this example, `%1` is a string holding the property name and `%2` is a 131number holding the threshold value. 132 133The parameters are filled from a comma-separated list of the MessageArgs, so 134this message can be logged to the journal as follows: 135 136```cpp 137phosphor::logging::log<log::level>( 138 "journal text", 139 phosphor::logging::entry("REDFISH_MESSAGE_ID=%s", 140 "ResourceEvent.1.0.ResourceErrorThresholdExceeded"), 141 phosphor::logging::entry("REDFISH_MESSAGE_ARGS=%s,%d", 142 "Property Name", propertyValue)); 143``` 144 145or 146 147```cpp 148sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", <LOG_LEVEL>, 149 "REDFISH_MESSAGE_ID=%s", 150 "ResourceEvent.1.0.ResourceErrorThresholdExceeded", 151 "REDFISH_MESSAGE_ARGS=%s,%d", "Property Name", 152 propertyValue, NULL); 153```