[PATCH net-next] docs: networking: clarify expectation of persistent stats

[PATCH net-next] docs: networking: clarify expectation of persistent stats

[Naveen Mamindlapalli]

This update clarifies the requirement for preserving statistics across
interface up/down cycles, noting that some drivers may not support this
due to inherent limitations. It also outlines the potential effects on
monitoring and observability tools.

Signed-off-by: Naveen Mamindlapalli <naveenm@marvell.com>
---
 Documentation/networking/statistics.rst | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst
index 518284e287b0..857b08d633f7 100644
--- a/Documentation/networking/statistics.rst
+++ b/Documentation/networking/statistics.rst
@@ -222,8 +222,18 @@ Retrieving ethtool statistics is a multi-syscall process, drivers are advised
 to keep the number of statistics constant to avoid race conditions with
 user space trying to read them.
 
-Statistics must persist across routine operations like bringing the interface
-down and up.
+Statistics are expected to persist across routine operations like bringing the
+interface down and up. This includes both standard interface statistics and
+driver-defined statistics reported via `ethtool -S`.
+
+However, this behavior is not always strictly followed, and some drivers do
+reset these counters to zero when the device is closed and reopened. This can
+lead to misinterpretation of network behavior by monitoring tools, such as
+SNMP, that expect monotonically increasing counters.
+
+Driver authors are expected to preserve statistics across interface down/up
+cycles to ensure consistent reporting and better integration with monitoring
+tools that consume these statistics.
 
 Kernel-internal data structures
 -------------------------------
-- 
2.34.1

Re: [PATCH net-next] docs: networking: clarify expectation of persistent stats

[Jakub Kicinski]

On Mon, 25 Aug 2025 19:17:55 +0530 Naveen Mamindlapalli wrote:
> -Statistics must persist across routine operations like bringing the interface
> -down and up.
> +Statistics are expected to persist across routine operations like bringing the

Please don't weaken the requirement. The requirements is what it is.

> +interface down and up. This includes both standard interface statistics and
> +driver-defined statistics reported via `ethtool -S`.

Rest of the paragraph looks good, but I think the preferred form of
quotations is double back ticks? Most of this doc doesn't comply but
let's stick to double when adding new stuff.

> +However, this behavior is not always strictly followed, and some drivers do
> +reset these counters to zero when the device is closed and reopened. This can
> +lead to misinterpretation of network behavior by monitoring tools, such as
> +SNMP, that expect monotonically increasing counters.
> +
> +Driver authors are expected to preserve statistics across interface down/up
> +cycles to ensure consistent reporting and better integration with monitoring
> +tools that consume these statistics.

This feels like too many words. How about:

Note that the following legacy drivers do not comply with this requirement
and cannot be fixed without breaking existing users:
 - driver1
 - driver2
 ...
-- 
pw-bot: cr

Re: [PATCH net-next] docs: networking: clarify expectation of persistent stats

[Naveen Mamindlapalli]

On 2025-08-27 at 06:14:57, Jakub Kicinski (kuba@kernel.org) wrote:
> On Mon, 25 Aug 2025 19:17:55 +0530 Naveen Mamindlapalli wrote:
> > -Statistics must persist across routine operations like bringing the interface
> > -down and up.
> > +Statistics are expected to persist across routine operations like bringing the
> 
> Please don't weaken the requirement. The requirements is what it is.
Ack on not weakening the requirement.
> 
> > +interface down and up. This includes both standard interface statistics and
> > +driver-defined statistics reported via `ethtool -S`.
> 
> Rest of the paragraph looks good, but I think the preferred form of
> quotations is double back ticks? Most of this doc doesn't comply but
> let's stick to double when adding new stuff.
Ack.
> 
> > +However, this behavior is not always strictly followed, and some drivers do
> > +reset these counters to zero when the device is closed and reopened. This can
> > +lead to misinterpretation of network behavior by monitoring tools, such as
> > +SNMP, that expect monotonically increasing counters.
> > +
> > +Driver authors are expected to preserve statistics across interface down/up
> > +cycles to ensure consistent reporting and better integration with monitoring
> > +tools that consume these statistics.
> 
> This feels like too many words. How about:
> 
> Note that the following legacy drivers do not comply with this requirement
> and cannot be fixed without breaking existing users:
>  - driver1
>  - driver2
>  ...
I don’t have a definitive list of non-compliant drivers. Would you prefer to add
a brief note stating that some drivers may not comply, without naming them explicitly?

Regards,
Naveen
> -- 
> pw-bot: cr
> 

Re: [PATCH net-next] docs: networking: clarify expectation of persistent stats

[Jakub Kicinski]

On Fri, 5 Sep 2025 16:34:30 +0530 Naveen Mamindlapalli wrote:
> > Note that the following legacy drivers do not comply with this requirement
> > and cannot be fixed without breaking existing users:
> >  - driver1
> >  - driver2
> >  ...  
> I don’t have a definitive list of non-compliant drivers. Would you prefer to add
> a brief note stating that some drivers may not comply, without naming them explicitly?

We don't have to list them all from the start.
It's for a quick sanity check so that users don't duplicate work
validating that their driver is broken. Maybe say ".. following legacy
drivers are known not to comply .." Hopefully the "are known"
sufficiently indicates that we're covering only one quadrant of 
the Rumsfeld matrix.