Bug 1381714

Summary:	possible documentation error for the recently added cpu_cycles statistic
Product:	[Community] Virtualization Tools	Reporter:	Frank Ch. Eigler <fche>
Component:	libvirt	Assignee:	John Ferlan <jferlan>
Status:	CLOSED NEXTRELEASE	QA Contact:
Severity:	unspecified	Docs Contact:
Priority:	unspecified
Version:	unspecified	CC:	jferlan, libvirt-maint, myllynen, rbalakri
Target Milestone:	---
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	No Doc Update
Doc Text:	undefined	Story Points:	---
Clone Of:		Environment:
Last Closed:	2016-10-07 17:33:47 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Frank Ch. Eigler 2016-10-04 19:32:39 UTC

https://libvirt.org/git/?p=libvirt.git;a=commitdiff;h=bae660869de0612bee2a740083fb494c27e3f80c

added a "cpu_cycles" statistic to the libvirt api.  It documents it thusly, in various places.

<td>the number of cpu cycles one instruction needs</td>

This is incorrect, and probably came from a misunderstanding of the VIR_PERF_PARAM_CPU_CYCLES blurb:

Macro for typed parameter name that represents cpu_cycles perf event which can be used to measure how many cpu cycles one instruction needs. It corresponds to the "perf.cpu_cycles" field in the *Stats APIs.

The cpu_cycles counts cpu cycles (total/elapsed).  Only when divided by VIR_PERF_PARAM_INSTRUCTIONS does one get an *average* cycles-per-instruction (which would be represented by a FLOAT rather than LONG LONG anyway).

Please consider fixing the documentation.

Comment 1 John Ferlan 2016-10-07 12:44:58 UTC

Yeah when looking at things, I'm sure I thought that looks strange, but I didn't alter the original author's text assuming it was right...  The series which I altered was here:

http://www.redhat.com/archives/libvir-list/2016-July/msg00607.html

In any case, there's a patch upstream to alter the text for cpu_cycles (as part of a series of minor alterations):

http://www.redhat.com/archives/libvir-list/2016-October/msg00319.html

thanks!

Comment 2 John Ferlan 2016-10-07 17:33:47 UTC

Patches pushed - changes will be in libvirt 2.4.0

commit 12629888fccf063580a0541a9e77aac0086b6e72
Author: John Ferlan <jferlan>
Date:   Fri Oct 7 07:55:51 2016 -0400

    docs: Alter descriptions of perf cpu_cycles
...


$ git describe 12629888fccf063580a0541a9e77aac0086b6e72
v2.3.0-38-g1262988

See:

https://libvirt.org/git/?p=libvirt.git;a=commitdiff;h=12629888fccf063580a0541a9e77aac0086b6e72