Document Vrouter Sandesh messages
Affects | Status | Importance | Assigned to | Milestone | ||
---|---|---|---|---|---|---|
Juniper Openstack | Status tracked in Trunk | |||||
Trunk |
Fix Committed
|
High
|
Kumar Harsh |
Bug Description
Hello Contrail Software Developers,
As part of 3.0 release, we are required to document all messages generated by the controller and compute daemons. The analytics team has added code to mainline to automatically generate HTML documentation from the sandesh files and display it as part of the contrail-
All contrail software developers will need to add appropriate documentation to the sandesh files so that all the generated messages are documented properly. As example, I have added documentation to controller/
For example, for sandesh system log message TcpServerMessag
/**
* @description: System log for TCP server module
* @severity: ERROR
* @cause: An internal software failure occurred
* @action: Contact your technical support representative
*/
systemlog sandesh TcpServerMessageLog {
1: "Server";
/** Name of server is usually the local endpoint */
2: string ServerName;
/** Direction is send '>' or receive '<' */
3: string Direction;
4: string Message;
}
The guidelines for adding documentation to the sandesh files:
1. Any documentation is enclosed in /** */ comments.
2. Documentation about a sandesh message precedes the sandesh definition in the file and is indicated using /** */.
3. Developers can add general free-form documentation for a sandesh preceding the @ words.
4. @ words followed by space, tab, or ‘:’ will be added to a table in the documentation so that developers can add @action, @description, @severity, @cause fields. For object logs or UVEs, @object can be added to indicate the object the log is associated with. None of the @ words are mandatory, however guideline is to add @action, @cause for errors seen in field.
5. Documentation about fields precedes the field definition and is indicated using /** */
6. Documentation about structures precedes the structure definition and is indicated using /** */
7. Developers will need to change generic systemlog messages to specific one so that appropriate descriptions can be added. Further, @severity fields are preferred to have only one value rather than using the same message for ERROR and DEBUG.
8. Sandesh file or module level documentation is added at the top of the file after the copyright. For example, for io.sandesh, following is the module level documentation:
/**
* Message definitions for IO and EventManager modules.
*
* The EventManager module is responsible for handling IO and timer events
* in a daemon.
*
* The IO module is responsible for handling TCP and UDP IO server and client
* in a daemon.
*/
You can also find the guidelines at https:/
Thanks and please let me know any concerns/questions.
Megh
Changed in juniperopenstack: | |
importance: | Medium → High |
Changed in juniperopenstack: | |
assignee: | Hari Prasad Killi (haripk) → Kumar Harsh (hkumar) |
Review in progress for https:/ /review. opencontrail. org/16583
Submitter: Kumar Harsh (<email address hidden>)