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