documentation/manual/en/module_specs/Zend_Log-Writers-ZendMonitor.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.log.writers.zendmonitor">
   4     <title>Writing to the Zend Server Monitor</title>
   5
   6     <para>
   7         <classname>Zend_Log_Writer_ZendMonitor</classname> allows you to log events via Zend
   8         Server's Monitor <acronym>API</acronym>. This allows you to aggregate log messages for your
   9         entire application environment in a single location. Internally, it simply uses the
  10         <methodname>monitor_custom_event()</methodname> function from the Zend Monitor
  11         <acronym>API</acronym>.
  12     </para>
  13
  14     <para>
  15         One particularly useful feature of the Monitor <acronym>API</acronym> is that it allows you
  16         to specify arbitrary custom information alongside the log message. For instance, if you wish
  17         to log an exception, you can log not just the exception message, but pass the entire
  18         exception object to the function, and then inspect the object within the Zend Server event
  19         monitor.
  20     </para>
  21
  22     <note>
  23         <title>Zend Monitor must be installed and enabled</title>
  24
  25         <para>
  26             In order to use this log writer, Zend Monitor must be both installed and enabled.
  27             However, it is designed such that if Zend Monitor is not detected, it will simply act as
  28             a <constant>NULL</constant> logger.
  29         </para>
  30     </note>
  31
  32     <para>
  33         Instantiating the <classname>ZendMonitor</classname> log writer is trivial:
  34     </para>
  35
  36     <programlisting language="php"><![CDATA[
  37 $writer = new Zend_Log_Writer_ZendMonitor();
  38 $log    = new Zend_Log($writer);
  39 ]]></programlisting>
  40
  41     <para>
  42         Then, simply log messages as usual:
  43     </para>
  44
  45     <programlisting language="php"><![CDATA[
  46 $log->info('This is a message');
  47 ]]></programlisting>
  48
  49     <para>
  50         If you want to specify additional information to log with the event, pass that information
  51         in a second parameter:
  52     </para>
  53
  54     <programlisting language="php"><![CDATA[
  55 $log->info('Exception occurred', $e);
  56 ]]></programlisting>
  57
  58     <para>
  59         The second parameter may be a scalar, object, or array; if you need to pass multiple pieces
  60         of information, the best way to do so is to pass an associative array.
  61     </para>
  62
  63     <programlisting language="php"><![CDATA[
  64 $log->info('Exception occurred', array(
  65     'request'   => $request,
  66     'exception' => $e,
  67 ));
  68 ]]></programlisting>
  69
  70     <para>
  71         Within Zend Server, your event is logged as a "custom event". From the "Monitor" tab, select
  72         the "Events" sub-item, and then filter on "Custom" to see custom events.
  73     </para>
  74
  75     <para>
  76         <inlinegraphic fileref="figures/zend.log.writers.zendmonitor-events.png" format="PNG" />
  77     </para>
  78
  79     <para>
  80         Events in Zend Server's Monitor dashboard
  81     </para>
  82
  83     <para>
  84         In this screenshot, the first two events listed are custom events logged via the
  85         <classname>ZendMonitor</classname> log writer. You may then click on an event to view all
  86         information related to it.
  87     </para>
  88
  89     <para>
  90         <inlinegraphic fileref="figures/zend.log.writers.zendmonitor-event.png" format="PNG" />
  91     </para>
  92
  93     <para>
  94         Event detail in Zend Server's Monitor
  95     </para>
  96
  97     <para>
  98         Clicking on the "Custom" sub tab will detail any extra information you logged by passing the
  99         second argument to the logging method. This information will be logged as the
 100         <varname>info</varname> subkey; you can see that the request object was logged in this
 101         example.
 102     </para>
 103
 104     <note>
 105         <title>Integration with Zend_Application</title>
 106
 107         <para>
 108             By default, the <command>zf.sh</command> and <command>zf.bat</command> commands add
 109             configuration for the <link
 110                 linkend="zend.application.available-resources.log"><classname>Zend_Application</classname>
 111                 log resource</link>, which includes configuration for the
 112             <classname>ZendMonitor</classname> log writer. Additionally, the
 113             <classname>ErrorController</classname> uses the configured logger to log application
 114             exceptions -- providing you with Zend Monitor event integration by default.
 115         </para>
 116
 117         <para>
 118             As noted previously, if the Monitor <acronym>API</acronym> is not detected in your
 119             <acronym>PHP</acronym> installation, the logger will simply act as a
 120             <constant>NULL</constant> logger.
 121         </para>
 122     </note>
 123 </sect2>