From 6da71d03084d90f8f45320ff6355bd7687970307 Mon Sep 17 00:00:00 2001 From: Simran Date: Tue, 19 Jun 2018 18:47:30 +0200 Subject: [PATCH] Doc - Arangoinspect tool (#5537) --- .../Manual/Programs/Arangoinspect/Examples.md | 116 +++++ .../Manual/Programs/Arangoinspect/Options.md | 6 + .../Manual/Programs/Arangoinspect/README.md | 7 + Documentation/Books/Manual/Programs/README.md | 2 + Documentation/Books/Manual/SUMMARY.md | 3 + Documentation/Examples/arangoinspect.json | 423 ++++++++++++++++++ utils/generateExamples.sh | 2 +- 7 files changed, 558 insertions(+), 1 deletion(-) create mode 100644 Documentation/Books/Manual/Programs/Arangoinspect/Examples.md create mode 100644 Documentation/Books/Manual/Programs/Arangoinspect/Options.md create mode 100644 Documentation/Books/Manual/Programs/Arangoinspect/README.md create mode 100644 Documentation/Examples/arangoinspect.json diff --git a/Documentation/Books/Manual/Programs/Arangoinspect/Examples.md b/Documentation/Books/Manual/Programs/Arangoinspect/Examples.md new file mode 100644 index 0000000000..2d5d88465e --- /dev/null +++ b/Documentation/Books/Manual/Programs/Arangoinspect/Examples.md @@ -0,0 +1,116 @@ +Arangoinspect Examples +====================== + +If you are asked by ArangoDB support to provide an inspector output, run +the _arangoinspect_ binary to generate a file in the current working folder. + +The resulting JSON file is a collection of meta data acquired from all +involved instances. The data includes relevant operating system parameters, +ArangoDB process parameters, local database information etc. + +{% hint 'warning' %} +Please open the file locally and check if it contains anything that you are +not allowed/willing to share and obfuscate it before sharing (user names, +files paths etc.). +{% endhint %} + +Invoking Arangoinspect +---------------------- + +Point the tool to an ArangoDB endpoint. In case of a single server, there +is only one. You can connect to any node in case of a cluster (_DBServer_, +_Coordinator_, _Agent_). + + arangoinspect --server.endpoint tcp://127.0.0.1:8529 + +This will start the tool with a prompt for the JWT secret and try to connect +to the specified ArangoDB server. You have to type the secret as is used for +the `arangod` option `--server.jwt-secret`. For non-cluster deployments, +you may authenticate with a user name and password instead: + + arangoinspect --server.ask-jwt-secret false --server.username "root" --server.password "foobar" + +The password can be omitted and entered interactively. + +Example outputs +--------------- + +If _arangoinspect_ succeeds to authenticate, it starts to gather information +and writes the result to `arangodb-inspector.json`, then exits: + +``` +arangoinspect --server.endpoint tcp://127.0.0.1:8629 + +Please specify the JWT secret: +Connected to ArangoDB 'http+tcp://127.0.0.1:8629' version: 3.4.devel [server], database: '_system', username: 'root' + + _ ___ _ + / \ _ __ __ _ _ __ __ _ ___ |_ _|_ __ ___ _ __ ___ ___| |_ ___ _ __ + / _ \ | '__/ _` | '_ \ / _` |/ _ \ | || '_ \/ __| '_ \ / _ \/ __| __/ _ \| '__| + / ___ \| | | (_| | | | | (_| | (_) | | || | | \__ \ |_) | __/ (__| || (_) | | +/_/ \_\_| \__,_|_| |_|\__, |\___/ |___|_| |_|___/ .__/ \___|\___|\__\___/|_| + |___/ |_| + +2018-06-05T19:40:10Z [19858] INFO Connected to ArangoDB 'http+tcp://[::1]:4001', version 3.4.devel [server], database '_system', username: 'root' +2018-06-05T19:40:10Z [19858] INFO Connected to ArangoDB 'http+tcp://[::1]:4001', version 3.4.devel [server], database '_system', username: 'root' +INFO changing endpoint for AGNT-01e83a4b-8a51-4919-9f50-ff640accb9fa from http+tcp://[::1]:4001 to tcp://[::1]:4001 +INFO changing endpoint for PRMR-9f5b337e-c1de-4b7d-986a-d6ad2eb8f857 from tcp://127.0.0.1:8629 to tcp://[::1]:8629 +INFO Analysing agency dump ... +INFO Plan (version 22) +INFO Databases +INFO _system +INFO Collections +INFO _system +INFO _graphs +INFO _users +INFO _modules +INFO _iresearch_analyzers +INFO _routing +INFO _aqlfunctions +INFO _frontend +INFO _queues +INFO _jobs +INFO _apps +INFO _appbundles +INFO _statisticsRaw +INFO _statistics +INFO _statistics15 +INFO Server health +INFO DB Servers +INFO PRMR-9f5b337e-c1de-4b7d-986a-d6ad2eb8f857(DBServer0001) +INFO PRMR-90ff8c20-b0f3-49c5-a5dd-7b186bb7db33(DBServer0002) +INFO Coordinators +INFO CRDN-0dbf16ec-8a06-4203-9359-447d97757b4e(Coordinator0001) +INFO Supervision activity +INFO Jobs: undefined(To do: 0, Pending: 0, Finished: 0, Failed: 0) +INFO Summary +INFO 1 databases +INFO 14 collections +INFO 14 shards +INFO ... agency analysis finished. +INFO Collecting diagnostics from all servers ... +2018-06-05T19:40:10Z [19858] INFO Connected to ArangoDB 'http+tcp://[::1]:8629', version 3.4.devel [server], database '_system', username: 'root' +2018-06-05T19:40:11Z [19858] INFO Connected to ArangoDB 'http+tcp://[::1]:4001', version 3.4.devel [server], database '_system', username: 'root' +2018-06-05T19:40:11Z [19858] INFO Connected to ArangoDB 'http+tcp://[::1]:8630', version 3.4.devel [server], database '_system', username: 'root' +2018-06-05T19:40:11Z [19858] INFO Connected to ArangoDB 'http+tcp://[::1]:8530', version 3.4.devel [server], database '_system', username: 'root' +2018-06-05T19:40:11Z [19858] INFO Connected to ArangoDB 'http+tcp://[::1]:4001', version 3.4.devel [server], database '_system', username: 'root' +INFO ... dignostics collected. +INFO Report written to arango-inspector.json. +``` + +If _arangoinspect_ cannot connect or authentication/authorization fails, then a fatal error +will be raised and the tool shuts down: + +``` +Could not connect to endpoint 'http+tcp://127.0.0.1:8529', database: '_system', username: 'root' +Error message: '401: Unauthorized' + + _ ___ _ + / \ _ __ __ _ _ __ __ _ ___ |_ _|_ __ ___ _ __ ___ ___| |_ ___ _ __ + / _ \ | '__/ _` | '_ \ / _` |/ _ \ | || '_ \/ __| '_ \ / _ \/ __| __/ _ \| '__| + / ___ \| | | (_| | | | | (_| | (_) | | || | | \__ \ |_) | __/ (__| || (_) | | +/_/ \_\_| \__,_|_| |_|\__, |\___/ |___|_| |_|___/ .__/ \___|\___|\__\___/|_| + |___/ |_| + +FATAL cannot connect to server 'http+tcp://127.0.0.1:8529': 401: Unauthorized +``` diff --git a/Documentation/Books/Manual/Programs/Arangoinspect/Options.md b/Documentation/Books/Manual/Programs/Arangoinspect/Options.md new file mode 100644 index 0000000000..f38867e0f1 --- /dev/null +++ b/Documentation/Books/Manual/Programs/Arangoinspect/Options.md @@ -0,0 +1,6 @@ +Arangoinspect Options +===================== + +Usage: `arangoinspect []` + +@startDocuBlock program_options_arangoinspect diff --git a/Documentation/Books/Manual/Programs/Arangoinspect/README.md b/Documentation/Books/Manual/Programs/Arangoinspect/README.md new file mode 100644 index 0000000000..cff1ab5603 --- /dev/null +++ b/Documentation/Books/Manual/Programs/Arangoinspect/README.md @@ -0,0 +1,7 @@ +Arangoinspect +============= + +_Arangoinspect_ is a command-line client tool that collects information of any +ArangoDB server setup to facilitate troubleshooting for the ArangoDB support. + +The tool is available starting from ArangoDB v.3.3.11. \ No newline at end of file diff --git a/Documentation/Books/Manual/Programs/README.md b/Documentation/Books/Manual/Programs/README.md index cfeca54f75..a342f495cd 100644 --- a/Documentation/Books/Manual/Programs/README.md +++ b/Documentation/Books/Manual/Programs/README.md @@ -14,6 +14,7 @@ The full ArangoDB package ships with the following programs and tools: | `arangoexport` | [Bulk exporter](Arangoexport/README.md) for the ArangoDB server. It supports JSON, CSV and XML. | `arango-dfdb` | [Datafile debugger](Arango-dfdb/README.md) for ArangoDB (MMFiles storage engine only). | `arangobench` | [Benchmark and test tool](Arangobench/README.md). It can be used for performance and server function testing. +| `arangoinspect` | [Inspection tool](Arangoinspect/README.md) that gathers server setup information. | `arangovpack` | Utility to convert [VelocyPack](https://github.com/arangodb/velocypack) data to JSON. The client package comes with a subset of programs and tools: @@ -24,6 +25,7 @@ The client package comes with a subset of programs and tools: - arangodump - arangorestore - arangobench +- arangoinspect - arangovpack Additional tools which are available separately: diff --git a/Documentation/Books/Manual/SUMMARY.md b/Documentation/Books/Manual/SUMMARY.md index 3cf95c9af9..493b55522c 100644 --- a/Documentation/Books/Manual/SUMMARY.md +++ b/Documentation/Books/Manual/SUMMARY.md @@ -60,6 +60,9 @@ * [Arangobench](Programs/Arangobench/README.md) * [Examples](Programs/Arangobench/Examples.md) * [Options](Programs/Arangobench/Options.md) + * [Arangoinspect](Programs/Arangoinspect/README.md) + * [Examples](Programs/Arangoinspect/Examples.md) + * [Options](Programs/Arangoinspect/Options.md) * [Datafile Debugger](Programs/Arango-dfdb/README.md) * [Examples](Programs/Arango-dfdb/Examples.md) # https://@github.com/arangodb/foxx-cli.git;foxx-cli;docs/Manual;;/ diff --git a/Documentation/Examples/arangoinspect.json b/Documentation/Examples/arangoinspect.json new file mode 100644 index 0000000000..bfc000c31b --- /dev/null +++ b/Documentation/Examples/arangoinspect.json @@ -0,0 +1,423 @@ +{ + "check-configuration" : { + "default" : false, + "description" : "check the configuration and exit", + "hidden" : true, + "section" : "", + "type" : "boolean" + }, + "config" : { + "default" : "", + "description" : "the configuration file or 'none'", + "hidden" : true, + "section" : "", + "type" : "string" + }, + "configuration" : { + "default" : "", + "description" : "the configuration file or 'none'", + "hidden" : false, + "section" : "", + "type" : "string" + }, + "console.audit-file" : { + "default" : "", + "description" : "audit log file to save commands and results", + "hidden" : false, + "section" : "console", + "type" : "string" + }, + "console.auto-complete" : { + "default" : true, + "description" : "enable auto completion", + "hidden" : false, + "section" : "console", + "type" : "boolean" + }, + "console.colors" : { + "default" : true, + "description" : "enable color support", + "hidden" : false, + "section" : "console", + "type" : "boolean" + }, + "console.pager" : { + "default" : false, + "description" : "enable paging", + "hidden" : false, + "section" : "console", + "type" : "boolean" + }, + "console.pager-command" : { + "default" : "less -X -R -F -L", + "description" : "pager command", + "hidden" : true, + "section" : "console", + "type" : "string" + }, + "console.pretty-print" : { + "default" : true, + "description" : "enable pretty printing", + "hidden" : false, + "section" : "console", + "type" : "boolean" + }, + "console.prompt" : { + "default" : "%E@%d> ", + "description" : "prompt used in REPL. prompt components are: '%t': current time as timestamp, '%p': duration of last command in seconds, '%d': name of current database, '%e': current endpoint, '%E': current endpoint without protocol, '%u': current user", + "hidden" : false, + "section" : "console", + "type" : "string" + }, + "default-language" : { + "default" : "", + "description" : "ISO-639 language code", + "hidden" : true, + "section" : "", + "type" : "string" + }, + "define" : { + "default" : [ + ], + "description" : "define key=value for a @key@ entry in config file", + "hidden" : true, + "section" : "", + "type" : "string..." + }, + "dump-dependencies" : { + "default" : false, + "description" : "dump dependency graph", + "hidden" : true, + "section" : "", + "type" : "boolean" + }, + "dump-options" : { + "default" : true, + "description" : "dump configuration options in JSON format", + "hidden" : true, + "section" : "", + "type" : "boolean" + }, + "javascript.check-syntax" : { + "default" : [ + ], + "description" : "syntax check code Javascript code from file", + "hidden" : false, + "section" : "javascript", + "type" : "string..." + }, + "javascript.client-module" : { + "default" : "inspector.js", + "description" : "client module to use at startup", + "hidden" : true, + "section" : "javascript", + "type" : "string" + }, + "javascript.current-module-directory" : { + "default" : true, + "description" : "add current directory to module path", + "hidden" : false, + "section" : "javascript", + "type" : "boolean" + }, + "javascript.execute" : { + "default" : [ + ], + "description" : "execute Javascript code from file", + "hidden" : false, + "section" : "javascript", + "type" : "string..." + }, + "javascript.execute-string" : { + "default" : [ + ], + "description" : "execute Javascript code from string", + "hidden" : false, + "section" : "javascript", + "type" : "string..." + }, + "javascript.gc-interval" : { + "default" : 50, + "description" : "request-based garbage collection interval (each n.th commands)", + "hidden" : false, + "section" : "javascript", + "type" : "uint64" + }, + "javascript.module-directory" : { + "default" : [ + ], + "description" : "additional paths containing JavaScript modules", + "hidden" : true, + "section" : "javascript", + "type" : "string..." + }, + "javascript.startup-directory" : { + "default" : "./js", + "description" : "startup paths containing the Javascript files", + "hidden" : true, + "section" : "javascript", + "type" : "string" + }, + "javascript.unit-tests" : { + "default" : [ + ], + "description" : "do not start as shell, run unit tests instead", + "hidden" : false, + "section" : "javascript", + "type" : "string..." + }, + "javascript.v8-max-heap" : { + "default" : 3072, + "description" : "maximal heap size (in MB)", + "hidden" : false, + "section" : "javascript", + "type" : "uint64" + }, + "javascript.v8-options" : { + "default" : [ + ], + "description" : "options to pass to v8", + "hidden" : true, + "section" : "javascript", + "type" : "string..." + }, + "jslint" : { + "default" : [ + ], + "description" : "do not start as shell, run jslint instead", + "hidden" : false, + "section" : "", + "type" : "string..." + }, + "log" : { + "default" : [ + "info" + ], + "description" : "the global or topic-specific log level", + "hidden" : true, + "section" : "", + "type" : "string..." + }, + "log.color" : { + "default" : true, + "description" : "use colors for TTY logging", + "hidden" : false, + "section" : "log", + "type" : "boolean" + }, + "log.escape" : { + "default" : true, + "description" : "escape characters when logging", + "hidden" : false, + "section" : "log", + "type" : "boolean" + }, + "log.file" : { + "default" : "-", + "description" : "shortcut for '--log.output file://'", + "hidden" : true, + "section" : "log", + "type" : "string" + }, + "log.force-direct" : { + "default" : false, + "description" : "do not start a seperate thread for logging", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.foreground-tty" : { + "default" : false, + "description" : "also log to tty if backgrounded", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.keep-logrotate" : { + "default" : false, + "description" : "keep the old log file after receiving a sighup", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.level" : { + "default" : [ + "info" + ], + "description" : "the global or topic-specific log level", + "hidden" : false, + "section" : "log", + "type" : "string..." + }, + "log.line-number" : { + "default" : false, + "description" : "append line number and file name", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.output" : { + "default" : [ + ], + "description" : "log destination(s)", + "hidden" : false, + "section" : "log", + "type" : "string..." + }, + "log.performance" : { + "default" : false, + "description" : "shortcut for '--log.level performance=trace'", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.prefix" : { + "default" : "", + "description" : "prefix log message with this string", + "hidden" : true, + "section" : "log", + "type" : "string" + }, + "log.role" : { + "default" : false, + "description" : "log server role", + "hidden" : false, + "section" : "log", + "type" : "boolean" + }, + "log.shorten-filenames" : { + "default" : true, + "description" : "shorten filenames in log output (use with --log.line-number)", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.thread" : { + "default" : false, + "description" : "show thread identifier in log message", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.thread-name" : { + "default" : false, + "description" : "show thread name in log message", + "hidden" : true, + "section" : "log", + "type" : "boolean" + }, + "log.use-local-time" : { + "default" : false, + "description" : "use local timezone instead of UTC", + "hidden" : false, + "section" : "log", + "type" : "boolean" + }, + "log.use-microtime" : { + "default" : false, + "description" : "use microtime instead", + "hidden" : false, + "section" : "log", + "type" : "boolean" + }, + "quiet" : { + "default" : false, + "description" : "silent startup", + "hidden" : false, + "section" : "", + "type" : "boolean" + }, + "random.generator" : { + "default" : 1, + "description" : "random number generator to use (1 = MERSENNE, 2 = RANDOM, 3 = URANDOM, 4 = COMBINED (not for Windows), 5 = WinCrypt (Windows only)", + "hidden" : true, + "section" : "random", + "type" : "uint32", + "values" : "Possible values: 1, 2, 3, 4" + }, + "server.ask-jwt-secret" : { + "default" : true, + "description" : "if this option is specified, the user will be prompted for a JWT secret. This option is not compatible with --server.username or --server.password. If specified, it will be used for all connections - even when a new connection to another server is created", + "hidden" : true, + "section" : "server", + "type" : "boolean" + }, + "server.authentication" : { + "default" : false, + "description" : "require authentication credentials when connecting (does not affect the server-side authentication settings)", + "hidden" : false, + "section" : "server", + "type" : "boolean" + }, + "server.connection-timeout" : { + "default" : 5, + "description" : "connection timeout in seconds", + "hidden" : false, + "section" : "server", + "type" : "double" + }, + "server.database" : { + "default" : "_system", + "description" : "database name to use when connecting", + "hidden" : false, + "section" : "server", + "type" : "string" + }, + "server.endpoint" : { + "default" : "http+tcp://127.0.0.1:8529", + "description" : "endpoint to connect to, use 'none' to start without a server", + "hidden" : false, + "section" : "server", + "type" : "string" + }, + "server.max-packet-size" : { + "default" : 134217728, + "description" : "maximum packet size (in bytes) for client/server communication", + "hidden" : true, + "section" : "server", + "type" : "uint64" + }, + "server.password" : { + "default" : "", + "description" : "password to use when connecting. If not specified and authentication is required, the user will be prompted for a password", + "hidden" : false, + "section" : "server", + "type" : "string" + }, + "server.request-timeout" : { + "default" : 1200, + "description" : "request timeout in seconds", + "hidden" : false, + "section" : "server", + "type" : "double" + }, + "server.username" : { + "default" : "root", + "description" : "username to use when connecting", + "hidden" : false, + "section" : "server", + "type" : "string" + }, + "ssl.protocol" : { + "default" : 5, + "description" : "ssl protocol (1 = SSLv2, 2 = SSLv2 or SSLv3 (negotiated), 3 = SSLv3, 4 = TLSv1, 5 = TLSV1.2)", + "hidden" : false, + "section" : "ssl", + "type" : "uint64", + "values" : "Possible values: 1, 2, 3, 4, 5" + }, + "temp.path" : { + "default" : "", + "description" : "path for temporary files", + "hidden" : false, + "section" : "temp", + "type" : "string" + }, + "version" : { + "default" : false, + "description" : "reports the version and exits", + "hidden" : false, + "section" : "", + "type" : "boolean" + } +} diff --git a/utils/generateExamples.sh b/utils/generateExamples.sh index 77c2f613cc..82da37be25 100755 --- a/utils/generateExamples.sh +++ b/utils/generateExamples.sh @@ -49,7 +49,7 @@ fi [ "$(uname -s)" = "Darwin" -a -x "${ARANGOSH}" ] && ARANGOSH="$(cd -P -- "$(dirname -- "${ARANGOSH}")" && pwd -P)/$(basename -- "${ARANGOSH}")" -ALLPROGRAMS="arangobench arangod arangodump arangoexport arangoimport arangorestore arangosh" +ALLPROGRAMS="arangobench arangod arangodump arangoexport arangoimport arangoinspect arangorestore arangosh" for HELPPROGRAM in ${ALLPROGRAMS}; do "${BIN_PATH}/${HELPPROGRAM}${EXT}" --dump-options > "Documentation/Examples/${HELPPROGRAM}.json"