initial version

Author: thraxil

README.markdown

@@ -0,0 +1,98 @@
+This is a Django application to make it a bit simpler to use 
+Munin (http://munin-monitoring.org/) to monitor various metrics
+for your Django app. 
+
+First, it includes a munin plugin that you can symlink into
+/etc/munin/plugins/ and point at your django application and it will
+gather data for munin to graph. Second, it contains a couple views
+that return some very basic information about the state of your app:
+database performance, number of users, number of sessions, etc. Third,
+it provides a decorator to make it simple to expose your own custom
+metrics to Munin. 
+
+Install django-munin into your python path with the usual pip install
+or whatever you are doing. Then add 'munin' to your INSTALLED_APPS and
+run 'manage.py syncdb' (it just needs to set up one database table
+that it will use for performance testing). 
+
+To access the included basic views, add the following pattern to your
+urls.py: 
+
+   ('^munin/',include('munin.urls')),
+
+The views available there are then going to be at:
+
+    * munin/db_performance/   (milliseconds to perform insert/select/delete operations)
+    * munin/total_users/      (total number of Users)
+    * munin/active_users/     (number of users logged in in the last hour)
+    * munin/total_sessions/   (total number of sessions)
+    * munin/active_sessions/  (number of sessions that are not expired)
+
+Those were the only metrics I could think of that would be potentially
+useful on just about any Django app and were likely to always be
+available. 
+
+(I'm going to assume that you are already a pro at configuring
+Munin. If not, go get on that. Munin is very cool)  
+
+Next, copy scripts/django.py into your /usr/share/munin/plugins/
+directory. 
+
+For each metric that you want Munin to monitor, make a symlink in
+/etc/munin/plugins/ to /usr/share/munin/plugins/django.py with an
+appropriate name. Eg, to monitor all five of the included ones (as
+root, probably):
+
+    $ ln -s /usr/share/munin/plugins/django.py /etc/munin/plugins/myapp_db_performance
+    $ ln -s /usr/share/munin/plugins/django.py /etc/munin/plugins/myapp_total_users
+    $ ln -s /usr/share/munin/plugins/django.py /etc/munin/plugins/myapp_active_users
+    $ ln -s /usr/share/munin/plugins/django.py /etc/munin/plugins/myapp_total_sessions
+    $ ln -s /usr/share/munin/plugins/django.py /etc/munin/plugins/myapp_active_sessions
+
+You then need to configure each of them in
+/etc/munin/plugin-conf.d/munin-node
+
+For each, give it a stanza with env.url and graph_category set. To
+continue the above, you'd add something like: 
+
+    [myapp_db_performance]
+    env.url http://example.com/munin/db_performance/
+    graph_category myapp
+
+    [myapp_total_users]
+    env.url http://example.com/munin/total_users/
+    graph_category myapp
+
+    [myapp_active_users]
+    env.url http://example.com/munin/active_users/
+    graph_category myapp
+
+    [myapp_total_sessions]
+    env.url http://example.com/munin/total_sessions/
+    graph_category myapp
+
+    [myapp_active_sessions]
+    env.url http://example.com/munin/active_sessions/
+    graph_category myapp
+
+Restart your Munin node, and it should start collecting and graphing
+that data. 
+
+Those are pretty generic metrics though and the real power of this
+application is that you can easily expose your own custom
+metrics. Basically, anything that you can calculate in the context of
+a Django view in your application, you can easily expose to Munin. 
+
+django-munin includes a 'muninview' decorator that lets you write a
+regular django view that returns a list of (key,value) tuples and it
+will expose those to that django.py munin plugin for easy graphing. 
+
+The @muninview decorator takes a config parameter, which is just a
+string of munin config directives. You'll want to put stuff like
+graph_title, graph_vlabel, and graph_info there. Possibly
+graph_category too (if you include it there, remove it from the munin
+plugin conf stanza). The view function that it wraps then just needs
+to return a list of tuples.
+
+The simplest way to get a feel for how this works is to look at how
+the included views were written. So check out munin/views.py.  

munin/__init__.py

@@ -0,0 +1,21 @@
+from django.http import HttpResponse
+
+class muninview(object):
+    """ decorator to make it simpler to write munin views """
+    def __init__(self,config=""):
+        self.config = config
+
+    def __call__(self, func):
+        def rendered_func(request, *args, **kwargs):
+            tuples = func(request, *args, **kwargs)
+            if 'autoconfig' in request.GET:
+                return HttpResponse("yes")
+            if 'config' in request.GET:
+                rows = ["%s.label %s" % (t[0].replace(" ","_"),t[0]) for t in tuples]
+                return HttpResponse("\n".join([self.config] + rows))
+            if type(tuples) == type([]):
+                rows = ["%s %s" % (t[0].replace(" ","_"),str(t[1])) for t in tuples]
+                return HttpResponse("\n".join(rows))
+            else:
+                return tuples
+        return rendered_func

munin/helpers.py

@@ -0,0 +1,4 @@
+from django.db import models
+
+class Test(models.Model):
+    name = models.CharField(max_length=256)

munin/models.py

@@ -0,0 +1,9 @@
+from django.conf.urls.defaults import *
+
+urlpatterns = patterns('',
+                       (r'^total_users/$','munin.views.total_users'),
+                       (r'^active_users/$','munin.views.active_users'),
+                       (r'^total_sessions/$','munin.views.total_sessions'),
+                       (r'^active_sessions/$','munin.views.active_sessions'),
+                       (r'^db_performance/$','munin.views.db_performance'),
+)

munin/urls.py

@@ -0,0 +1,49 @@
+from helpers import muninview
+from django.contrib.auth.models import User
+from django.contrib.sessions.models import Session
+from datetime import datetime
+from datetime import timedelta
+import time
+from models import Test
+
+@muninview(config="""graph_title Total Users
+graph_vlabel users""")
+def total_users(request):
+    return [("users",User.objects.all().count())]
+
+@muninview(config="""graph_title Active Users
+graph_vlabel users
+graph_info Number of users logged in during the last hour""")
+def active_users(request):
+    hour_ago = datetime.now() - timedelta(hours=1)
+    return [("users",User.objects.filter(last_login__gt=hour_ago).count())]
+
+@muninview(config="""graph_title Total Sessions
+graph_vlabel sessions""")
+def total_sessions(request):
+    return [("sessions",Session.objects.all().count())]
+
+@muninview(config="""graph_title Active Sessions
+graph_vlabel sessions""")
+def active_sessions(request):
+    return [("sessions",Session.objects.filter(expire_date__gt=datetime.now()).count())]
+
+@muninview(config="""graph_title DB performance
+graph_vlabel milliseconds
+graph_info performance of simple insert/select/delete operations""")
+def db_performance(request):
+    start = time.time()
+    t = Test.objects.create(name="inserting at %f" % start)
+    end = time.time()
+    insert = end - start
+    start = time.time()
+    t2 = Test.objects.get(id=t.id)
+    end = time.time()
+    select = end - start
+    start = time.time()
+    t2.delete()
+    end = time.time()
+    delete = end - start
+    return [("insert",1000 * insert),
+            ("select",1000 * select),
+            ("delete",1000 * delete)]

munin/views.py

@@ -0,0 +1,22 @@
+#!/usr/bin/python
+import sys
+import urllib2
+import os
+
+url = os.environ['url']
+category = os.environ.get('graph_category',"")
+
+if len(sys.argv) == 2:
+    url = url + "?" + sys.argv[1] + "=1"
+    print urllib2.urlopen(url).read()
+    # they can set the category in the config
+    if category != "":
+        print "graph_category " + category
+else:
+    data = urllib2.urlopen(url).readlines()
+    for line in data:
+        parts = line.split(" ")
+        label = parts[0]
+        value = " ".join(parts[1:])
+        print label + ".value " + value 
+        

plugins/django.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2011, Columbia Center For New Media Teaching And Learning (CCNMTL)
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of the CCNMTL nor the
+#       names of its contributors may be used to endorse or promote products
+#       derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY CCNMTL ``AS IS'' AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL <copyright holder> BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+from setuptools import setup, find_packages
+
+setup(
+    name="django-munin",
+    version="0.1.1",
+    author="Anders Pearson",
+    author_email="anders@columbia.edu",
+    url="http://github.com/ccnmtl/django-munin/",
+    description="Munin adaptor for Django",
+    long_description="Helper application for using munin to monitor your Django apps",
+    install_requires = [],
+    scripts = [],
+    license = "BSD",
+    platforms = ["any"],
+    zip_safe=False,
+    package_data = {'' : ['*.*']},
+    packages=['munin'],
+    test_suite='nose.collector',
+    )
+