Changeset 102095 in vbox for trunk

Timestamp:

Nov 15, 2023 10:21:46 AM (18 months ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

160214

Message:

Jira:VBP-402. Added OCI telemetry API support in VBoxManage. 2 new commands - 'VBoxManage cloud instance metriclist' and 'VBoxManage cloud instance metricdata' Added help documentation for these commands.

Location:

trunk

Files:

• doc/manual/en_US/man_VBoxManage-cloud.xml (modified) (2 diffs)
• src/VBox/Frontends/VBoxManage/VBoxManageCloud.cpp (modified) (5 diffs)

trunk/doc/manual/en_US/man_VBoxManage-cloud.xml ¶

@@ -156 +156 @@
        <arg choice="req">--id=<replaceable>unique id</replaceable></arg>
        <arg>--clone-name=<replaceable>name for a clone instance</replaceable></arg>
+     </cmdsynopsis>
+     <cmdsynopsis id="synopsis-vboxmanage-cloud-instance-metriclist" sepchar=" ">
+       <command moreinfo="none">VBoxManage cloud</command>
+       <arg choice="req">--provider=<replaceable>name</replaceable></arg>
+       <arg choice="req">--profile=<replaceable>name</replaceable></arg>
+       <sbr/>
+       <arg choice="plain">instance metriclist</arg>
+       <arg choice="req">--id=<replaceable>unique id</replaceable></arg>
+     </cmdsynopsis>
+     <cmdsynopsis id="synopsis-vboxmanage-cloud-instance-metricdata" sepchar=" ">
+       <command moreinfo="none">VBoxManage cloud</command>
+       <arg choice="req">--provider=<replaceable>name</replaceable></arg>
+       <arg choice="req">--profile=<replaceable>name</replaceable></arg>
+       <sbr/>
+       <arg choice="plain">instance metricdata</arg>
+       <arg choice="req">--id=<replaceable>unique id</replaceable></arg>
+       <arg choice="req">--metric-name=<replaceable>metric name</replaceable></arg>
+       <arg choice="req">--metric-points=<replaceable>number of history metric points</replaceable></arg>
      </cmdsynopsis>
 
@@ -502 +520 @@
     </refsect2>
 
+    <refsect2 id="vboxmanage-cloud-instance-metriclist">
+      <title>available list of metrics for cloud instances</title>
+      <remark role="help-copy-synopsis"/>
+      <para>
+        Displays the list of the available metrics for the instance.
+        The returned names must be used with the command "VBoxManage cloud instance metricdata".
+      </para>
+      <variablelist>
+        <varlistentry>
+          <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2 id="vboxmanage-cloud-instance-metricdata">
+      <title>Displays cloud instance metric data</title>
+      <remark role="help-copy-synopsis"/>
+      <para>
+        Displays the metric data with the resolution 1 minute for the requested cloud instances.
+        The timestamps are returned in the format Rfc2822.
+      </para>
+      <variablelist>
+        <varlistentry>
+          <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><option>--metric-name</option></term><listitem><para>Metric name</para></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><option>--metric-points</option></term>
+            <listitem>
+                <para>
+                    History metric point numbers start at 1 and can go backwards as long as history exists.
+                    Points are counted from the current time to the past. If user only wants the last actual value
+                    he passes the value "1". If 2 values need to be returned (last and second to last),
+                    the user passes "2", etc.
+                </para>
+            </listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
     <!-- Cloud image commands -->
     <refsect2 id="vboxmanage-cloud-image-create">

trunk/src/VBox/Frontends/VBoxManage/VBoxManageCloud.cpp ¶

@@ -49 +49 @@
 
 #include <list>
+#include <vector>
 
 using namespace com;//at least for Bstr
 
 DECLARE_TRANSLATION_CONTEXT(Cloud);
-
+DECLARE_TRANSLATION_CONTEXT(CloudMachine);
 
 /**
@@ -1147 +1148 @@
 }
 
+
+static RTEXITCODE cloudInstanceMetricList(HandlerArg *a, int iFirst, PCLOUDCOMMONOPT pCommonOpts)
+{
+    HRESULT hrc = S_OK;
+
+    static const RTGETOPTDEF s_aOptions[] =
+    {
+        { "--id",           'i', RTGETOPT_REQ_STRING },
+        { "help",           'h', RTGETOPT_REQ_NOTHING },
+        { "--help",         'h', RTGETOPT_REQ_NOTHING }
+    };
+    RTGETOPTSTATE GetState;
+    RTGETOPTUNION ValueUnion;
+    int vrc = RTGetOptInit(&GetState, a->argc, a->argv, s_aOptions, RT_ELEMENTS(s_aOptions), iFirst, 0);
+    AssertRCReturn(vrc, RTEXITCODE_FAILURE);
+    if (a->argc == iFirst)
+    {
+        RTPrintf(Cloud::tr("Empty command parameter list, show help.\n"));
+        printHelp(g_pStdOut);
+        return RTEXITCODE_SUCCESS;
+    }
+
+    Utf8Str strInstanceId;
+
+    int c;
+    while ((c = RTGetOpt(&GetState, &ValueUnion)) != 0)
+    {
+        switch (c)
+        {
+            case 'i':
+            {
+                if (strInstanceId.isNotEmpty())
+                    return errorArgument(Cloud::tr("Duplicate parameter: --id"));
+
+                strInstanceId = ValueUnion.psz;
+                if (strInstanceId.isEmpty())
+                    return errorArgument(Cloud::tr("Empty parameter: --id"));
+
+                break;
+            }
+            case 'h':
+                printHelp(g_pStdOut);
+                return RTEXITCODE_SUCCESS;
+            case VINF_GETOPT_NOT_OPTION:
+                return errorUnknownSubcommand(ValueUnion.psz);
+
+            default:
+                return errorGetOpt(c, &ValueUnion);
+        }
+    }
+
+    /* Delayed check. It allows us to print help information.*/
+    hrc = checkAndSetCommonOptions(a, pCommonOpts);
+    if (FAILED(hrc))
+        return RTEXITCODE_FAILURE;
+
+    if (strInstanceId.isEmpty())
+        return errorArgument(Cloud::tr("Missing parameter: --id"));
+
+    ComPtr<ICloudProfile> pCloudProfile = pCommonOpts->profile.pCloudProfile;
+
+    ComObjPtr<ICloudClient> oCloudClient;
+    CHECK_ERROR2_RET(hrc, pCloudProfile,
+                     CreateCloudClient(oCloudClient.asOutParam()),
+                     RTEXITCODE_FAILURE);
+    RTPrintf(Cloud::tr("Getting list of metric names for the cloud instance with id %s\n"), strInstanceId.c_str());
+    RTPrintf(Cloud::tr("Reply is the list, each metric name is placed on a separate line as \' - <metric name>\'\n"));
+
+    ComPtr<IProgress> progress;
+
+    CHECK_ERROR2_RET(hrc, oCloudClient, ReadCloudMachineList(progress.asOutParam()), RTEXITCODE_FAILURE);
+
+    /* First step*/
+    RTPrintf(Cloud::tr("First, reading the cloud machines list...\n"));
+    hrc = showProgress(progress);
+    CHECK_PROGRESS_ERROR_RET(progress, (Cloud::tr("Reading the cloud machines list failed")), RTEXITCODE_FAILURE);
+
+    com::SafeIfaceArray<ICloudMachine> aMachines;
+    CHECK_ERROR2_RET(hrc, oCloudClient, 
+                     COMGETTER(CloudMachineList)(ComSafeArrayAsOutParam(aMachines)),
+                     RTEXITCODE_FAILURE);
+
+    const size_t cMachines = aMachines.size();
+    if (cMachines == 0)
+        return RTEXITCODE_SUCCESS;
+
+    std::vector<ComPtr<ICloudMachine> > vMachines(cMachines);
+    std::vector<com::Bstr> vBstrCloudIds(cMachines);
+    std::vector<com::Bstr> vBstrIds(cMachines);
+
+    com::Bstr bstrFoundMachineVBoxId;
+
+    for (size_t i = 0; i < cMachines; ++i)
+    {
+        vMachines[i] = aMachines[i];
+
+        CHECK_ERROR2_RET(hrc, vMachines[i],
+                         COMGETTER(CloudId)(vBstrCloudIds[i].asOutParam()),
+                         RTEXITCODE_FAILURE);
+
+        Utf8Str strCurrMachineCloudId(vBstrCloudIds[i]);
+        if (strCurrMachineCloudId.equals(strInstanceId))
+        {
+            CHECK_ERROR2_RET(hrc, vMachines[i],
+                             COMGETTER(Id)(vBstrIds[i].asOutParam()),
+                             RTEXITCODE_FAILURE);
+            bstrFoundMachineVBoxId = vBstrIds[i];
+            break;
+        }
+    }
+
+    if (bstrFoundMachineVBoxId.isEmpty())
+    {
+        RTPrintf("The passed cloud instance Id \'%s\' WASN'T found among the cloud machines "
+                 "of user \'%s\' registered with VirtualBox\n", 
+                 strInstanceId.c_str(), pCommonOpts->profile.pszProfileName);
+        return RTEXITCODE_FAILURE;
+    }
+
+    /* Second step*/
+    RTPrintf(Cloud::tr("Second, refresh information about cloud instance ...\n"));
+    ComPtr<ICloudMachine> pMachine;
+    CHECK_ERROR2_RET(hrc, oCloudClient,
+        GetCloudMachine(bstrFoundMachineVBoxId.raw(), pMachine.asOutParam()), RTEXITCODE_FAILURE);
+
+    ComPtr<IProgress> pRefreshProgress;
+    CHECK_ERROR2_RET(hrc, pMachine, Refresh(pRefreshProgress.asOutParam()), RTEXITCODE_FAILURE);
+
+    hrc = showProgress(pRefreshProgress);
+    CHECK_PROGRESS_ERROR_RET(pRefreshProgress, (Cloud::tr("Refreshing information about cloud instance failed")), RTEXITCODE_FAILURE);
+
+    /* Third step*/
+    RTPrintf(Cloud::tr("Third, getting information about cloud instance metric names...\n"));
+    ComPtr<IProgress> progress2;
+    ComPtr<IStringArray> returnMetricNames;
+    CHECK_ERROR2_RET(hrc, pMachine, ListMetricNames(returnMetricNames.asOutParam(), progress2.asOutParam()),  RTEXITCODE_FAILURE);
+
+    hrc = showProgress(progress2);
+    CHECK_PROGRESS_ERROR_RET(progress, (Cloud::tr("Getting information about cloud instance metrics failed")), RTEXITCODE_FAILURE);
+
+    com::SafeArray<BSTR> metricNamesArray;
+    CHECK_ERROR2_RET(hrc,
+                     returnMetricNames, COMGETTER(Values)(ComSafeArrayAsOutParam(metricNamesArray)),
+                     RTEXITCODE_FAILURE);
+
+    RTPrintf(Cloud::tr("Available metric names:\n"));
+    uint32_t cMetricNamesArraySize = metricNamesArray.size();
+
+    if (cMetricNamesArraySize == 0)
+    {
+        RTPrintf(Cloud::tr("\tThe list of metric names is empty. It may mean that an appropriate service wasn't run on the instance.\n"));
+        return RTEXITCODE_FAILURE;
+    }
+    else
+    {
+        Bstr value;
+        for (uint32_t k = 0; k < cMetricNamesArraySize; ++k)
+        {
+            value = metricNamesArray[k];
+            MetricType_T aMetricType;
+            CHECK_ERROR2_RET(hrc, oCloudClient, GetMetricTypeByName(value.raw(), &aMetricType), RTEXITCODE_FAILURE);
+
+            if (SUCCEEDED(hrc))
+            {
+                switch (aMetricType)
+                {
+                    case MetricType_CpuUtilization:
+                    case MetricType_MemoryUtilization:
+                    case MetricType_DiskBytesRead:
+                    case MetricType_DiskBytesWritten:
+                    case MetricType_NetworksBytesIn:
+                    case MetricType_NetworksBytesOut:
+                        RTPrintf(Cloud::tr(" - %ls\n"), value.raw());
+                        break;
+                    case MetricType_Invalid:
+                    default:
+                        break;
+                }
+            }
+        }
+    }
+
+    return SUCCEEDED(hrc) ? RTEXITCODE_SUCCESS : RTEXITCODE_FAILURE;
+}
+
+
+static RTEXITCODE cloudInstanceMetricData(HandlerArg *a, int iFirst, PCLOUDCOMMONOPT pCommonOpts)
+{
+    HRESULT hrc = S_OK;
+
+    static const RTGETOPTDEF s_aOptions[] =
+    {
+        { "--id",           'i', RTGETOPT_REQ_STRING },
+        { "--metric-name",  'n', RTGETOPT_REQ_STRING },
+        { "--metric-points",'p', RTGETOPT_REQ_STRING },
+        { "help",           'h', RTGETOPT_REQ_NOTHING },
+        { "--help",         'h', RTGETOPT_REQ_NOTHING }
+    };
+    RTGETOPTSTATE GetState;
+    RTGETOPTUNION ValueUnion;
+    int vrc = RTGetOptInit(&GetState, a->argc, a->argv, s_aOptions, RT_ELEMENTS(s_aOptions), iFirst, 0);
+    AssertRCReturn(vrc, RTEXITCODE_FAILURE);
+    if (a->argc == iFirst)
+    {
+        RTPrintf(Cloud::tr("Empty command parameter list, show help.\n"));
+        printHelp(g_pStdOut);
+        return RTEXITCODE_SUCCESS;
+    }
+
+    Utf8Str strInstanceId;
+    Utf8Str strMetricName;
+    Utf8Str strMetricPoints;
+
+    int c;
+    while ((c = RTGetOpt(&GetState, &ValueUnion)) != 0)
+    {
+        switch (c)
+        {
+            case 'i':
+            {
+                if (strInstanceId.isNotEmpty())
+                    return errorArgument(Cloud::tr("Duplicate parameter: --id"));
+
+                strInstanceId = ValueUnion.psz;
+                if (strInstanceId.isEmpty())
+                    return errorArgument(Cloud::tr("Empty parameter: --id"));
+
+                break;
+            }
+            case 'n':
+            {
+                if (strMetricName.isNotEmpty())
+                    return errorArgument(Cloud::tr("Duplicate parameter: --metric-name"));
+
+                strMetricName = ValueUnion.psz;
+                if (strMetricName.isEmpty())
+                    return errorArgument(Cloud::tr("Empty parameter: --metric-name"));
+
+                break;
+            }
+            case 'p':
+            {
+                if (strMetricPoints.isNotEmpty())
+                    return errorArgument(Cloud::tr("Duplicate parameter: --metric-points"));
+
+                strMetricPoints = ValueUnion.psz;
+                if (strMetricPoints.isEmpty())
+                    return errorArgument(Cloud::tr("Empty parameter: --metric-points"));
+
+                break;
+            }
+            case 'h':
+                printHelp(g_pStdOut);
+                return RTEXITCODE_SUCCESS;
+            case VINF_GETOPT_NOT_OPTION:
+                return errorUnknownSubcommand(ValueUnion.psz);
+
+            default:
+                return errorGetOpt(c, &ValueUnion);
+        }
+    }
+
+    /* Delayed check. It allows us to print help information.*/
+    hrc = checkAndSetCommonOptions(a, pCommonOpts);
+    if (FAILED(hrc))
+        return RTEXITCODE_FAILURE;
+
+    if (strInstanceId.isEmpty())
+        return errorArgument(Cloud::tr("Missing parameter: --id"));
+    if (strMetricName.isEmpty())
+        return errorArgument(Cloud::tr("Missing parameter: --metric-name"));
+
+    unsigned long metricPoins;
+    strMetricPoints.isEmpty() ? metricPoins = 1 : metricPoins = RTStrToUInt32(strMetricPoints.c_str());
+
+    ComPtr<ICloudProfile> pCloudProfile = pCommonOpts->profile.pCloudProfile;
+
+    ComObjPtr<ICloudClient> oCloudClient;
+    CHECK_ERROR2_RET(hrc, pCloudProfile,
+                     CreateCloudClient(oCloudClient.asOutParam()),
+                     RTEXITCODE_FAILURE);
+    RTPrintf(Cloud::tr("Getting %s metric for the cloud instance with id %s...\n"), strMetricName.c_str(), strInstanceId.c_str());
+    RTPrintf(Cloud::tr("Reply is in the form \'%s[Rfc2822 time format]\' = \'value\'\n"), strMetricName.c_str());
+
+    /* Check the requested metric type */
+    MetricType_T aMetricType;
+    CHECK_ERROR2_RET(hrc, oCloudClient, GetMetricTypeByName(com::Bstr(strMetricName.c_str()).raw(), &aMetricType), RTEXITCODE_FAILURE);
+
+    /* First step*/
+    RTPrintf(Cloud::tr("First, reading the cloud machines list...\n"));
+    ComPtr<IProgress> progress;
+    CHECK_ERROR2_RET(hrc, oCloudClient, ReadCloudMachineList(progress.asOutParam()), RTEXITCODE_FAILURE);
+
+    hrc = showProgress(progress);
+    CHECK_PROGRESS_ERROR_RET(progress, (Cloud::tr("Reading the cloud machines list failed")), RTEXITCODE_FAILURE);
+
+    com::SafeIfaceArray<ICloudMachine> aMachines;
+    CHECK_ERROR2_RET(hrc, oCloudClient, 
+                     COMGETTER(CloudMachineList)(ComSafeArrayAsOutParam(aMachines)),
+                     RTEXITCODE_FAILURE);
+
+    const size_t cMachines = aMachines.size();
+    if (cMachines == 0)
+        return RTEXITCODE_SUCCESS;
+
+    std::vector<ComPtr<ICloudMachine> > vMachines(cMachines);
+    std::vector<com::Bstr> vBstrCloudIds(cMachines);
+    std::vector<com::Bstr> vBstrIds(cMachines);
+
+    com::Bstr bstrFoundMachineVBoxId;
+
+    for (size_t i = 0; i < cMachines; ++i)
+    {
+        vMachines[i] = aMachines[i];
+
+        CHECK_ERROR2_RET(hrc, vMachines[i],
+                         COMGETTER(CloudId)(vBstrCloudIds[i].asOutParam()),
+                         RTEXITCODE_FAILURE);
+
+        Utf8Str strCurrMachineCloudId(vBstrCloudIds[i]);
+        if (strCurrMachineCloudId.equals(strInstanceId))
+        {
+            CHECK_ERROR2_RET(hrc, vMachines[i],
+                             COMGETTER(Id)(vBstrIds[i].asOutParam()),
+                             RTEXITCODE_FAILURE);
+            bstrFoundMachineVBoxId = vBstrIds[i];
+            break;
+        }
+    }
+
+    if (bstrFoundMachineVBoxId.isEmpty())
+    {
+        RTPrintf("The passed cloud instance Id \'%s\' WASN'T found among the cloud machines "
+                 "of user \'%s\' registered with VirtualBox\n", 
+                 strInstanceId.c_str(), pCommonOpts->profile.pszProfileName);
+        return RTEXITCODE_FAILURE;
+    }
+
+    /* Second step*/
+    RTPrintf(Cloud::tr("Second, refresh information about cloud instance ...\n"));
+    ComPtr<ICloudMachine> pMachine;
+    CHECK_ERROR2_RET(hrc, oCloudClient,
+        GetCloudMachine(bstrFoundMachineVBoxId.raw(), pMachine.asOutParam()), RTEXITCODE_FAILURE);
+
+    ComPtr<IProgress> pRefreshProgress;
+    CHECK_ERROR2_RET(hrc, pMachine, Refresh(pRefreshProgress.asOutParam()), RTEXITCODE_FAILURE);
+
+    hrc = showProgress(pRefreshProgress);
+    CHECK_PROGRESS_ERROR_RET(pRefreshProgress, (Cloud::tr("Refreshing information about cloud instance failed")), RTEXITCODE_FAILURE);
+
+    /* Third step*/
+    RTPrintf(Cloud::tr("Third, request metric data from cloud instance ...\n"));
+    ComPtr<IProgress> progress2;
+    ComPtr<IStringArray> returnDataValues;
+    ComPtr<IStringArray> returnDataTimestamps;
+    ComPtr<IStringArray> returnMeasureUnits;
+
+    CHECK_ERROR2_RET(hrc, pMachine, EnumerateMetricData(aMetricType,
+                                                        metricPoins,
+                                                        returnDataValues.asOutParam(),
+                                                        returnDataTimestamps.asOutParam(),
+                                                        returnMeasureUnits.asOutParam(),
+                                                        progress2.asOutParam()),  RTEXITCODE_FAILURE);
+
+    hrc = showProgress(progress2);
+    CHECK_PROGRESS_ERROR_RET(progress2, (Cloud::tr("Getting metric data failed")), RTEXITCODE_FAILURE);
+
+    com::SafeArray<BSTR> dataValueArray;
+    CHECK_ERROR2_RET(hrc,
+                     returnDataValues, COMGETTER(Values)(ComSafeArrayAsOutParam(dataValueArray)),
+                     RTEXITCODE_FAILURE);
+
+    com::SafeArray<BSTR> dataTimestampArray;
+    CHECK_ERROR2_RET(hrc,
+                     returnDataTimestamps, COMGETTER(Values)(ComSafeArrayAsOutParam(dataTimestampArray)),
+                     RTEXITCODE_FAILURE);
+
+    com::SafeArray<BSTR> measureUnitArray;
+    CHECK_ERROR2_RET(hrc,
+                     returnMeasureUnits, COMGETTER(Values)(ComSafeArrayAsOutParam(measureUnitArray)),
+                     RTEXITCODE_FAILURE);
+
+    size_t cDataValueArraySize = dataValueArray.size();
+    Bstr unit = cDataValueArraySize == 0 ? Bstr("unknown units") : measureUnitArray[0];
+    RTPrintf(Cloud::tr("The %s metric values (in %ls):\n"), strMetricName.c_str(), unit.raw());
+
+    if (cDataValueArraySize == 0)
+        RTPrintf(Cloud::tr("\tThe list of metric data is empty. It may mean that an appropriate service wasn't run on the instance.\n"));
+    else
+    {
+        Bstr value;
+        for (size_t k = 0; k < cDataValueArraySize; ++k)
+        {
+            value = dataValueArray[k];
+            Utf8Str strTimestamp(dataTimestampArray[k]);
+            RTPrintf(Cloud::tr("%d: %s[%s] = %ls\n"), k, strMetricName.c_str(), strTimestamp.c_str(), value.raw());
+        }
+    }
+
+    return SUCCEEDED(hrc) ? RTEXITCODE_SUCCESS : RTEXITCODE_FAILURE;
+}
+
+
 static RTEXITCODE startCloudInstance(HandlerArg *a, int iFirst, PCLOUDCOMMONOPT pCommonOpts)
 {
@@ -1489 +1893 @@
         kCloudInstance_Reset,
         kCloudInstance_Clone,
+        kCloudInstance_MetricList,
+        kCloudInstance_MetricData,
     };
 
@@ -1501 +1907 @@
         { "reset",          kCloudInstance_Reset,     RTGETOPT_REQ_NOTHING },
         { "clone",          kCloudInstance_Clone,     RTGETOPT_REQ_NOTHING },
+        { "metriclist",     kCloudInstance_MetricList,RTGETOPT_REQ_NOTHING },
+        { "metricdata",     kCloudInstance_MetricData,RTGETOPT_REQ_NOTHING },
 
         { "help",           'h',                      RTGETOPT_REQ_NOTHING },
@@ -1557 +1965 @@
                 setCurrentSubcommand(HELP_SCOPE_CLOUD_INSTANCE_CLONE);
                 return cloneCloudInstance(a, GetState.iNext, pCommonOpts);
+
+            case kCloudInstance_MetricData:
+                setCurrentSubcommand(HELP_SCOPE_CLOUD_INSTANCE_METRICDATA);
+                return cloudInstanceMetricData(a, GetState.iNext, pCommonOpts);
+
+            case kCloudInstance_MetricList:
+                setCurrentSubcommand(HELP_SCOPE_CLOUD_INSTANCE_METRICLIST);
+                return cloudInstanceMetricList(a, GetState.iNext, pCommonOpts);
 
             case 'h':