From 45b2e0a472ad39cb45be306b8dcdf59f432a7f9e Mon Sep 17 00:00:00 2001
From: Jana Halackova <jsindelarova@suse.com>
Date: Fri, 13 Sep 2024 15:01:16 +0200
Subject: [PATCH] Completed output format description.

---
 articles/vhostmd.asm.xml         | 36 ++++++++-----
 concepts/vhostmd_data_format.xml | 89 +++++++++++++++++++++++++++++++-
 2 files changed, 111 insertions(+), 14 deletions(-)

diff --git a/articles/vhostmd.asm.xml b/articles/vhostmd.asm.xml
index 8278f6c7..a8234907 100644
--- a/articles/vhostmd.asm.xml
+++ b/articles/vhostmd.asm.xml
@@ -25,6 +25,9 @@
     <resource xml:id="_vhostmd_about" href="../concepts/vhostmd_about.xml">
       <description>About vhostmd</description>
     </resource>
+    <resource xml:id="_vhostmd_data_format" href="../concepts/vhostmd_data_format.xml">
+      <description>Metrics format</description>
+    </resource>
   </resources>
   <!-- Tasks -->
   <resources>
@@ -51,14 +54,13 @@
     </resource>
   </resources>
   <!-- S T R U C T U R E -->
-  <structure renderas="article" xml:id="article-example" xml:lang="en">
+  <structure renderas="article" xml:id="vmhostmd" xml:lang="en">
     <merge>
-      <title>Setting Up Virtual Host Metrics Daemon on &productname;</title>
-      <subtitle>Subtitle if necessary</subtitle>
+      <title>Setting Up Virtual Host Metrics Daemon on &productname;</title>      
       <!-- Create revision history to enable versioning; add most recent entries at the top. -->
       <!-- Check https://documentation.suse.com/style/current/single-html/docu_styleguide/#sec-revhistory for detailed instructions-->
-      <revhistory xml:id="rh-USE-ROOT-ID">
-        <revision><date>2024-11-14</date>
+      <revhistory xml:id="rh-vmhostmd">
+        <revision><date>2024-10-14</date>
           <revdescription>
             <itemizedlist>
               <!-- Group by type of change (added/removed/changed)-->
@@ -72,7 +74,7 @@
       <!-- add author's e-mail -->
       <meta name="maintainer" content="jsindelarova@suse.com" its:translate="no"/>
       <!-- ISO date of last update as YYYY-MM-DD -->
-      <meta name="updated" content="2024-11-16" its:translate="no"/>
+      <meta name="updated" content="2024-10-16" its:translate="no"/>
       <!-- this does not work yet. Use the dm tags listed below for now
         <meta name="bugtracker" its:translate="no">
           <phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>
@@ -95,14 +97,16 @@
       <meta name="architecture">
         <phrase>&x86-64;</phrase>
         <phrase>&power;</phrase>
+        <phrase>&aarch64;</phrase>
       </meta>
       <!-- enter one or more product names and version -->
       <meta name="productname" its:translate="no">
         <productname>&productname;</productname>
       </meta>
-      <meta name="title" its:translate="yes">short title for SEO and social media, max. 55 chars</meta>
-      <meta name="description" its:translate="yes">short description, max. 150 chars</meta>
-      <meta name="social-descr" its:translate="yes">ultrashort description for social media, max 55 chars</meta>
+      <meta name="title" its:translate="yes">Setting Up Virtual Host Metrics Daemon</meta>
+      <meta name="description" its:translate="yes">vhostmd is a tool that collects metrics on a virtual machine host
+        and can provide those metrics to virtual machines running on that host.</meta>
+      <meta name="social-descr" its:translate="yes">vhostmd is a tool to collect metrics.</meta>
       <!-- suitable categories -->
       <meta name="category">
         <phrase>Systems Management</phrase>
@@ -117,8 +121,8 @@
       <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
         <dm:bugtracker>
           <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
