Enhancements to sandesh message documentation
Following enhancements to sandesh messages documentation are needed to improve usability:
We need to provide a mechanism for users to figure out the changes in the sandesh systemlog messages between 2 releases. The changes can be in the content of the messages (added/deleted field or in the severity). We have added a contrail-docs-diff script that takes as input 2 index files (one for the old release and another for the new release). The index file contains the list of all sandesh systemlog messages and their content fingerprint and severity. The index file is named index_logs.doc.schema.json, is located in /usr/share/doc/contrail-docs/html/messages/ and is generated by the contrail-docs package.
-
The documentation served out of contrail-analytics-api needs to be organized in a better format. Currently the messages are indexed only per daemon and thus it is difficult to find out a list of sandesh systemlog messages for the whole system. We have added global indexes per sandesh message type (systemlog and objectlog, UVES, traces, introspect messages) as well as per severity for sandesh systemlog messages.
-
For objectlog and UVE messages, we can index them based on the object associated with the message. This can also then serve as a UVE schema.
-
All sandesh systemlog messages need to associated with a/one specific severity level. This is indicated using
@severityin the documentation of the message. It is also desired that this is enforced in the sandesh compiler by failing the compilation if the@severitytag is not found in the sandesh message documentation. The sandesh API to send no longer should provide an option to set the severity when sending the message and the message severity should be set to the one specified in the documentation by the generated code. -
All developers need to document each sandesh message and their individual fields also.