monitoringGraph.php

<?php
/**
 * Retrieve graphs for specific metrics for a single server.
 *
 * This example shows how to use the SoftLayer API to retrieve graphs for the
 * specific Advanced Monitoring metrics for a single hardware or virtual guest
 * server instance.
 *
 * We will call the SoftLayer API to retrieve the monitoring agents,
 * configuration template, and configuration values for a server instance.
 * Then we will demonstrate how to find definitions that you have enabled for
 * metric tracking, how to check that they are enabled, and how to then use them
 * to get graphs of those metrics for arbitrary dates.
 *
 * Note that the agent, section, sub-section, and definition names have already been
 * pre-selected and in order for this example to work your server must have these
 * configuration options enabled and be able to retrieve graphs for them through
 * the portal. If you wish to use additional or substitute names for any of those
 * shown below you can do so by looking at the current options available in the
 * SoftLayer portal or by further debugging the output of this script.
 *
 * See below for more details.
 *
 * This assumes the SoftLayer API PHP client
 * <http://github.com/softlayer/softlayer-api-php-client> is installed in the
 * directory '/SoftLayer' in this script's path and that you wish to use the
 * SOAP client instead of our XML-RPC client.
 *
 * @see http://sldn.softlayer.com/wiki/index.php/SoftLayer_Hardware_Server::getObject
 * @see http://sldn.softlayer.com/wiki/index.php/SoftLayer_Hardware_Server::getMonitoringAgents
 * @see http://sldn.softlayer.com/wiki/index.php/SoftLayer_Virtual_Guest::getMonitoringAgents
 * @see http://sldn.softlayer.com/wiki/index.php/SoftLayer_Monitoring_Agent::getConfigurationTemplate
 * @see http://sldn.softlayer.com/wiki/index.php/SoftLayer_Monitoring_Agent::getConfigurationValues
 * @see http://sldn.softlayer.com/wiki/index.php/SoftLayer_Monitoring_Agent::getGraph
 * @see http://sldn.softlayer.com/wiki/index.php/SoftLayer_Container_Monitoring_Graph_Outputs
 * @license <http://sldn.softlayer.com/wiki/index.php/License>
 * @author SoftLayer Technologies, Inc. <sldn@softlayer.com>
 */

// Include XmlrpcClient.class.php if you'd like to use our XML-RPC client
// instead.
require_once(dirname(__FILE__) . '/SoftLayer/SoapClient.class.php');

/**
 * Your SoftLayer API username.
 *
 * @var string
 */
$apiUsername = 'set me!';

/**
 * Your SoftLayer API key. Generate and API key at the SoftLayer customer
 * portal:
 * https://manage.softlayer.com/Administrative/apiKeychain
 *
 * @var string
 */
$apiKey = 'set me too!';

/**
 * The id number of the server whose graphs you wish to retrieve. Call the
 * getHardware() method in the SoftLayer_Account API service to retrieve a list
 * of the servers on your account.
 *
 * @var int
 */
$serverId = 1234;

/**
 * The date at which you wish to start graphing bandwidth. Pass any string that
 * is compatible with the PHP strtotime() function.
 *
 * @var string
 */
$startDate = '11/07/2010';

/**
 * The date at which you wish to end graphing bandwidth.
 *
 * @var string
 */
$endDate = '11/08/2010';

/**
 * Create a connection to the SoftLayer_Hardware_Server API service and call the
 * getMonitoringAgents() method to get the server's associated tracking
 * object record.
 *
 * @var SoftLayer_SoapClient
 */
$client = Softlayer_SoapClient::getClient('SoftLayer_Hardware_Server', $serverId, $apiUsername, $apiKey);

$objectMask = new SoftLayer_ObjectMask();
$objectMask->monitoringAgents->statusName;
$client->setObjectMask($objectMask);

try {
    // Retrieve server's monitoring agents. as SoftLayer_Monitoring_Agent objects.
    // getMonitoringAgents() returns an array of SoftLayer_Monitoring_Agent objects.
    // From here you can loop through these agents to perform defferent functions such as get graphs,
    // activate, deactivate, or run other functions on it.
    $monitoringAgents = $client->getMonitoringAgents();
} catch (Exception $e) {
    die('Unable to retrieve server record: ' . $e->getMessage());
}

/**
 *
 * Find the id of the specific agent we are wanting, in this example the "Cpu, Disk, and Memory" monitoring agent.
 *
 */
$cdmAgent = null;
foreach ($monitoringAgents as $agent) {
    if ($agent->name == 'Cpu, Disk, and Memory Monitoring Agent') {
        $cdmAgent = $agent;
        break;
    }
}

/**
 * Next we can create an array of all configuration variables that we are able to track.
 * Re-declare our client variable to talk to the
 * SoftLayer_Monitoring_Agent API service.
 */
$client = SoftLayer_SoapClient::getClient('SoftLayer_Monitoring_Agent', $cdmAgent->id, $apiUsername, $apiKey);

// Object mask to get all definitions that we might need.
$objectMask = new SoftLayer_ObjectMask();
$objectMask->configurationTemplate->configurationSections->subSections->definitions->valueType;
$objectMask->configurationTemplate->configurationSections->subSections->definitions->monitoringDataFlag;
$objectMask->configurationValues->definition;
$client->setObjectMask($objectMask);

