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```