:doc:`IoTEventsData <../../iotevents-data>` / Client / describe_alarm

**************
describe_alarm
**************



.. py:method:: IoTEventsData.Client.describe_alarm(**kwargs)

  

  Retrieves information about an alarm.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/iotevents-data-2018-10-23/DescribeAlarm>`_  


  **Request Syntax**
  ::

    response = client.describe_alarm(
        alarmModelName='string',
        keyValue='string'
    )
    
  :type alarmModelName: string
  :param alarmModelName: **[REQUIRED]** 

    The name of the alarm model.

    

  
  :type keyValue: string
  :param keyValue: 

    The value of the key used as a filter to select only the alarms associated with the `key <https://docs.aws.amazon.com/iotevents/latest/apireference/API_CreateAlarmModel.html#iotevents-CreateAlarmModel-request-key>`__.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'alarm': {
              'alarmModelName': 'string',
              'alarmModelVersion': 'string',
              'keyValue': 'string',
              'alarmState': {
                  'stateName': 'DISABLED'|'NORMAL'|'ACTIVE'|'ACKNOWLEDGED'|'SNOOZE_DISABLED'|'LATCHED',
                  'ruleEvaluation': {
                      'simpleRuleEvaluation': {
                          'inputPropertyValue': 'string',
                          'operator': 'GREATER'|'GREATER_OR_EQUAL'|'LESS'|'LESS_OR_EQUAL'|'EQUAL'|'NOT_EQUAL',
                          'thresholdValue': 'string'
                      }
                  },
                  'customerAction': {
                      'actionName': 'SNOOZE'|'ENABLE'|'DISABLE'|'ACKNOWLEDGE'|'RESET',
                      'snoozeActionConfiguration': {
                          'snoozeDuration': 123,
                          'note': 'string'
                      },
                      'enableActionConfiguration': {
                          'note': 'string'
                      },
                      'disableActionConfiguration': {
                          'note': 'string'
                      },
                      'acknowledgeActionConfiguration': {
                          'note': 'string'
                      },
                      'resetActionConfiguration': {
                          'note': 'string'
                      }
                  },
                  'systemEvent': {
                      'eventType': 'STATE_CHANGE',
                      'stateChangeConfiguration': {
                          'triggerType': 'SNOOZE_TIMEOUT'
                      }
                  }
              },
              'severity': 123,
              'creationTime': datetime(2015, 1, 1),
              'lastUpdateTime': datetime(2015, 1, 1)
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **alarm** *(dict) --* 

        Contains information about an alarm.

        
        

        - **alarmModelName** *(string) --* 

          The name of the alarm model.

          
        

        - **alarmModelVersion** *(string) --* 

          The version of the alarm model.

          
        

        - **keyValue** *(string) --* 

          The value of the key used as a filter to select only the alarms associated with the `key <https://docs.aws.amazon.com/iotevents/latest/apireference/API_CreateAlarmModel.html#iotevents-CreateAlarmModel-request-key>`__.

          
        

        - **alarmState** *(dict) --* 

          Contains information about the current state of the alarm.

          
          

          - **stateName** *(string) --* 

            The name of the alarm state. The state name can be one of the following values:

             

            
            * ``DISABLED`` - When the alarm is in the ``DISABLED`` state, it isn't ready to evaluate data. To enable the alarm, you must change the alarm to the ``NORMAL`` state.
             
            * ``NORMAL`` - When the alarm is in the ``NORMAL`` state, it's ready to evaluate data.
             
            * ``ACTIVE`` - If the alarm is in the ``ACTIVE`` state, the alarm is invoked.
             
            * ``ACKNOWLEDGED`` - When the alarm is in the ``ACKNOWLEDGED`` state, the alarm was invoked and you acknowledged the alarm.
             
            * ``SNOOZE_DISABLED`` - When the alarm is in the ``SNOOZE_DISABLED`` state, the alarm is disabled for a specified period of time. After the snooze time, the alarm automatically changes to the ``NORMAL`` state.
             
            * ``LATCHED`` - When the alarm is in the ``LATCHED`` state, the alarm was invoked. However, the data that the alarm is currently evaluating is within the specified range. To change the alarm to the ``NORMAL`` state, you must acknowledge the alarm.
            

            
          

          - **ruleEvaluation** *(dict) --* 

            Information needed to evaluate data.

            
            

            - **simpleRuleEvaluation** *(dict) --* 

              Information needed to compare two values with a comparison operator.

              
              

              - **inputPropertyValue** *(string) --* 

                The value of the input property, on the left side of the comparison operator.

                
              

              - **operator** *(string) --* 

                The comparison operator.

                
              

              - **thresholdValue** *(string) --* 

                The threshold value, on the right side of the comparison operator.

                
          
        
          

          - **customerAction** *(dict) --* 

            Contains information about the action that you can take to respond to the alarm.

            
            

            - **actionName** *(string) --* 

              The name of the action. The action name can be one of the following values:

               

              
              * ``SNOOZE`` - When you snooze the alarm, the alarm state changes to ``SNOOZE_DISABLED``.
               
              * ``ENABLE`` - When you enable the alarm, the alarm state changes to ``NORMAL``.
               
              * ``DISABLE`` - When you disable the alarm, the alarm state changes to ``DISABLED``.
               
              * ``ACKNOWLEDGE`` - When you acknowledge the alarm, the alarm state changes to ``ACKNOWLEDGED``.
               
              * ``RESET`` - When you reset the alarm, the alarm state changes to ``NORMAL``.
              

               

              For more information, see the `AlarmState <https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_AlarmState.html>`__ API.

              
            

            - **snoozeActionConfiguration** *(dict) --* 

              Contains the configuration information of a snooze action.

              
              

              - **snoozeDuration** *(integer) --* 

                The snooze time in seconds. The alarm automatically changes to the ``NORMAL`` state after this duration.

                
              

              - **note** *(string) --* 

                The note that you can leave when you snooze the alarm.

                
          
            

            - **enableActionConfiguration** *(dict) --* 

              Contains the configuration information of an enable action.

              
              

              - **note** *(string) --* 

                The note that you can leave when you enable the alarm.

                
          
            

            - **disableActionConfiguration** *(dict) --* 

              Contains the configuration information of a disable action.

              
              

              - **note** *(string) --* 

                The note that you can leave when you disable the alarm.

                
          
            

            - **acknowledgeActionConfiguration** *(dict) --* 

              Contains the configuration information of an acknowledge action.

              
              

              - **note** *(string) --* 

                The note that you can leave when you acknowledge the alarm.

                
          
            

            - **resetActionConfiguration** *(dict) --* 

              Contains the configuration information of a reset action.

              
              

              - **note** *(string) --* 

                The note that you can leave when you reset the alarm.

                
          
        
          

          - **systemEvent** *(dict) --* 

            Contains information about alarm state changes.

            
            

            - **eventType** *(string) --* 

              The event type. If the value is ``STATE_CHANGE``, the event contains information about alarm state changes.

              
            

            - **stateChangeConfiguration** *(dict) --* 

              Contains the configuration information of alarm state changes.

              
              

              - **triggerType** *(string) --* 

                The trigger type. If the value is ``SNOOZE_TIMEOUT``, the snooze duration ends and the alarm automatically changes to the ``NORMAL`` state.

                
          
        
      
        

        - **severity** *(integer) --* 

          A non-negative integer that reflects the severity level of the alarm.

          
        

        - **creationTime** *(datetime) --* 

          The time the alarm was created, in the Unix epoch format.

          
        

        - **lastUpdateTime** *(datetime) --* 

          The time the alarm was last updated, in the Unix epoch format.

          
    
  
  **Exceptions**
  
  *   :py:class:`IoTEventsData.Client.exceptions.InvalidRequestException`

  
  *   :py:class:`IoTEventsData.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`IoTEventsData.Client.exceptions.ThrottlingException`

  
  *   :py:class:`IoTEventsData.Client.exceptions.InternalFailureException`

  
  *   :py:class:`IoTEventsData.Client.exceptions.ServiceUnavailableException`

  