Changeset f57d1e9 in trunk

Timestamp:

2016-05-05T01:37:23Z (9 years ago)

Author:

Brian Warner <warner@…>

Branches:

master

Children:

1e1e86f

Parents:

d1d9884 (diff), 93bb3e9 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch '2773-stats'

This changes "tahoe create-stats-gatherer" to take --hostname,
--location, and --port, according to (refs ticket:2773).

Files:

• docs/stats.rst (modified) (3 diffs)
• src/allmydata/scripts/stats_gatherer.py (modified) (2 diffs)
• src/allmydata/stats.py (modified) (2 diffs)
• src/allmydata/test/common.py (modified) (1 diff)
• src/allmydata/test/test_runner.py (modified) (7 diffs)
• topfiles/2773.docs (added)

docs/stats.rst ¶

@@ -280 +280 @@
 The stats-gatherer is created in the same fashion as regular tahoe client
 nodes and introducer nodes. Choose a base directory for the gatherer to live
-in (but do not create the directory). Then run:
+in (but do not create the directory). Choose the hostname that should be
+advertised in the gatherer's FURL. Then run:
 
 ::
 
-   tahoe create-stats-gatherer $BASEDIR
+   tahoe create-stats-gatherer --hostname=HOSTNAME $BASEDIR
 
 and start it with "tahoe start $BASEDIR". Once running, the gatherer will
@@ -296 +297 @@
 
     [client]
-    stats_gatherer.furl = pb://qbo4ktl667zmtiuou6lwbjryli2brv6t@192.168.0.8:49997/wxycb4kaexzskubjnauxeoptympyf45y
+    stats_gatherer.furl = pb://qbo4ktl667zmtiuou6lwbjryli2brv6t@HOSTNAME:PORTNUM/wxycb4kaexzskubjnauxeoptympyf45y
 
 or simply copy the stats_gatherer.furl file into the node's base directory
 (next to the tahoe.cfg file): it will be interpreted in the same way.
 
-The first time it is started, the gatherer will listen on a random unused TCP
-port, so it should not conflict with anything else that you have running on
-that host at that time. On subsequent runs, it will re-use the same port (to
-keep its FURL consistent). To explicitly control which port it uses, write
-the desired portnumber into a file named "portnum" (i.e. $BASEDIR/portnum),
-and the next time the gatherer is started, it will start listening on the
-given port. The portnum file is actually a "strports specification string",
-as described in :doc:`configuration`.
+When the gatherer is created, it will allocate a random unused TCP port, so
+it should not conflict with anything else that you have running on that host
+at that time. To explicitly control which port it uses, run the creation
+command with ``--location=`` and ``--port=`` instead of ``--hostname=``. If
+you use a hostname of ``example.org`` and a port number of ``1234``, then
+run::
+
+  tahoe create-stats-gatherer --location=tcp:example.org:1234 --port=tcp:1234
+
+``--location=`` is a Foolscap FURL hints string (so it can be a
+comma-separated list of connection hints), and ``--port=`` is a Twisted
+"server endpoint specification string", as described in :doc:`configuration`.
 
 Once running, the stats gatherer will create a standard JSON file in
@@ -323 +328 @@
 "storage_server.disk_avail' values from all servers to compute a
 total-disk-available number for the entire grid (however, the "disk watcher"
-daemon, in misc/operations_helpers/spacetime/, is better suited for this specific task).
+daemon, in misc/operations_helpers/spacetime/, is better suited for this
+specific task).
 
 Using Munin To Graph Stats Values
 =================================
 
-The misc/munin/ directory contains various plugins to graph stats for Tahoe
-nodes. They are intended for use with the Munin_ system-management tool, which
-typically polls target systems every 5 minutes and produces a web page with
-graphs of various things over multiple time scales (last hour, last month,
-last year).
+The misc/operations_helpers/munin/ directory contains various plugins to
+graph stats for Tahoe nodes. They are intended for use with the Munin_
+system-management tool, which typically polls target systems every 5 minutes
+and produces a web page with graphs of various things over multiple time
+scales (last hour, last month, last year).
 
 Most of the plugins are designed to pull stats from a single Tahoe node, and

src/allmydata/scripts/stats_gatherer.py ¶

@@ -1 @@
-
 import os, sys
-
+from twisted.python import usage
 from allmydata.scripts.common import NoDefaultBasedirOptions
 from allmydata.scripts.create_node import write_tac
 from allmydata.util.assertutil import precondition
 from allmydata.util.encodingutil import listdir_unicode, quote_output
