MAPI - Log Resources
====================

..  versionadded:: 0.9.3

..  automodule:: hcpsdk.mapi
    :synopsis: Access to selected Management API (:term:`MAPI`) functionality.

This class allows to request internal logs from HCP, which will then prepare
a zip-file to be downloaded later on.

..  Note::

    To be able to use this class, HCP needs to run at least
    **version 7.2**.

The usage pattern is this:

    *  *prepare()*
    *  check the *status()* until *readyForStreaming* is True, then
    *  *download()* the logs
    *  save the zip'ed logs or process them, what ever is needed.
    *  *close()* the underlying *Connection()* object


Classes
-------

.. _hcpsdk_mapi_logs:

Logs
^^^^

..  autoclass:: Logs

    **Class constants:**

    Log types:

        ..  attribute:: L_ACCESS

            The log files *http_gateway_request.log.x*,
            *mapi_gateway_request.log.x* and *admin_request.log.x* contain all
            HTTP access messages that includes all of the HTTP based (SMC,
            TMC, MAPI, MQE, REST, HS3, HSwift) gateway logs. MAPI and Admin
            will contain all the system level access information while http
            gateway contains TMC and namespace access info.

        ..  attribute:: L_SYSTEM

            This is a snapshot of the running system when the logs were
            captured. This includes the messages that are generated by HCP OS,
            the firewall and routing rules, the fiber channel info and many
            others and are always important as a first step for support to go
            over.

        ..  attribute:: L_SERVICE

            These are logs generated when performing any of the service
            procedures such as when installing HCP software, adding a node,
            adding a LUN, node recovery etc.

        ..  attribute:: L_APPLICATION

            These are logs from all the HCP specific services such as the JVM,
            the volume manager, storman etc.

        ..  attribute:: L_ALL

            A list containing all other L_* log types.

   **Class attributes**

   ..   attribute:: suggestedfilename

        When a *download* has been started, this attribute holds the filename
        suggested by HCP.

   **Class methodes:**

   ..   automethod:: mark

   ..   automethod:: prepare

   ..   automethod:: status

   ..   automethod:: download

   ..   automethod:: cancel

   ..   automethod:: close



Exceptions
----------

..  autoexception:: LogsError

..  autoexception:: LogsNotReadyError

..  autoexception:: LogsInProgessError

Sample Code
-----------

The following :download:`example code <../80_examples/code/mapilogshell.py>`
creates a simple command processor that allows to prepare and download logs
from HCP.

    ..  include:: ../80_examples/code/mapilogshell.py
        :literal:

Sample Output
-------------

    ..  include:: ../80_examples/output/mapilogshell.txt
        :literal: