Amon+ usage example

README.rst

@@ -9,16 +9,16 @@ Amonpy is the Python client for Amon
 ===============
 
 
-1. Install the package with ``pip install amonpy`` or alternatively you can  
+1. Install the package with ``pip install amonpy`` or alternatively you can
 download the tarball and run ``python setup.py install``
 
 
 ===============
- Configuration 
+ Configuration
 ===============
 
 
-:: 
+::
 
     import amonpy
     amonpy.config.address = 'http://amonhost:port'
@@ -27,13 +27,15 @@ download the tarball and run ``python setup.py install``
 
 
 =========
- Usage 
+ Usage
 =========
 
+You can use amopy module to send log messages or exceptions to the Amon server.
+
 ::
-    
+
     import amonpy
-    
+
     amonpy.log(message)
     amonpy.log(message, ['list', 'of', 'tags'])
 
@@ -46,33 +48,107 @@ download the tarball and run ``python setup.py install``
         'data': ''
 
     }
-    
+
     amonpy.exception(data)
 
+========================================
+ More complex usage example (Amon Plus)
+========================================
+
+Here is an example script how to log custom errors to Amon+ service.
+The script monitors a certain file and if this file is gone or not have been
+refreshed for a while then an exception is logged.
+
+* All communication is done over HTTP. Amon and Amon+ expose a JSON based loggin API
+
+* **Amon+ requires application key** for all log messages. Create application
+  key in Amon+ web interface and put it into the script
+
+* To use this script you can simply drop it to ``/etc/cron.daily`` folder
+  on your server where the log file must be monitored.
+
+* In Amon+ you can connect this log message to an email alert, based on tags, and thus have incoming
+  message when things go bad
+
+Example code::
+
+    #!/usr/bin/python
+    """
+
+        A simple Amon script to monitor whether a file has been updated recently.
+
+    """
+
+    import os
+    import amonpy
+    import time
+    import socket
+    import sys
+
+    # The script identifies itself as server name + script name pair in log messages
+    MY_NAME = socket.gethostname() + ":" + os.path.abspath(os.path.join(os.getcwd(), sys.argv[0]))
+
+    # Which tags we set on our log entry
+    # Later can be used to configurae alerts in amon+
+    TAGS = ["error"]
+
+    FILENAME = "/var/log/serious-log-file.log"
+
+    #: Threshold time in seconds - one hour
+    THRESHOLD = 60*60
+
+    # amonpy connects to the server via http/zeromg and application key secret
+    amonpy.config.address = 'http://your.amonplus.server.com:2464'
+    amonpy.config.application_key = "xxxxx"
+
+
+    def log_error(message):
+        """
+        Send message to amon logs. stamped with info where it is coming from
+        """
+        amonpy.log("%s: %s" % (MY_NAME, message), TAGS)
+        sys.exit(message)  # Terminate the script with output to terminal
+
+
+    def main():
+        """
+        Check if file last modification date is too old and log an error in Amon.
+        """
+        if not os.path.exists(FILENAME):
+            log_error("File is gone: %s" % FILENAME)
+
+        modification_time = os.path.getmtime(FILENAME)
+
+        age = time.time() - modification_time
+        if age > THRESHOLD:
+            log_error("File is not up-to-date: %s" % FILENAME)
+
+
+    main()
 
 
 ================
- Django 
+ Django
 ================
 
-Using amonpy in Django is exactly the same as in every other python library. You can customize the config options 
+Using amonpy in Django is exactly the same as in every other python library. You can customize the config options
 by adding them somewhere in `settings.py`
 
-:: 
+::
 
     # in settings.py
     import amonpy
-    amon.config.address = 'http://amonhost:port' 
+    amon.config.address = 'http://amonhost:port'
 
 
 To capture and log exceptions
 
-:: 
+::
 
-   MIDDLEWARE_CLASSES = (        
+   MIDDLEWARE_CLASSES = (
     .....
     'amonpy.adapters.DjangoExceptionMiddleware'
-    ) 
+    )
 
 ===============
  Requirements