From nobody Sat May 4 09:51:27 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1667298519; cv=none; d=zohomail.com; s=zohoarc; b=BJ89gOnZBV/XjQ6SVcLxfrw95EepLMPBe/kYToPDqC8xQT54t89ppmNMEpQLHyHAjPlLRrPI2d1zpR1c1eNZZrNI5bpL87NtkN8kh0LqsyHaSp+feA1jS/ouUO3mmfmt0fpqqSaRx+gQd0OlB9ffWA32BPHguna0lcZ7DuZ08tw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1667298519; h=Content-Type:Content-Transfer-Encoding:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=Nehn2sUBFMnTNJclwYrsD0bEvGwAhdK0YKunkjEHmys=; b=GKxrLyQX1pOFocfYR8CB2wVyGXa7+AgFskEUMA5JKsgZH9SL9zd1P/1QVe7WWzQaEKjGDnxVog8Ji2zdXd8g+54Wi0J7wrE3ait38m0tF+CKySmanJHcPjNnCBzVM4Z13/mJ0+BnbLk4sTWvd3Yn90XWnEXe++eUYZyHuwZXg2s= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1667298519070860.2876157775294; Tue, 1 Nov 2022 03:28:39 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-434-CT0eqcVLNd69nIiVWyZ50g-1; Tue, 01 Nov 2022 06:28:35 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 0C3CC80253E; Tue, 1 Nov 2022 10:28:34 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (unknown [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 15099140EBF3; Tue, 1 Nov 2022 10:28:32 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id DE6F619465B3; Tue, 1 Nov 2022 10:28:31 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 710E11946594 for ; Tue, 1 Nov 2022 10:28:31 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 4027740C6EC4; Tue, 1 Nov 2022 10:28:31 +0000 (UTC) Received: from speedmetal.lan (ovpn-208-27.brq.redhat.com [10.40.208.27]) by smtp.corp.redhat.com (Postfix) with ESMTP id 92B6540C6F9F for ; Tue, 1 Nov 2022 10:28:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1667298518; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Nehn2sUBFMnTNJclwYrsD0bEvGwAhdK0YKunkjEHmys=; b=Q7qqpLjiQNHql7+hd3Xw3FlsNwugqgKPkf90ovBIFFleBm2f1zhUWADKKEk/Wwa8dYYexB HUYtMzA6c4rfIKntNgwlhf9+y17PYXpLvBDnVadBZ0SFGHrXeqeeOvebTSxRg/frZjVDoy FYNB9w+IZPHyQf9DjNtIoKSVfzEH7l0= X-MC-Unique: CT0eqcVLNd69nIiVWyZ50g-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH for 8.9.0] Document caveats of 'VIR_DOMAIN_STATS_VM' group of statistics Date: Tue, 1 Nov 2022 11:28:11 +0100 Message-Id: <1f4207247df6eeb3655ea7dafa57d79cb4bae062.1667298470.git.pkrempa@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.2 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 3.1 on 10.11.54.7 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1667298520665100001 Content-Type: text/plain; charset="utf-8" The original patches adding the functionality neglected to add any form of documentation for the stats fields returned for this group. The stats are directly converted from qemu's 'query-stats(-schema)' QMP command without any further interpretation. The 'query-stats-schema' has the following disclaimer: Note: runtime-collected statistics and their names fall outside QEMU's usu= al deprecation policies. QEMU will try to keep the set of available da= ta stable, together with their names, but will not guarantee stability at all costs; the same is true of providers that source statistics externally, e.g. from Linux. For example, if the same value is being tracked with different names on different architectures or by differ= ent providers, one of them might be renamed. A statistic might go away = if an algorithm is changed or some code is removed; changing a default might cause previously useful statistics to always report 0. Such changes, however, are expected to be rare. Since libvirt is not doing any form of conversion of the stats we can't meaningfully document any of the returned fields. At the same time we can't even meaningfully provide any form of API stability for the filed names. Modify the documentation for the 'VIR_DOMAIN_STATS_VM' group both in the API docs and in the virsh man page to reflect that and disclaim any form of stability guarantees we provide normally. Fixes: 8c9e3dae142 Signed-off-by: Peter Krempa Reviewed-by: Jiri Denemark Reviewed-by: J=C3=A1n Tomko --- docs/manpages/virsh.rst | 36 ++++++++++++++++++++++++++++++++++-- src/libvirt-domain.c | 26 +++++++++++++++++++++++++- tools/virsh-domain-monitor.c | 2 +- 3 files changed, 60 insertions(+), 4 deletions(-) diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index 61fcb2e9ca..cb2dbaec18 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -2297,7 +2297,7 @@ domstats domstats [--raw] [--enforce] [--backing] [--nowait] [--state] [--cpu-total] [--balloon] [--vcpu] [--interface] - [--block] [--perf] [--iothread] [--memory] [--dirtyrate] + [--block] [--perf] [--iothread] [--memory] [--dirtyrate] [--vm] [[--list-active] [--list-inactive] [--list-persistent] [--list-transient] [--list-running]y [--list-paused] [--list-shutoff] [--list-other]] | [domain ...] @@ -2317,7 +2317,7 @@ The individual statistics groups are selectable via s= pecific flags. By default all supported statistics groups are returned. Supported statistics groups flags are: *--state*, *--cpu-total*, *--balloon*, *--vcpu*, *--interface*, *--block*, *--perf*, *--iothread*, *--memory*, -*--dirtyrate*. +*--dirtyrate*, *--vm*. Note that - depending on the hypervisor type and version or the domain sta= te - not all of the following statistics may be returned. @@ -2533,6 +2533,38 @@ not available for statistical purposes. * ``dirtyrate.vcpu..megabytes_per_second`` - the calculated memory di= rty rate for a virtual cpu in MiB/s +*--vm* returns: + +The *--vm* option enables reporting of hypervisor-specific statistics. Nam= ing +and meaning of the fields is entirely hypervisor dependant. + +The statistics in this group have following naming scheme: + + ``vm.$NAME.$TYPE`` + + ``$NAME`` + name of the statistics field provided by the hypervisor + + ``$TYPE`` + Type of the value. Following types are returned: + + ``cur`` + current instant value + ``sum`` + aggregate value + ``max`` + peak value + + The returned value may be either an unsigned long long or a boolean. + + **WARNING**: The stats reported in this group are runtime-collected and + hypervisor originated, thus fall outside of the usual stable API + policies of libvirt. + + Libvirt can't guarantee that the statistics reported from the outside + source will be present in further versions of the hypervisor, or that + naming or meaning will stay consistent. Changes to existing fields, + however, are expected to be rare. Selecting a specific statistics groups doesn't guarantee that the daemon supports the selected group of stats. Flag *--enforce* diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 52fa136186..4728ddd6ff 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -12482,7 +12482,31 @@ virConnectGetDomainCapabilities(virConnectPtr conn, * unsigned long long. * * VIR_DOMAIN_STATS_VM: - * Return fd-based KVM statistics for the target VM + * Return hypervisor-specific statistics. Note that the naming and mea= ning + * of the fields is entirely hypervisor dependant. + * + * The statistics in this group have following naming scheme: + * + * "vm.$NAME.$TYPE" + * + * $NAME - name of the statistics field provided by the hypervisor + * + * $TYPE - Type of the value. Following types are returned: + * 'cur' - current instant value + * 'sum' - aggregate value + * 'max' - peak value + * + * The returned value may be either an unsigned long long or a boolea= n. + * + * WARNING: + * The stats reported in this group are runtime-collected and + * hypervisor originated, thus fall outside of the usual stable API + * policies of libvirt. + * + * Libvirt can't guarantee that the statistics reported from the outs= ide + * source will be present in further versions of the hypervisor, or t= hat + * naming or meaning will stay consistent. Changes to existing fields, + * however, are expected to be rare. * * Note that entire stats groups or individual stat fields may be missing = from * the output in case they are not supported by the given hypervisor, are = not diff --git a/tools/virsh-domain-monitor.c b/tools/virsh-domain-monitor.c index be8f827685..f89118f64f 100644 --- a/tools/virsh-domain-monitor.c +++ b/tools/virsh-domain-monitor.c @@ -2067,7 +2067,7 @@ static const vshCmdOptDef opts_domstats[] =3D { }, {.name =3D "vm", .type =3D VSH_OT_BOOL, - .help =3D N_("report fd-based VM statistics by KVM"), + .help =3D N_("report hypervisor-specific statistics"), }, {.name =3D "list-active", .type =3D VSH_OT_BOOL, --=20 2.38.1