-          <dm:component>Smart Docs</dm:component>
-          <dm:product>Documentation</dm:product>
+          <dm:component>Documentation</dm:component>
+          <dm:product>SUSE Linux Enterprise Micro 6.1</dm:product>
           <!-- provide your BUGZILLA e-mail address, otherwise this does not work correctly-->
           <dm:assignee>jsindelarova@suse.com</dm:assignee>
        </dm:bugtracker>
@@ -148,7 +152,7 @@
           <term>EFFORT</term>
             <listitem>
               <para>
-                What's the effort one has to put in?
+                It takes approximately 15 minutes to read the article.
               </para>
             </listitem>
         </varlistentry>
@@ -213,6 +217,14 @@
         </abstract>
       </merge>
       </module>
+
+      <module resourceref="_vhostmd_data_format" renderas="section">
+        <merge>
+          <abstract>
+            <para/>
+          </abstract>
+        </merge>
+        </module>
     
     <module resourceref="_legal"/>
     <module resourceref="_gfdl">
diff --git a/concepts/vhostmd_data_format.xml b/concepts/vhostmd_data_format.xml
index a66c3f70..39d78ebf 100644
--- a/concepts/vhostmd_data_format.xml
+++ b/concepts/vhostmd_data_format.xml
@@ -30,12 +30,97 @@
   </info>
   <para>
     <literal>vhostmd</literal> stores the collected metrics data on the metrics disk in a raw
-    format. The disk contains 32bytes header followed by the metrics data.
+    format. The disk contains 32bytes header followed by the metrics data in XML format.
   </para>
   <section xml:id="vhostmd-data-format-xml">
 <title>Metrics XML format</title>
 <para>
-  If you configured that a 
+  The collected metrics results are similar to the configured metrics definition. The <literal>&lt;metric&gt;</literal>
+  element can have the following attirbutes:
 </para>
+<variablelist>
+  <varlistentry>
+    <term><literal>type</literal></term>
+    <listitem>
+      <para>
+        Denotes the data type of the particular metric, for example <literal>string</literal>.
+      </para>
+    </listitem>    
+  </varlistentry>
+  <varlistentry>
+    <term><literal>context</literal></term>
+    <listitem>
+    <para>
+      Identifies whether the metric is collected on the host (<literal>host</literal>) or on a virtual machine (<literal>vm</literal>).
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><literal>id</literal></term>
+    <listitem>
+      <para>
+        Used in the <literal>vm</literal> context. Conveys the ID number of the virtual machine.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><literal>uuid</literal></term>
+    <listitem>
+      <para>
+        Used in the <literal>vm</literal> context. Conveys the Universally Unique Identifier of the virtual machine.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+<para>
+  The <literal>&lt;metric&gt;</literal> element contains the following elements:
+</para>
+<variablelist>
+  <varlistentry>
+    <term><literal>&lt;name&gt;</literal></term>
+    <listitem>
+      <para>
+        Conveys the metric name.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><literal>&lt;value&gt;</literal></term>
+    <listitem>
+      <para>
+        Conveys the metrics actual value.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+<note>
+  <title>No multiple values within one metric</title>
+  <para>
+    When the <literal>group</literal> type of a metric has been configured, each configured <literal>&lt;variable&gt;</literal> is stored
+    as a separate metric in the result. For example, the following configuration snippet:
+  </para>
+  <screen>
+&lt;metric type="group" context="host">
+  &lt;name>PageRates&lt;/name>
+  &lt;action>pagerate.pl&lt;/action>
+  &lt;variable name="PageInRate" type="uint64"/>
+  &lt;variable name="PageFaultRate" type="uint64"/>
+&lt;/metric>
+</screen>
+<para>
+  Results in the following snippet:
+</para>
+<screen>
+&lt;metric type='uint64' context='host'>
+  &lt;name>PageInRate&lt;/name>
+  &lt;value>0.000000&lt;/value>
+&lt;/metric>
+&lt;metric type='uint64' context='host'>
+  &lt;name>PageFaultRate&lt;/name>
+  &lt;value>0.000000&lt;/value>
+&lt;/metric>
+
+</screen>
+</note>
   </section>
 </topic>