diff --git a/CHANGELOG.md b/CHANGELOG.md index dd816290d6..8bc1a90a3f 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 5d95ab198e..fcaeb2b5b3 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 a62b53a396..622b2eb2de 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 0000000000..c9d5d6fa63 --- /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 0000000000..a931a5dd5e --- /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 0000000000..8b83feb87f --- /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 0000000000..ef260193c0 --- /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[]