Add documentation and acceptance tests (echocat#387)

README.md

@@ -201,6 +201,30 @@ ones set for the principal instance.
 
 So in this case you would have 3 cache instances, the first one is `cache` (you can refer to it as `cache:a` too), `cache:b` and `cache:c`. cache:a will listen on ports 2003, 2004 and 7002 for line, pickle and query respectively. But, cache:b will do it on ports 2103, 2104, and 7102, and cache:c on 2203, 2204 and 7202. All other parameters from cache:a will be inherited by cache:b and c.
 
+### Install Graphite 1.1 and enable tag-support
+
+Taged metrics are available in Graphite/Carbon 1.1.1 and later. To use tags Carbon has to add tags to a TagDB (see https://graphite.readthedocs.io/en/latest/tags.html) for details. To enable this feature in Carbon set the parameter `gr_tags_enable` to `true`. This will configure Carbon to pass tags to Graphite-web listening on `127.0.0.1` and port `gr_web_server_port`. Redis and HTTP(S) Tag DBs are not yet supported.
+
+To use tags at least version 1.1.1 of Graphite-Web/Carbopn/Whisper as well as compatible versions of Django, Django Tagging and Twisted have to be installed. 
+
+```
+class { 'graphite': 
+    gr_tags_enable            => true,
+    #
+    # Needed to install / upgrade to Graphite 1.1
+    #
+    gr_graphite_ver           => '1.1.7',
+    gr_carbon_ver             => '1.1.7',
+    gr_whisper_ver            => '1.1.7',
+    gr_django_ver             => '1.11',
+    gr_django_tagging_ver     => '0.4.6',
+    gr_twisted_ver            => '20.3.0',
+    gr_django_init_command    => 'PYTHONPATH=/opt/graphite/webapp /usr/local/bin/django-admin.py migrate --setting=graphite.settings --fake-initial',
+    gr_django_init_provider   => 'shell',
+}
+```
+
+
 ### Installing with something other than pip and specifying package names and versions
 If you need to install via something other than pip, an internal apt repo with fpm converted packages for instance, you can set `gr_pip_install` to false.
 If you're doing this you'll most likely have to override the default package names and versions as well.

manifests/init.pp

@@ -539,6 +539,9 @@
 #   Default: false
 # [*gr_enable_logrotation*]
 #   Boolean. Sets up a cronjob to rotate carbon and webapp logs.
+# [*gr_tags_enable*]
+#   Boolean. Enable tag support in carbon. Tags will be sent to the graphite-web service
+#   on 'http://127.0.0.1:${gr_web_server_port}'
 # [*gr_apache_port*]
 #   DEPRECATED. Use `gr_web_server_port` now. Trying to set this variable will
 #   cause puppet to fail.

spec/acceptance/x_tag_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper_acceptance'
+
+hosts_as('graphite_1').each do |graphite_host|
+
+  describe "graphite 1.1 install/update on host #{graphite_host}" do
+    let(:graphite_version){ '1.1.7' }
+    let(:django_version){ '1.11' }
+    let(:django_tagging_version){ '0.4.6' }
+    let(:twisted_version){ '20.3.0' }
+
+    it 'has to delete the existing django db to work around failures migrating the database from 0.9' do
+      on(graphite_host, 'rm -f /opt/graphite/storage/graphite.db || exit 0')
+    end
+
+    context 'install or upgrade Graphite 1.1 with tag support' do
+      # Using puppet_apply as a helper
+      it 'should work with no errors' do
+        pp = <<-EOS
+          class { 'graphite': 
+                secret_key                => '123456789', 
+                gr_base_dir               => '/opt/graphite',
+                gr_django_init_command    => 'PYTHONPATH=/opt/graphite/webapp /usr/local/bin/django-admin.py migrate --setting=graphite.settings --fake-initial && chown www-data /opt/graphite/storage/log/*.log',
+                gr_django_init_provider   => 'shell',
+                gr_carbon_ver             => '#{graphite_version}',
+                gr_graphite_ver           => '#{graphite_version}',
+                gr_whisper_ver            => '#{graphite_version}',
+                gr_django_ver             => '#{django_version}',
+                gr_django_tagging_ver     => '#{django_tagging_version}',
+                gr_twisted_ver            => '#{twisted_version}',
+                gr_tags_enable            => true,
+          }
+        EOS
+
+        apply_manifest_on(graphite_host, pp, :catch_failures => true)
+      end
+
+      it 'should send tagged data' do
+        result = on(graphite_host, 'echo "data;arg=key 42 `date +%s`" | nc -N 127.0.0.1 2003')
+        expect(result.exit_code).to eq 0
+      end
+
+      it 'graphite should have received the data' do
+        result = on(graphite_host, "sleep 10 && curl -s 'http://127.0.0.1/render?target=seriesByTag(\"arg=key\")&format=raw&from=-5min' | grep 'arg=key,.*42.0'")
+        expect(result.exit_code).to eq 0
+      end
+    end
+  end
+end
+