.. meta::
    :description: This documentation will guide you through the use of the Memset API.

.. index::
   double: Methods; server.monitoring

.. _server.monitoring:

Server Monitoring Methods
-------------------------

Server Monitoring API.

.. function:: server.monitoring.get_policy

    Retrieve the current policy for monitoring of named server.
    
    .. seealso:: :func:`server.monitoring.set_policy`
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :returns: A dictionary of flags corresponding to those set by :func:`server.monitoring.set_policy`.

.. function:: server.monitoring.rule_create

    Create a monitoring rule for name.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param service: The monitoring service. Acceptable values
        
        'http'
            HTTP / Apache
        'http_string'
            HTTP string
        'ssh'
            SSH access
        'mysql'
            MySQL (external connectivity)
        'mysql_slave'
            MySQL (slave)
        'smtp'
            SMTP (email)
        'pop3'
            POP3 (email)
        'imap'
            IMAP (email)
        'tcp'
            Other TCP port
        'disk'
            Disk space
        'load'
            Server load
        'ping'
            Ping
        'ssl_cert'
            SSL certificate validity
        
    :type service: String
    
    :param alert_type: The alert type. Note: memset-warning, memset-alert only permitted for Server Monitoring Advanced Memset-monitored customers. Acceptable values
        
        'email'
            Email to:
        'sms'
            SMS to:
        'memset-warning'
            Warn Memset
        'memset-alert'
            Memset Alert 24x7
        
    :type alert_type: String
    
    :param contact_address: The email address or telephone number to which alerts should be sent. Required for non Memset-monitored alert types.
    :type contact_address: String, Optional
    
    :param port: The port number to monitor. Required only for `service` 'tcp' or 'http_string'.
    :type port: Integer, Optional
    
    :param host_name: The host name or URL to check.  Required only for `service` 'http_string'.
    :type host_name: String, Optional
    
    :param http_check_string: The string to check for at `host_name`. Required only for `service` 'http_string'.
    :type http_check_string: String, Optional
    
    :returns: a dictionary with the new rule information in as described in :func:`server.monitoring.rule_info`
    
    :raises: :class:`ApiErrorBadParameters` if the correct combination of parameters have not been provided.
    :raises: :class:`ApiErrorPreconditionFailed` when attempting to set up alerts not within the server's Monitoring support level, or rule quota reached.

.. function:: server.monitoring.rule_delete

    Delete the monitoring rule with rule_id for name
    
    :raises: :class:`ApiErrorBadParameters` if the `rule_id` is not valid.
    :raises: :class:`ApiErrorDoesNotExist` if the `rule_id` does not exist for this account.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param rule_id: The id of the monitoring rule
    :type rule_id: String
    
    

.. function:: server.monitoring.rule_info

    Info about a monitoring rule
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param rule_id: The id of the monitoring rule
    :type rule_id: String
    
    :returns: a dictionary with the following keys
    
        **rule_id**
            String: The unique identifier for this rule.
    
        **service**
            String: The monitoring service for this rule.
    
        **alert_type**
            String: The alert type configured for this rule.
    
        **contact_address**
            String: The email address or telephone number to which alerts for this monitoring rule are sent. It will be empty if
                    the alert_type is a Memset-managed alert type.
    
        **port**
            Integer: It will be empty for a standard `service` e.g. 'http'.
    
        **host_name**
            String: The host name or URL being checked.  It will be empty if the `service` is not 'http_string'.
    
        **http_check_string**
            String: The string being checked.  It will be empty if the `service` is not 'http_string'.
    
    :raises: :class:`ApiErrorDoesNotExist` if the `rule_id` does not exist for this account.

.. function:: server.monitoring.rule_list

    Provides information on Server Monitoring rules for name
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :returns: list of dictionaries as described in :func:`server.monitoring.rule_info`.

.. function:: server.monitoring.rule_update

    Update the monitoring rule with rule_id for name
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param rule_id: The id of the monitoring rule
    :type rule_id: String
    
    :param service: The monitoring service. Acceptable values
        
        'http'
            HTTP / Apache
        'http_string'
            HTTP string
        'ssh'
            SSH access
        'mysql'
            MySQL (external connectivity)
        'mysql_slave'
            MySQL (slave)
        'smtp'
            SMTP (email)
        'pop3'
            POP3 (email)
        'imap'
            IMAP (email)
        'tcp'
            Other TCP port
        'disk'
            Disk space
        'load'
            Server load
        'ping'
            Ping
        'ssl_cert'
            SSL certificate validity
        
    :type service: String, Optional
    
    :param alert_type: The alert type. Note: memset-warning, memset-alert only permitted for Server Monitoring Advanced Memset-monitored customers. Acceptable values
        
        'email'
            Email to:
        'sms'
            SMS to:
        'memset-warning'
            Warn Memset
        'memset-alert'
            Memset Alert 24x7
        
    :type alert_type: String, Optional
    
    :param contact_address: The email address or telephone number to which alerts should be sent. Required for non Memset-monitored alert types.
    :type contact_address: String, Optional
    
    :param port: The port number to monitor. Required only for `service` 'tcp'.
    :type port: Integer, Optional
    
    :param host_name: The host name or URL to check.  Required only for `service` 'http_string'.
    :type host_name: String, Optional
    
    :param http_check_string: The string to check for at `host_name`. Required only for `service` 'http_string'.
    :type http_check_string: String, Optional
    
    :returns: a dictionary with the rule information in as described in :func:`server.monitoring.rule_info`
    
    :raises: :class:`ApiErrorBadParameters` if the `rule_id` is invalid or the updated rule is invalid.

.. function:: server.monitoring.set_policy

    Set the monitoring policy for the named server.
    
    .. seealso:: :func:`server.monitoring.get_policy`
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param monitoring: Whether or not monitoring is enabled for the named server.
    :type monitoring: Boolean
    
    :param auto_reboot: 
            Whether or not to automatically reboot the named server if monitoring
            determines that it has becomes unresponsive. This defaults to true when
            monitoring is *enabled*.
        
            .. NOTE::
                This flag can only be set when when monitoring is *enabled*,
                trying to set it to true when this is not the case will result in an
                API error.
            
    :type auto_reboot: Boolean, Optional
    
    :param reminder_emails: 
            Whether or not to send a reminder at regular intervals about monitoring
            being disabled. The reminder is sent to the email address associated with
            your account. This defaults to true when monitoring is *disabled*.
        
            .. NOTE::
                This flag can only be set when when monitoring is *disabled*,
                trying to set it to true when this is not the case will result in an
                API error.
            
    :type reminder_emails: Boolean, Optional
    
    :returns: A dictionary as described in :func:`job.status`.
    :raises: Will raise :class:`ApiErrorBadParameters` for incompatible combinations of flags.
    :raises: Will raise :class:`ApiErrorAlreadyInProgress` if a policy change is already in progress.