README.rdoc in zenoss_client-0.10.0 vs README.rdoc in zenoss_client-0.10.1
- old
+ new
@@ -1,86 +1,173 @@
\ No newline at end of file
+h1. zenoss_client: A Ruby library for JSON/REST access to Zenoss
+
+This is a work-in-progress to create an easy to use client JSON/REST API for
+Zenoss (http://www.zenoss.com) written in Ruby. I love Zenoss as a product,
+but I am much more efficient in Ruby than Python so I decided to start
+hacking this library together. It is very incomplete and I am just adding
+functionality as I need it or it is requested.
+
+Cheers,
+
+Dan Wanek
+
+h2. CHANGES SINCE THE 0.1.x BRANCH
+
+Starting with 0.5.0 I am trying to incorporate as much of the new JSON API
+into this library as possible because the type conversion hackery that was
+present in the REST code is largely unnecessary. Please note that the
+initialization is much different because we are using the sign-in form auth
+instead of the Basic auth of the previous version. This is because the JSON
+calls do not support Basic authentication.
+
+There is still much work that needs to be done in order to fully implement
+all of the JSON methods. For now many of the older features fall back to
+REST and some of those will always rely on REST because they are not
+currently supported in the JSON API.
+
+
+h2. REQUIREMENTS:
+Gems:
+
+* tzinfo: For Python DateTime to Ruby DateTime conversion
+
+
+h2. UNSUPPORTED REST METHODS:
+Some methods within Zope are unsupported due to type conversion issues.
+I have created a work-around but you must add a custom Python script
+to Zope in order to do this. Please see this blog post for information
+on how add the custom script:
+
+http://distributed-frostbite.blogspot.com/2010/04/using-ruby-with-zenoss-part-1.html
+
+UPDATE: The script itself is now part of the source tree and can be found here: tools/callZenossMethod.py
+It should still be installed in the same fashion as the blog post steps through.
+
+== TO USE:
+A gem is now available. 'gem install zenoss_client'
+
+<pre>
+<code>
+ require 'zenoss'
+ require 'date'
+
+ server = 'https://zenhost:port/zport/dmd'
+ user, pass = 'zuser', 'zpass'
+ @zen = Zenoss.connect server, user, pass
+ dev = (@zen.find_devices_by_name 'myservername').first
+
+ # Get RRD data for this device
+ rrdpts = dev.get_rrd_data_points
+ datapoints = dev.fetch_rrd_value rrdpts.first.name, (DateTime.now - 1)
+
+ # Get the uptime of the device
+ dev.sys_uptime
+
+ # Get a list of events for this system
+ dev.get_events
+</code>
+</pre>
+
+Have fun and let me know what needs to be fixed / added.
+
+== Testing
+You can invoke a series of minitest based spec test using the supplied
+tests and rake task. Simply run the following to kick off the tests
+@bundle exec rake test@
+
+You should see output similar to the following (The number of tests will
+of course grow over time):
+@3 tests, 6 assertions, 0 failures, 0 errors, 0 skips@
+
+If you get any failures, you should of course address them
+
+Since the test suite requires a working Zenoss installation to test against,
+some docker files are provided under test/docker. From a docker host, clone this
+repo, cd to the appropriate test/docker/ subdirectory, and run @sh start.sh@ to
+build and start the container. Once the container is running, you should be able
+to run the tests as described above.