Re: git: 8c47d8f53854 - main - prometheus_sysctl_exporter: fix metric aliasing

On 19/04/2022 16:33, Alan Somers wrote:
> On Tue, Apr 19, 2022 at 8:22 AM Mateusz Piotrowski <0mp@freebsd.org> wrote:
>> On 19/04/2022 14:56, Alan Somers wrote:
>>> The branch main has been updated by asomers:
>>>
>>> URL: https://cgit.FreeBSD.org/src/commit/?id=8c47d8f53854825d8e8591ccd06e32b2c798f81c
>>>
>>> commit 8c47d8f53854825d8e8591ccd06e32b2c798f81c
>>> Author:     Alan Somers <asomers@FreeBSD.org>
>>> AuthorDate: 2022-04-18 21:29:37 +0000
>>> Commit:     Alan Somers <asomers@FreeBSD.org>
>>> CommitDate: 2022-04-19 12:56:39 +0000
>>>
>>>       prometheus_sysctl_exporter: fix metric aliasing
>>>
>>>       When exporting sysctls to Prometheus, the exporter replaces "." with
>>>       "_".  This caused several metrics to alias, confusing the Prometheus
>>>       server.  Fix it by:
>>>
>>>       * Renaming the "tcp_log_bucket" UMA zone to "tcp_log_id_bucket".  Also,
>>>         rename "tcp_log_node" to "tcp_log_id_node" for consistency.
>>>
>>>       * Not exporting sysctls with "(LEGACY)" in the description.  That is
>>>         used by ZFS sysctls that have been replaced by others, many of which
>>>         alias to the same Prometheus metric name (like "vfs.zfs.arc_max" and
>>>         "vfs.zfs.arc.max").
>>>
>>>       PR:             259607
>>>       Reported by:    delphij
>>>       MFC after:      2 weeks
>>>       Sponsored by:   Axcient
>>>       Reviewed by:    delphij,rew,thj
>>>       Differential Revision: https://reviews.freebsd.org/D34952
>> This should definitely make it to release notes.
>>
>> Also, should we keep a log of these kind of changes in the history section of the manual pages? I
>> find the history logs that systemd folks publish in their manual pages to be quite informative,
>> e.g., https://www.man7.org/linux/man-pages//man7/systemd.net-naming-scheme.7.html
> Do you think that the uma zone rename is too disruptive to MFC?

I don't know :) I don't know how often this sysctl is used and how often it is consumed by 
automation. I think that it's alright to perform such clean-ups, especially for such a new tool like 
our in-base prometheus exporter. My point is that due to the nature of prometheus metrics, I think 
it is a good idea to give users a heads-up that the metric name is going to change. A note in the 
release notes should be sufficient.

Best,

Mateusz Piotrowski