[netmod] Re: Gunter Van de Velde's Discuss on draft-ietf-netmod-syslog-model-32: (with DISCUSS and COMMENT)

[Mahesh Jethanandani <[e-mail]>]

Hi Gunter,

Just so you know, Joe and I were late additions as authors on this document, after most of the original authors had retired or moved on from the document.  As such, some of the motivations for design or reason for certain phrases are mere speculation on our part. 

See inline.

> On Sep 10, 2024, at 6:26 PM, Gunter Van de Velde via Datatracker <[e-mail]> wrote:
> 
> Gunter Van de Velde has entered the following ballot position for
> draft-ietf-netmod-syslog-model-32: Discuss
> 
> When responding, please keep the subject line intact and reply to all
> email addresses included in the To and CC lines. (Feel free to cut this
> introductory paragraph, however.)
> 
> 
> Please refer to https://www.ietf.org/about/groups/iesg/statements/handling-ballot-positions/ 
> for more information about how to handle DISCUSS and COMMENT positions.
> 
> 
> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-netmod-syslog-model/
> 
> 
> 
> ----------------------------------------------------------------------
> DISCUSS:
> ----------------------------------------------------------------------
> 
> # Gunter Van de Velde, RTG AD, comments for draft-ietf-netmod-syslog-model-32
> 
> # Many thanks for writing this document. It contains one blocking DISCUSS,
> which will likely be straightforward to resolve and some non-blocking comments
> and observations.
> 
> #DISCUSS
> ========
> ## I am raising a DISCUSS. The inclusion of vendor-specific details in the main
> body of a standards-track document is unexpected (see line 165). If the Working
> Group wishes to document vendor-specific properties, it should be considered
> informational and explicitly placed in an appendix for clarity. Upon reviewing
> the YANG module, I note that the vendor-specific augmentations are already
> documented in the appendix. It may be beneficial for clarity to add a note at
> line 165 indicating that the referenced vendor-specific augmentations are
> detailed in Appendix A.1 and A.2.

We can do that. But I will agree that the wording of that paragraph could be improved. See suggestions below on how to improve the paragraph you refer to here, and the previous one.
.
> 
> 
> ----------------------------------------------------------------------
> COMMENT:
> ----------------------------------------------------------------------
> 
> #GENERIC COMMENTS
> #================
> ## The yang module has a significant amount of feature statement defines an
> optional capability that may or may not be supported by an implementation of
> the YANG module. Some of these at first glance look rather feasible for being
> supported by default. Has the list of optional capabilities been verified with
> existing syslog implementations?

There are two ways to deal with optional features in a YANG model. Define them, and then have implementations deviate them using the deviate option in the language, or provide feature statements that enable the feature to be included. RFC 7950 discourages the first approach, so the authors went with the latter option.

> 
> ## Some lines in the pyang tree output are wrapped, which affects the overall
> presentation. While this is not ideal, I do not have a better suggestion at
> this time. In my view, using abbreviations for leaf names would be less
> desirable from a modeling perspective than allowing wrapped lines within an
> IETF YANG standards document.

The tree output in the normative section of the draft is meant to help explain the design of the model. For that, the entire tree diagram does not need to be presented. The next update of the draft will abridge the tree output in such a way as to still be able to explain the design without the ugly line wrapping. A more complete tree diagram will be moved to the Appendix.

> 
> #DETAILED COMMENTS
> #=================
> ##classified as [minor] and [major]
> 
> 117     2.  Terminology
> 118
> 119        The term "originator" is defined in [RFC5424] : an "originator"
> 120        generates syslog content to be carried in a message.
> 121
> 122        The term "relay" is defined in [RFC5424] : a "relay" forwards
> 123        messages, accepting messages from originators or other relays and
> 124        sending them to collectors or other relays
> 125
> 126        The term "collectors" is defined in [RFC5424] : a "collector" gathers
> 127        syslog content for further analysis.
> 128
> 129        The term "action" refers to the processing that takes place for each
> 130        syslog message received.
> 
> [minor]
> rewrite suggestion for making the Terminology section more structured:
> 
> "
> The following terms are used throughout this document:
> 
> Originator: As defined in [RFC5424], an "originator" refers to an entity that
> generates syslog content to be included in a message.
> 
> Relay: As defined in [RFC5424], a "relay" is an entity that forwards syslog
> messages. It accepts messages from originators or other relays and sends them
> to collectors or other relays.
> 
> Collector: As defined in [RFC5424], a "collector" refers to an entity that
> gathers syslog messages for further analysis.
> 
> Action: Refers to the processing applied to each syslog message received.
> "

We will take these suggestions to improve the Terminology Section.

> 
> 160        This document addresses the common leafs between implementations and
> 161        creates a common model, which can be augmented with proprietary
> 162        features, if necessary.  This model is designed to be very simple for
> 163        maximum flexibility.
> 
> [minor]
> rewrite proposal:
> 
> "
> This document identifies common elements across implementations and defines a
> shared model, which can be augmented with proprietary features as needed. The
> model is intentionally designed to be simple, ensuring maximum flexibility. "

How about this to address your DISCUSS and the COMMENT?

OLD:
This document addresses the common leafs between implementations and creates a common model, which can be augmented with proprietary features, if necessary. This model is designed to be very simple for maximum flexibility.

Some optional features are defined in this document to specify functionality that is present in specific vendor configurations.

NEW:
The module defines leafs that are common across implementations. Its simple design is meant to offer maximum flexibility. However, not all optional features defined in this document are present in all vendor implementations. Vendors, therefore, need to use the feature statements to specify the optional features they support. At the same time, vendors can augment the model to add proprietary features. Appendix A.1 and A.2 show examples of how that can be realized.

Thanks

Mahesh Jethanandani
[e-mail]