Merge pull request #7268 from influxdata/js-more-man-pages

More man pages for the other tools we package

CHANGELOG.md

@@ -11,6 +11,7 @@
 - [#6992](https://github.com/influxdata/influxdb/issues/6992): Support tools for running async queries.
 - [#7136](https://github.com/influxdata/influxdb/pull/7136): Update jwt-go dependency to version 3.
 - [#6962](https://github.com/influxdata/influxdb/issues/6962): Support ON and use default database for SHOW commands.
+- [#7268](https://github.com/influxdata/influxdb/pull/7268): More man pages for the other tools we package and compress man pages fully.
 
 ### Bugfixes
 

build.py

@@ -154,7 +154,7 @@ def package_man_files(build_root):
     run("make -C man/ clean install DESTDIR={}/usr".format(build_root))
     for path, dir, files in os.walk(os.path.join(build_root, MAN_DIR[1:])):
         for f in files:
-            run("gzip {}".format(os.path.join(path, f)))
+            run("gzip -9n {}".format(os.path.join(path, f)))
 
 def run_generate():
     """Run 'go generate' to rebuild any static assets.

man/Makefile

@@ -10,6 +10,9 @@ MAN1_TXT += influxd-restore.txt
 MAN1_TXT += influxd-run.txt
 MAN1_TXT += influxd-version.txt
 MAN1_TXT += influx.txt
+MAN1_TXT += influx_inspect.txt
+MAN1_TXT += influx_stress.txt
+MAN1_TXT += influx_tsm.txt
 
 MAN_TXT = $(MAN1_TXT)
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))

man/README.md

@@ -0,0 +1,38 @@
+# Building the Man Pages
+
+The man pages are created with `asciidoc`, `docbook`, and `xmlto`.
+
+## Debian/Ubuntu
+
+This is the easiest since Debian and Ubuntu automatically install the
+dependencies correctly.
+
+```bash
+$ sudo apt-get install -y build-essential asciidoc xmlto
+```
+
+You should then be able to run `make` and the man pages will be
+produced.
+
+## Mac OS X
+
+Mac OS X also has the tools necessary to build the docs, but one of the
+dependencies gets installed incorrectly and you need an environment
+variable to run it correctly.
+
+Use Homebrew to install the dependencies. There might be other methods
+to get the dependencies, but that's left up to the reader if they want
+to use a different package manager.
+
+If you have Homebrew installed, you should already have the Xcode tools
+and that should include `make`.
+
+```bash
+$ brew install asciidoc xmlto
+```
+
+Then set the following environment variable everytime you run `make`.
+
+```bash
+export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
+```

man/influx_inspect.txt

@@ -0,0 +1,74 @@
+influx_inspect(1)
+=================
+
+NAME
+----
+influx_inspect - Displays detailed information about InfluxDB data files
+
+SYNPOSIS
+--------
+[verse]
+'influx_inspect dumptsm' [options]
+'influx_inspect export' [options]
+'influx_inspect report' [options]
+
+DESCRIPTION
+-----------
+Displays detailed information about InfluxDB data files through one of the
+following commands.
+
+*dumptsm*::
+  Dumps low-level details about tsm1 files.
+
+*export*::
+  Exports TSM files into InfluxDB line protocol format.
+
+*report*::
+  Displays shard level report.
+
+DUMPTSM OPTIONS
+---------------
+-all::
+  Dump all data. Caution: This may print a lot of information.
+
+-blocks::
+  Dump raw block data.
+
+-filter-key <string>::
+  Only display index and block data that match this key substring.
+
+-index::
+  Dump raw index data.
+
+EXPORT OPTIONS
+--------------
+-compress::
+  Compress the output.
+
+-db <name>::
+  The database to export. Optional.
+
+-rp <name>::
+  The retention policy to export. Optional. Requires the '-db <name>' option to be specified.
+
+-dir <path>::
+  Root storage path. Defaults to '~/.influxdb'.
+
+-start-time <timestamp>::
+  The start time of the export. The timestamp is in RFC3339 format. Optional.
+
+-end-time <timestamp>::
+  The end time of the export. The timestamp is in RFC3339 format. Optional.
+
+-out <path>::
+  Destination file to write exported data to. Defaults to '~/.influxdb/export'.
+
+REPORT OPTIONS
+--------------
+-detailed::
+  Report detailed cardinality estimates.
+
+-pattern <string>::
+  Include only files matching a pattern.
+
+include:footer.txt[]

man/influx_stress.txt

@@ -0,0 +1,52 @@
+influx_stress(1)
+================
+
+NAME
+----
+influx_stress - Runs a stress test against one or multiple InfluxDB servers
+
+SYNOPSIS
+--------
+[verse]
+'influx_stress' [options]
+
+DESCRIPTION
+-----------
+Runs write and query stress tests against one or multiple InfluxDB servers to
+create reproducible performance benchmarks against InfluxDB.
+
+OPTIONS
+-------
+-addr <addr>::
+  IP address and port of the database where response times will persist. This
+  is not for specifying which database to test against. That option is located
+  inside of the configuration file. The default is 'http://localhost:8086'.
+
+-database <name>::
+  The database where response times will persist. This is not for specifying
+  which database to test against. See '-db' or the configuration file for that
+  option. The default is 'stress'.
+
+-retention-policy <name>::
+  The retention policy where response times will persist. This is not for
+  specifying which retention policy to test against. See the configuration file
+  for that option. The default is an empty string which will use the default
+  retention policy.
+
+-config <path>::
+  The stress configuration file.
+
+-cpuprofile <path>::
+  Write the cpu profile to the path. No cpu profile is written unless this is
+  used. This profiles 'influx_stress', not the InfluxDB server.
+
+-db <name>::
+  The target database within the test system for write and query load.
+
+-tags <values>::
+  A comma separated list of tags.
+
+-v2::
+  Use version 2 of the stress tool. The default is to use version 1.
+
+include::footer.txt[]

man/influx_tsm.txt

@@ -0,0 +1,58 @@
+influx_tsm(1)
+=============
+
+NAME
+----
+influx_tsm - Convert a database from b1 or bz1 format to tsm1 format
+
+SYNPOSIS
+--------
+[verse]
+'influx_tsm' [options] <data-path>
+
+DESCRIPTION
+-----------
+This tool can be used to convert a database from the deprecated b1 or bz1
+formats to tsm1 format. The b1 and bz1 formats were deprecated in 0.10 and
+removed in 0.12.
+
+This tool will backup the directories before conversion (if not disabled). The
+backed-up files must be removed manually, generally after starting up the node
+again to make sure all of the data has been converted correctly.
+
+To restore a backup after attempting to convert to tsm1, you shut down the
+node, remove the converted directory, and copy the backed-up directory to the
+original location.
+
+OPTIONS
+-------
+-backup <path>::
+  The location to backup the current databases. Must not be within the data
+  directory.
+
+-dbs <names>::
+  Comma-delimited list of databases to convert. The default is to convert all
+  databases.
+
+-debug <addr>::
+  If set, http debugging endpoints will be enabled on the given address.
+
+-interval <duration>::
+  How often status updates are printed. Default is '5s'.
+
+-nobackup::
+  Disable database backups. Not recommended.
+
+-parallel::
+  Perform parallel conversions (up to GOMAXPROCS shards at once).
+
+-profile <path>::
+  Write a CPU profile to the path.
+
+-sz <size>::
+  Maximum size of individual TSM files. Defaults to 2147483648.
+
+-y::
+  Don't ask, just convert.
+
+include::footer.txt[]