+from allmydata.util import fileutil, iputil
 
 
 class CreateStatsGathererOptions(NoDefaultBasedirOptions):
     subcommand_name = "create-stats-gatherer"
+    optParameters = [
+        ("hostname", None, None, "Hostname of this machine, used to build location"),
+        ("location", None, None, "FURL connection hints, e.g. 'tcp:HOSTNAME:PORT'"),
+        ("port", None, None, "listening endpoint, e.g. 'tcp:PORT'"),
+        ]
+    def postOptions(self):
+        if self["hostname"] and (not self["location"]) and (not self["port"]):
+            pass
+        elif (not self["hostname"]) and self["location"] and self["port"]:
+            pass
+        else:
+            raise usage.UsageError("You must provide --hostname, or --location and --port.")
+
+    description = """
+    Create a "stats-gatherer" service, which is a standalone process that
+    collects and stores runtime statistics from many server nodes. This is a
+    tool for operations personnel to keep track of free disk space, server
+    load, and protocol activity, across a fleet of Tahoe storage servers.
+
+    The "stats-gatherer" listens on a TCP port and publishes a Foolscap FURL
+    by writing it into a file named "stats_gatherer.furl". You must copy this
+    FURL into the servers' tahoe.cfg, as the [client] stats_gatherer.furl=
+    entry. Those servers will then establish a connection to the
+    stats-gatherer and publish their statistics on a periodic basis. The
+    gatherer writes a summary JSON file out to disk after each update.
+
+    The stats-gatherer listens on a configurable port, and writes a
+    configurable hostname+port pair into the FURL that it publishes. There
+    are two configuration modes you can use.
+
+    * In the first, you provide --hostname=, and the service chooses its own
+      TCP port number. If the host is named "example.org" and you provide
+      --hostname=example.org, the node will pick a port number (e.g. 12345)
+      and use location="tcp:example.org:12345" and port="tcp:12345".
+
+    * In the second, you provide both --location= and --port=, and the
+      service will refrain from doing any allocation of its own. --location=
+      must be a Foolscap "FURL connection hint sequence", which is a
+      comma-separated list of "tcp:HOSTNAME:PORTNUM" strings. --port= must be
+      a Twisted server endpoint specification, which is generally
+      "tcp:PORTNUM". So, if your host is named "example.org" and you want to
+      use port 6789, you should provide --location=tcp:example.org:6789 and
+      --port=tcp:6789. You are responsible for making sure --location= and
+      --port= match each other.
+    """
 
 
@@ -27 +72 @@
         os.mkdir(basedir)
     write_tac(basedir, "stats-gatherer")
+    if config["hostname"]:
+        portnum = iputil.allocate_tcp_port()
+        location = "tcp:%s:%d" % (config["hostname"], portnum)
+        port = "tcp:%d" % portnum
+    else:
+        location = config["location"]
+        port = config["port"]
+    fileutil.write(os.path.join(basedir, "location"), location+"\n")
+    fileutil.write(os.path.join(basedir, "port"), port+"\n")
     return 0
 

src/allmydata/stats.py ¶

@@ -12 +12 @@
 from foolscap.api import eventually, DeadReferenceError, Referenceable, Tub
 
-from allmydata.util import log, fileutil
+from allmydata.util import log
 from allmydata.util.encodingutil import quote_local_unicode_path
 from allmydata.interfaces import RIStatsProvider, RIStatsGatherer, IStatsProducer
@@ -295 +295 @@
         self.stats_gatherer.setServiceParent(self)
 
-        portnumfile = os.path.join(self.basedir, "portnum")
         try:
-            portnum = open(portnumfile, "r").read()
+            with open(os.path.join(self.basedir, "location")) as f:
+                location = f.read().strip()
         except EnvironmentError:
-            portnum = None
-        self.listener = self.tub.listenOn(portnum or "tcp:0")
-        d = self.tub.setLocationAutomatically()
-        if portnum is None:
-            d.addCallback(self.save_portnum)
-        d.addCallback(self.tub_ready)
-        d.addErrback(log.err)
-
-    def save_portnum(self, junk):
-        portnum = self.listener.getPortnum()
-        portnumfile = os.path.join(self.basedir, 'portnum')
-        fileutil.write(portnumfile, '%d\n' % (portnum,))
-
-    def tub_ready(self, ignored):
+            raise ValueError("Unable to find 'location' in BASEDIR, please rebuild your stats-gatherer")
+        try:
+            with open(os.path.join(self.basedir, "port")) as f:
+                port = f.read().strip()
+        except EnvironmentError:
+            raise ValueError("Unable to find 'port' in BASEDIR, please rebuild your stats-gatherer")
+
+        self.tub.listenOn(port)
+        self.tub.setLocation(location)
         ff = os.path.join(self.basedir, self.furl_file)
         self.gatherer_furl = self.tub.registerReference(self.stats_gatherer,

src/allmydata/test/common.py ¶

@@ -495 +495 @@
         statsdir = self.getdir("stats_gatherer")
         fileutil.make_dirs(statsdir)
+        portnum = iputil.allocate_tcp_port()
+        location = "tcp:127.0.0.1:%d" % portnum
+        fileutil.write(os.path.join(statsdir, "location"), location)
+        port = "tcp:%d:interface=127.0.0.1" % portnum
+        fileutil.write(os.path.join(statsdir, "port"), port)
         self.stats_gatherer_svc = StatsGathererService(statsdir)
         self.stats_gatherer = self.stats_gatherer_svc.stats_gatherer

src/allmydata/test/test_runner.py ¶

@@ -185 +185 @@
         return rc, out.getvalue(), err.getvalue()
 
-    def do_create(self, kind):
+    def do_create(self, kind, *args):
         basedir = self.workdir("test_" + kind)
         command = "create-" + kind
@@ -192 +192 @@
 
         n1 = os.path.join(basedir, command + "-n1")
-        argv = ["--quiet", command, "--basedir", n1]
+        argv = ["--quiet", command, "--basedir", n1] + list(args)
         rc, out, err = self.run_tahoe(argv)
         self.failUnlessEqual(err, "")
@@ -227 +227 @@
         # test that the non --basedir form works too
         n2 = os.path.join(basedir, command + "-n2")
-        argv = ["--quiet", command, n2]
+        argv = ["--quiet", command] + list(args) + [n2]
         rc, out, err = self.run_tahoe(argv)
         self.failUnlessEqual(err, "")
@@ -237 +237 @@
         # test the --node-directory form
         n3 = os.path.join(basedir, command + "-n3")
-        argv = ["--quiet", "--node-directory", n3, command]
+        argv = ["--quiet", "--node-directory", n3, command] + list(args)
         rc, out, err = self.run_tahoe(argv)
         self.failUnlessEqual(err, "")
@@ -248 +248 @@
             # test that the output (without --quiet) includes the base directory
             n4 = os.path.join(basedir, command + "-n4")
-            argv = [command, n4]
+            argv = [command] + list(args) + [n4]
             rc, out, err = self.run_tahoe(argv)
             self.failUnlessEqual(err, "")
@@ -283 +283 @@
 
     def test_stats_gatherer(self):
-        self.do_create("stats-gatherer")
+        self.do_create("stats-gatherer", "--hostname=127.0.0.1")
 
     def test_subcommands(self):
@@ -292 +292 @@
                               run_by_human=False)
 
+    def test_stats_gatherer_good_args(self):
+        rc = runner.runner(["create-stats-gatherer", "--hostname=foo",
+                            self.mktemp()])
+        self.assertEqual(rc, 0)
+        rc = runner.runner(["create-stats-gatherer", "--location=tcp:foo:1234",
+                            "--port=tcp:1234", self.mktemp()])
+        self.assertEqual(rc, 0)
+
+    def test_stats_gatherer_bad_args(self):
+        # missing hostname/location/port
+        argv = "create-stats-gatherer D"
+        self.assertRaises(usage.UsageError, runner.runner, argv.split(),
+                          run_by_human=False)
+
+        # missing port
+        argv = "create-stats-gatherer --location=foo D"
+        self.assertRaises(usage.UsageError, runner.runner, argv.split(),
+                          run_by_human=False)
+
+        # missing location
+        argv = "create-stats-gatherer --port=foo D"
+        self.assertRaises(usage.UsageError, runner.runner, argv.split(),
+                          run_by_human=False)
+
+        # can't provide both
+        argv = "create-stats-gatherer --hostname=foo --port=foo D"
+        self.assertRaises(usage.UsageError, runner.runner, argv.split(),
+                          run_by_human=False)
+
+        # can't provide both
+        argv = "create-stats-gatherer --hostname=foo --location=foo D"
+        self.assertRaises(usage.UsageError, runner.runner, argv.split(),
+                          run_by_human=False)
+
+        # can't provide all three
+        argv = "create-stats-gatherer --hostname=foo --location=foo --port=foo D"
+        self.assertRaises(usage.UsageError, runner.runner, argv.split(),
+                          run_by_human=False)
 
 class RunNode(common_util.SignalMixin, unittest.TestCase, pollmixin.PollMixin,