try {
    // getConfigurationTemplate() returns a SoftLayer_Configuration_Template
    // object. This object holds the sections, sub-sections, and definitions
    // used to configure the monitoring agent.
    $cdmConfigurationTemplate = $client->getConfigurationTemplate();
    // getConfigurationTemplate() returns an array of 
    // SoftLayer_Monitoring_Configuration_Value objects.
    $cdmConfigurationValues = $client->getConfigurationValues();
} catch (Exception $e) {
    die('Unable to retrieve monitoring agent configuration template: ' . $e->getMessage());
}

// Definitions which can enable metric tracking
$cpuGraphingDefinitions = array();
$memoryGraphingDefinitions = array();


// Loop through each section
foreach ($cdmConfigurationTemplate->configurationSections as $configurationSection) {
    // Find CPU section
    if ($configurationSection->name == 'CPU') {
        // Loop through the sections's sub-sections
        foreach ($configurationSection->subSections as $configSubSection) {
            // Find Graphing sub-section
            if ($configSubSection->name == 'Graphing') {
                // Loop through sub-section's definitions and find all definitions that can track metrics
                foreach ($configSubSection->definitions as $configDefinition) {
                    // Get only definitions which can enable metric tracking
                    if ($configDefinition->monitoringDataFlag) {
                        $cpuGraphingDefinitions[] = $configDefinition;
                    }
                }
            }
        }
    }
    // Find Memory section
    if ($configurationSection->name == 'Memory') {
        // Loop through the sections's sub-sections
        foreach ($configurationSection->subSections as $configSubSection) {
            // Find Graphing sub-section
            if ($configSubSection->name == 'Graphing') {
                // Loop through sub-section's definitions and find all definitions that can track metrics
                foreach ($configSubSection->definitions as $configDefinition) {
                    // Get only definitions which can enable metric tracking
                    if ($configDefinition->monitoringDataFlag) {
                        $memoryGraphingDefinitions[] = $configDefinition;
                    }
                }
            }
        }
    }
}


// Now we can pick specific definitions we want to graph
// for a single metric graph we will use Total CPU Usage
// You can get metric names from the portal interface or
// by printing out each definition's name before hand.
foreach ($cpuGraphingDefinitions as $definition) {
    if ($definition->name == 'Graph Total CPU Usage') {
        $totalCpuUsageDefinition = $definition;
    }
}

// Now we can pick several definitions that have the
// same metric units, which in this case is percentage.
$memoryUsageDefinitions = array();
foreach ($memoryGraphingDefinitions as $definition) {
    if ($definition->name == 'Graph Swap Memory Usage as Percentage' || $definition->name == 'Graph Physical Memory Usage as Percentage') {
        $memoryUsageDefinitions[] = $definition;
    }
}

/**
 * SoftLayer_Monitoring_Agent_Configuration_Value is used to retrieve metric graphs.
 * Check if the agent configuration value for each definition
 * has been enabled. Otherwise, we will not have any data to graph.
 */
foreach ($cdmConfigurationValues as $configurationValue) {
    if ($configurationValue->definition->id == $totalCpuUsageDefinition->id){
        // Found definition value
        if ((bool) $configurationValue->value == false) {
            echo 'Graph Total CPU Usage value is not enabled';
        } else {
            $totalCpuUsageValue = $configurationValue;
        }
    }
    // Since we are going to be using multiple memory metrics
    // we need to check all definitions.
    foreach ($memoryUsageDefinitions as $memoryUsageDefinition) {
        if ($configurationValue->definition->id == $memoryUsageDefinition->id){
            // Found definition value
            if ((bool) $configurationValue->value == false) {
                echo 'Graph Memory definition value is not enabled';
            } else {
                $memoryUsageValues[] = $configurationValue;
            }
        }
    }
}


/**
 * Retrieving graphs for an individual metric.
 *
 * Re-declare our client variable to talk to the
 * SoftLayer_Monitoring_Agent API service.
 *
 * We will be retrieving the "Graph Total CPU Usage" graph.
 */
$client = SoftLayer_SoapClient::getClient('SoftLayer_Monitoring_Agent', $cdmAgent->id, $apiUsername, $apiKey);

try {
    // getGraph() returns a SoftLayer_Container_Monitoring_Graph_Outputs
    // object. The contents of the bandwidth image is in $image->graphImage.
    // From here you can write it to the filesystem, display it to a web
    // browser, or run other functions on it.
    $image = $client->getGraph(array($totalCpuUsageValue), $startDate, $endDate);
    echo 'Image retrieved!';
} catch (Exception $e) {
    die('Unable to retrieve graph image: ' . $e->getMessage());
}


/**
 * Retrieving graphs for combined metrics.
 *
 * *Note*
 * To combine metrics on a single graph they MUST have the same units. Example: percetage or MB/second
 *
 * Re-declare our client variable to talk to the
 * SoftLayer_Monitoring_Agent API service.
 *
 * We will graph "Graph Total CPU Usage" and "Graph Memory Usage as Percentage" together.
 */

$client = SoftLayer_SoapClient::getClient('SoftLayer_Monitoring_Agent', $cdmAgent->id, $apiUsername, $apiKey);

try {
    // getGraph() returns a SoftLayer_Container_Monitoring_Graph_Outputs
    // object. The contents of the bandwidth image is in $image->graphImage.
    // From here you can write it to the filesystem, display it to a web
    // browser, or run other functions on it.
    $image = $client->getGraph($memoryUsageValues, $startDate, $endDate);
    echo 'Image retrieved!';
} catch (Exception $e) {
    die('Unable to retrieve graph image: ' . $e->getMessage());
}