Open Stack

Doug Hellmann <doug at doughellmann.com> wrote on 03/02/2016 07:19:22 PM:

> From: Doug Hellmann <doug at doughellmann.com>
> To: openstack-dev <openstack-dev at lists.openstack.org>
> Date: 03/02/2016 07:20 PM
> Subject: Re: [openstack-dev] [nova] config options help text 
> improvement: current status
> 
> Excerpts from Markus Zoeller's message of 2016-03-02 18:45:45 +0100:
> 
> [a lot snipped]
> 
> > Appendix
> > ========
> > 
> > Example of the help text improvement
> > -----------------------------------
> > As an example, compare the previous documentation of the scheduler 
> > option "scheduler_tracks_instance_changes". 
> > Before we started:
> > 
> >     # Determines if the Scheduler tracks changes to instances to help 
> >     # with its filtering decisions. (boolean value)
> >     #scheduler_tracks_instance_changes = true
> > 
> > After the improvement:
> > 
> >     # The scheduler may need information about the instances on a host 

> >     # in order to evaluate its filters and weighers. The most common 
> >     # need for this information is for the (anti-)affinity filters, 
> >     # which need to choose a host based on the instances already 
running
> >     # on a host.
> >     #
> >     # If the configured filters and weighers do not need this 
information,
> >     # disabling this option will improve performance. It may also be 
> >     # disabled when the tracking overhead proves too heavy, although 
> >     # this will cause classes requiring host usage data to query the 
> >     # database on each request instead.
> >     #
> >     # This option is only used by the FilterScheduler and its 
subclasses;
> >     # if you use a different scheduler, this option has no effect.
> >     #
> >     # * Services that use this:
> >     #
> >     #     ``nova-scheduler``
> >     #
> >     # * Related options:
> >     #
> >     #     None
> >     #  (boolean value)
> >     #scheduler_tracks_instance_changes = true
> 
> If, in the course of adding this information, you think it would be
> useful for oslo.config or the config generator to provide a way to
> expose or derive the information, let me know. We're going to be doing
> some more work on the config generator to enable some automation in the
> config reference guide maintained by the docs team, and this looks like
> the sort of thing that might be useful to include in a discoverable way
> (not just within the comment text for the options).
> 
> Doug

I assume you mean the information about the services which use the
config option. We have indeed the concern that this is prone to be
outdated easily. I was thinking if it would make sense to do an
analysis of the module imports based on the nova services starter
scripts [1] to derive that information but I couldn't dive into that.
Long story short, if the config generator could derive that, that
would be awesome.

References:
[1] https://git.openstack.org/cgit/openstack/nova/tree/nova/cmd

Regards, Markus Zoeller (markus_z)