From edd32908fe2c747511cf76b967b1628bf8f0a213 Mon Sep 17 00:00:00 2001 From: "Jonathan A. Sternberg" Date: Thu, 15 Sep 2016 08:35:03 -0500 Subject: [PATCH] More man pages for the other tools we package Updating the package to compress the man pages fully and removes the filename and timestamp from being stored in the man page. Lintian complains that the packages aren't compressed using the best compression method. https://lintian.debian.org/tags/manpage-not-compressed.html --- CHANGELOG.md | 1 + build.py | 2 +- man/Makefile | 3 ++ man/README.md | 38 ++++++++++++++++++++++ man/influx_inspect.txt | 74 ++++++++++++++++++++++++++++++++++++++++++ man/influx_stress.txt | 52 +++++++++++++++++++++++++++++ man/influx_tsm.txt | 58 +++++++++++++++++++++++++++++++++ 7 files changed, 227 insertions(+), 1 deletion(-) create mode 100644 man/README.md create mode 100644 man/influx_inspect.txt create mode 100644 man/influx_stress.txt create mode 100644 man/influx_tsm.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index dd816290d67..8bc1a90a3f0 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/build.py b/build.py index 5d95ab198ed..fcaeb2b5b32 100755 --- a/build.py +++ b/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. diff --git a/man/Makefile b/man/Makefile index a62b53a3966..622b2eb2def 100644 --- a/man/Makefile +++ b/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)) diff --git a/man/README.md b/man/README.md new file mode 100644 index 00000000000..c9d5d6fa637 --- /dev/null +++ b/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 +``` diff --git a/man/influx_inspect.txt b/man/influx_inspect.txt new file mode 100644 index 00000000000..a931a5dd5e8 --- /dev/null +++ b/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 :: + Only display index and block data that match this key substring. + +-index:: + Dump raw index data. + +EXPORT OPTIONS +-------------- +-compress:: + Compress the output. + +-db :: + The database to export. Optional. + +-rp :: + The retention policy to export. Optional. Requires the '-db ' option to be specified. + +-dir :: + Root storage path. Defaults to '~/.influxdb'. + +-start-time :: + The start time of the export. The timestamp is in RFC3339 format. Optional. + +-end-time :: + The end time of the export. The timestamp is in RFC3339 format. Optional. + +-out :: + Destination file to write exported data to. Defaults to '~/.influxdb/export'. + +REPORT OPTIONS +-------------- +-detailed:: + Report detailed cardinality estimates. + +-pattern :: + Include only files matching a pattern. + +include:footer.txt[] diff --git a/man/influx_stress.txt b/man/influx_stress.txt new file mode 100644 index 00000000000..8b83feb87f3 --- /dev/null +++ b/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 :: + 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 :: + 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 :: + 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 :: + The stress configuration file. + +-cpuprofile :: + 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 :: + The target database within the test system for write and query load. + +-tags :: + A comma separated list of tags. + +-v2:: + Use version 2 of the stress tool. The default is to use version 1. + +include::footer.txt[] diff --git a/man/influx_tsm.txt b/man/influx_tsm.txt new file mode 100644 index 00000000000..ef260193c0b --- /dev/null +++ b/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] + +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 :: + The location to backup the current databases. Must not be within the data + directory. + +-dbs :: + Comma-delimited list of databases to convert. The default is to convert all + databases. + +-debug :: + If set, http debugging endpoints will be enabled on the given address. + +-interval :: + 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 :: + Write a CPU profile to the path. + +-sz :: + Maximum size of individual TSM files. Defaults to 2147483648. + +-y:: + Don't ask, just convert. + +include::footer.txt[]