Merge ~stub/charm-telegraf:tweaks into ~telegraf-charmers/charm-telegraf:master

[Stuart Bishop]

Polish the README and tweak the makefile a bit.

Dependent on prometheus-by-default, as that is what this version of the docs says. Its a minor change if that isn't going to land.

[Guillermo Gonzalez (verterok)]

+1

please see inline comment.

review: Approve

[Stuart Bishop (stub)]

The merge was fine but running tests failed.

review: Needs Fixing

[Stuart Bishop (stub)]

Previously approved

review: Approve

[Guillermo Gonzalez (verterok)]

review: Approve

diff --git a/Makefile b/Makefile
index 1ee0243..8fd218f 100644
--- a/Makefile
+++ b/Makefile
@@ -21,11 +21,13 @@ venv:
 test: venv 
 	venv/bin/py.test unit_tests/ -v
 
-build: clean
-	@if test -z ${JUJU_REPOSITORY} || test -z ${INTERFACE_PATH} || test -z ${LAYER_PATH}; then echo "JUJU_REPOSITORY, LAYER_PATH and INTERFACE_PATH needs to be defined"; exit 1; fi
+build: realclean
 	@charm build
 
 clean: 
 	@find -name __pycache__ | xargs rm -rf
 	@find -name *.pyc | xargs rm -rf
 	@rm -Rf venv
+
+realclean:
+	git clean -fxd
diff --git a/README.md b/README.md
index 619041c..567b3e4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # Overview
 
-This is a subordinate charm to deploy telegraf metrics agent to collect metrics from all services deployed in the environment.
+This is a subordinate charm to deploy the telegraf metrics agent to collect
+metrics from related services. The metrics may be scraped by or pushed
+to supported systems such as Prometheus, Graphite or InfluxDB.
 
 For details about telegraf see: https://github.com/influxdata/telegraf 
 
@@ -20,61 +22,106 @@ Add the relations:
 
 # Configuration
 
-By default there is no output plugin configured, but a basic set of input plugins are setup, which can be overriden with inputs_config charm config.
+## Prometheus Output
 
-To configure any of the (default or via relation) plugins, the extra_options charm config can be used. It's string in yaml format, for example: 
+By default, Prometheus output is presented available for scraping.
 
-    inputs:
-        cpu:
-            percpu: false
-            fielddrop: ["time_*"]
-        disk:
-            mount_points: ["/"]
-            ignore_fs: ["tmpfs", "devtmpfs"]
-        elasticsearch:
-            local: false
-            cluster_health: true
-        postgresql:
-            databases: ["foo", "bar"]
-            tagpass: 
-                db: ["template", "postgres"]
-    outputs:
-        influxdb:
-            precision: ms
+## InfluxDB Output
 
-This extra options will only be applied to plugins defined in templates/base_inputs.conf and any other plugins configured via relations.
+When related to an InfluxDB service, metrics will be pushed to a database
+named ``telegraf``.
 
-## Apache input
+## Apache Input
 
-For the apache input plugin, the charm provides the apache relation which uses apache-website interface. Current apache charm disables mod_status  and in order to telegraf apache input to work 'status' should be removed from the list of disable_modules in the apache charm config.
+For the apache input plugin, the charm provides the apache relation which
+uses ``apache-website`` interface. Current apache charm disables
+``mod_status`` and in order to telegraf apache input to work ``status``
+should be removed from the list of ``disable_modules`` in the apache charm
+config.
 
 ## Postgresql input 
 
-Due to a [bug/regression](https://bugs.launchpad.net/postgresql-charm/+bug/1560262) in the new postgresql-charm in order to get actual postgresql metrics, two relations need to be established between telegraf and the postgresql service, first a plain juju-info relation to get telegraf setup and then a regular postgresql/db one. e.g:
-
-juju add-relation telegraf:juju-info postgresql:juju-info 
-juju add-relation telegraf:postgresql postgresql:db
-
-## Output 
-
-The only output plugin supported via relation is influxdb, any other output plugin needs to be configured manually (via juju set)
-
-To use a different metrics storage, e.g: graphite. the plugin configuration needs to be set as a base64 string in outputs_config configuration.
-
-For exmaple, save the following config to a file: 
-
-    [[outputs.graphite]]
-      servers = ["10.0.3.231:2003"]
-      prefix = "juju_local.devel.telegraf"
-      timeout = 10
-
-And then 
-
-    juju set telegraf outputs_config="$(cat graphite-output.conf | base64)"
+Due to [relation scope issues](https://bugs.launchpad.net/postgresql-charm/+bug/1560262), two relations need to be established between telegraf and the
+postgresql service. first a plain ``juju-info`` relation to get standard
+system metrics and a ``postgresql`` relation for PostgreSQL database metrics.
+eg.:
+
+    ```
+    juju add-relation postgresql:juju-info telegraf
+    juju add-relation postgresql:db telegraf
+    ```
+
+## Advanced
+
+### Input
+
+A basic set of input plugins are setup by default, which can be overriden
+with the ``inputs_config`` configuration option. Both of these accept raw
+telegraf configuration.
+
+To configure any of the (default or via relation) plugins, the
+``extra_options`` charm config can be used. It's yaml, that needs to
+be encoded as a string in the config. For example:
+
+    ```yaml
+    telegraf:
+    # The trailing | means the following indented section is all one string.
+    extra_options: |
+        inputs:
+            cpu:
+                percpu: false
+                fielddrop: ["time_*"]
+            disk:
+                mount_points: ["/"]
+                ignore_fs: ["tmpfs", "devtmpfs"]
+            elasticsearch:
+                local: false
+                cluster_health: true
+            postgresql:
+                databases: ["foo", "bar"]
+                tagpass: 
+                    db: ["template", "postgres"]
+        outputs:
+            influxdb:
+                precision: ms
+    ```
+
+This extra options will only be applied to pligins configured via
+relations and the following list (defined in ``templates/base_inputs.conf``):
+    - inputs.cpu
+    - inputs.disk
+    - inputs.diskio
+    - inputs.mem
+    - inputs.net
+    - inputs.netstat
+    - inputs.swap
+    - inputs.system
+
+
+### Output 
+
+The only output plugin supported via relation is influxdb, any other output
+plugin needs to be configured manually (via juju set).
+
+To use a different metrics storage such as Graphite, the raw telegraf
+plugin configuration needs to be set as a string in ``outputs_config``
+configuration. For example:
+
+    ```yaml
+    telegraf:
+      # The trailing | indicates a multiline string in yaml.
+      outputs_config: |
+        [[outputs.graphite]]
+        servers = ["10.0.3.231:2003"]
+        prefix = "juju_local.devel.telegraf"
+        timeout = 10
+    ```
 
 This will make telegraf agents to send the metrics to the graphite instance.
 
 # Contact Information
 
+- Prometheus Charming Project: https://launchpad.net/prometheus-charms
+- Charm bugs: https://bugs.launchpad.net/telegraf-charm
 - Upstream https://github.com/influxdata/telegraf
 - Upstream bug tracker https://github.com/influxdata/telegraf/issues