repo_zf1/documentation/manual/en/module_specs/Zend_Service_WindowsAzure_Manager.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.windowsazure.diagnostics.manager">
    <title>Zend_Service_WindowsAzure_Diagnostics_Manager</title>

    <para>
        Blob Storage stores sets of binary data. Blob storage offers the following three
        Windows Azure Diagnostics enables you to collect diagnostic data from a service
        running in Windows Azure. It can be used for tasks like debugging and
        troubleshooting, measuring performance, monitoring resource usage, traffic
        analysis, capacity planning, and auditing. Once collected, diagnostic data can be
        transferred to a Windows Azure storage account for persistence. Transfers can
        either be scheduled or on-demand.
    </para>

    <para>
        You can configure Windows Azure Diagnostics from code running within a role. You
        can also configure it remotely from an application running outside of the Windows
        Azure; for example, you can manage Windows Azure Diagnostics from a custom
        dashboard application running locally. By managing Windows Azure Diagnostics
        remotely, you can start your service with an initial diagnostic configuration,
        and then tweak that configuration from code running outside of your service,
        without having to upgrade your service.
    </para>

    <para>
        More information on which logs, performance counters, crash dumps, ...
        can be monitored can be found on the <ulink
        url="http://msdn.microsoft.com/en-us/library/ee758705(v=MSDN.10).aspx">
        corresponding MSDN web page</ulink>.
    </para>

    <para>
        Note: Diagnostics are configured on a per-role basis. This means that each
        role should be configured separately. Specifying diagnostics instructions
        for one role instance does not imply this configuration is loaded on other
        role instances.
    </para>

    <para>
        Note: Diagnostics are configured on a per-role basis. This means that each
        The Diagnostics API in the Windows Azure SDK for PHP can only be used when
        the DiagnosticsMonitor has been started during role startup. Currently,
        this is only supported when an application is packaged with the Windows
        Azure Command-line Tools for PHP Developers.
    </para>

    <sect2 id="zend.service.windowsazure.diagnostics.manager.api">
        <title>API Examples</title>

        <para>
            This topic lists some examples of using the
            <classname>Zend_Service_WindowsAzure_Diagnostics_Manager</classname> class.  Other features are
            available in the download package, as well as a detailed API documentation of those
            features.
        </para>

        <sect3 id="zend.service.windowsazure.diagnostics.manager.api.config-exists">
            <title>Checking if a diagnostics configuration for the current role instance exists</title>

            <para>
                Using the following code, you can check if a diagnostics configuration for the
                current role instance exists.
            </para>

            <example id="zend.service.windowsazure.diagnostics.manager.api.config-exists.example">
                <title>Checking if a diagnostics configuration for the current role instance exists</title>

                <programlisting language="php"><![CDATA[
/** Zend_Service_WindowsAzure_Storage_Blob */
require_once 'Zend/Service/WindowsAzure/Storage/Blob.php';

/** Zend_Service_WindowsAzure_Diagnostics_Manager */
require_once 'Zend/Service/WindowsAzure/Diagnostics/Manager.php';

$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$manager = new Zend_Service_WindowsAzure_Diagnostics_Manager($storageClient);

$configurationExists = $manager->configurationForCurrentRoleInstanceExists();

echo 'The configuration ' . ($configurationExists ? 'exists' : 'does not exist';
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.diagnostics.manager.api.config-load">
            <title>Loading the current role instance diagnostics configuration</title>

            <para>
                Using the following code, you can load the current role instance diagnostics
                configuration.
            </para>

            <example id="zend.service.windowsazure.diagnostics.manager.api.config-load.example">
                <title>Loading the current role instance diagnostics configuration</title>

                <programlisting language="php"><![CDATA[
/** Zend_Service_WindowsAzure_Storage_Blob */
require_once 'Zend/Service/WindowsAzure/Storage/Blob.php';

/** Zend_Service_WindowsAzure_Diagnostics_Manager */
require_once 'Zend/Service/WindowsAzure/Diagnostics/Manager.php';

$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$manager = new Zend_Service_WindowsAzure_Diagnostics_Manager($storageClient);

$configuration = $manager->getConfigurationForCurrentRoleInstance();
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.diagnostics.manager.api.config-store">
            <title>Storing the current role instance diagnostics configuration</title>

            <para>
                Using the following code, you can store the current role instance diagnostics
                configuration.
            </para>

            <example id="zend.service.windowsazure.diagnostics.manager.api.config-store.example">
                <title>Storing the current role instance diagnostics configuration</title>

                <programlisting language="php"><![CDATA[
/** Zend_Service_WindowsAzure_Storage_Blob */
require_once 'Zend/Service/WindowsAzure/Storage/Blob.php';

/** Zend_Service_WindowsAzure_Diagnostics_Manager */
require_once 'Zend/Service/WindowsAzure/Diagnostics/Manager.php';

$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$manager = new Zend_Service_WindowsAzure_Diagnostics_Manager($storageClient);

$configuration = // ...;
$manager->setConfigurationForCurrentRoleInstance($configuration);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.diagnostics.manager.api.config-perf">
            <title>Subscribing to a performance counter</title>

            <para>
                Using the following code, you can subscribe to a performance counter.
            </para>

            <example id="zend.service.windowsazure.diagnostics.manager.api.config-perf.example">
                <title>Subscribing to a performance counter</title>

                <programlisting language="php"><![CDATA[
/** Zend_Service_WindowsAzure_Storage_Blob */
require_once 'Zend/Service/WindowsAzure/Storage/Blob.php';

/** Zend_Service_WindowsAzure_Diagnostics_Manager */
require_once 'Zend/Service/WindowsAzure/Diagnostics/Manager.php';

$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$manager = new Zend_Service_WindowsAzure_Diagnostics_Manager($storageClient);

$configuration = $manager->getConfigurationForCurrentRoleInstance();

// Subscribe to \Processor(*)\% Processor Time
$configuration->DataSources->PerformanceCounters->addSubscription('\Processor(*)\% Processor Time', 1);

$manager->setConfigurationForCurrentRoleInstance($configuration);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.diagnostics.manager.api.config-roleid">
            <title>Getting the current role instance id</title>

            <para>
                The current role instance id is defined in the server variable
                RdRoleId. It will only be available when the application is run in
                Development Fabric or Windows Azure Fabric.
            </para>

            <example id="zend.service.windowsazure.diagnostics.manager.api.config-roleid.example">
                <title>Getting the current role instance id</title>

                <programlisting language="php"><![CDATA[
echo 'The role instance id is ' . $_SERVER['RdRoleId'];
]]></programlisting>
            </example>
        </sect3>
    </sect2>
</sect1>