From 8451f50b57a3ecd0028e387831a8c32ed3fd5daf Mon Sep 17 00:00:00 2001 From: Robbie Gemmell Date: Thu, 16 Sep 2021 18:53:46 +0100 Subject: [PATCH] ARTEMIS-3486: update docs around data tools commands, note use of broker instance and refresh shown output --- .../apache/activemq/artemis/cli/Artemis.java | 4 +- docs/user-manual/en/data-tools.md | 342 +++++++++++------- 2 files changed, 218 insertions(+), 128 deletions(-) diff --git a/artemis-cli/src/main/java/org/apache/activemq/artemis/cli/Artemis.java b/artemis-cli/src/main/java/org/apache/activemq/artemis/cli/Artemis.java index 1130750d83..398bbd3e4b 100644 --- a/artemis-cli/src/main/java/org/apache/activemq/artemis/cli/Artemis.java +++ b/artemis-cli/src/main/java/org/apache/activemq/artemis/cli/Artemis.java @@ -177,13 +177,13 @@ public class Artemis { .withDescription("activation tools group (sync) (example ./artemis activation list)") .withDefaultCommand(ActivationSequenceList.class) .withCommands(ActivationSequenceList.class, ActivationSequenceSet.class); - builder.withGroup("data").withDescription("data tools group (print|imp|exp|encode|decode|compact) (example ./artemis data print)"). + builder.withGroup("data").withDescription("data tools group (print|imp|exp|encode|decode|compact|recover) (example ./artemis data print)"). withDefaultCommand(HelpData.class).withCommands(RecoverMessages.class, PrintData.class, XmlDataExporter.class, XmlDataImporter.class, DecodeJournal.class, EncodeJournal.class, CompactJournal.class); builder.withGroup("user").withDescription("default file-based user management (add|rm|list|reset) (example ./artemis user list)"). withDefaultCommand(HelpUser.class).withCommands(ListUser.class, AddUser.class, RemoveUser.class, ResetUser.class); builder = builder.withCommands(Run.class, Stop.class, Kill.class, PerfJournal.class); } else { - builder.withGroup("data").withDescription("data tools group (print) (example ./artemis data print)"). + builder.withGroup("data").withDescription("data tools group (print|recover) (example ./artemis data print)"). withDefaultCommand(HelpData.class).withCommands(RecoverMessages.class, PrintData.class); builder = builder.withCommand(Create.class); } diff --git a/docs/user-manual/en/data-tools.md b/docs/user-manual/en/data-tools.md index 51fee2942f..b07b3db4ac 100644 --- a/docs/user-manual/en/data-tools.md +++ b/docs/user-manual/en/data-tools.md @@ -2,18 +2,21 @@ You can use the Artemis CLI to execute data maintenance tools: -This is a list of sub-commands available +The following sub-commands are available when running the CLI data +command from a particular broker instance that has already been +installed using the create command: Name | Description ---|--- +print | Prints a report about journal records of a non-running server exp | Export the message data using a special and independent XML format imp | Imports the journal to a running broker using the output from expt -data | Prints a report about journal records and summary of existent records, as well a report on paging -recover | Revive data from the journal. It can be used in conjunction with historic journaling. encode | shows an internal format of the journal encoded to String decode | imports the internal journal format from encode +compact | Compacts the journal of a non running server +recover | Recover (undelete) messages from an existing journal and create a new one. -You can use the help at the tool for more information on how to execute each of the tools. For example: +You can use the CLI help for more information on how to execute each of the tools. For example: ``` $ ./artemis help data print @@ -28,9 +31,11 @@ SYNOPSIS [--jdbc-driver-class-name ] [--jdbc-large-message-table-name ] [--jdbc-message-table-name ] + [--jdbc-node-manager-table-name ] [--jdbc-page-store-table-name ] [--journal ] [--large-messages ] [--output ] - [--paging ] [--safe] [--verbose] [--] [] + [--paging ] [--reclaimed] [--safe] [--verbose] [--] + [] OPTIONS --bindings @@ -63,8 +68,11 @@ OPTIONS --jdbc-message-table-name Name of the jdbc messages table + --jdbc-node-manager-table-name + Name of the jdbc node manager table + --jdbc-page-store-table-name - Name of the page sotre messages table + Name of the page store messages table --journal The folder used for messages journal (default from broker.xml) @@ -78,6 +86,10 @@ OPTIONS --paging The folder used for paging (default from broker.xml) + --reclaimed + This option will try to print as many records as possible from + reclaimed files + --safe It will print your data structure without showing your data @@ -100,250 +112,328 @@ For a full list of data tools commands available use: ``` $ ./artemis help data NAME - artemis data - data tools group (print|imp|exp|encode|decode|compact) - (example ./artemis data print) + artemis data - data tools group + (print|imp|exp|encode|decode|compact|recover) (example ./artemis data + print) SYNOPSIS artemis data - artemis data compact [--verbose] [--paging ] - [--journal ] [--large-messages ] - [--broker ] [--bindings ] - artemis data decode [--verbose] [--suffix ] [--paging ] - [--prefix ] [--file-size ] --input - [--journal ] [--directory ] - [--large-messages ] [--broker ] - [--bindings ] - artemis data encode [--verbose] [--directory ] - [--suffix ] [--paging ] [--prefix ] - [--file-size ] [--journal ] - [--large-messages ] [--broker ] - [--bindings ] - artemis data exp [--jdbc-bindings-table-name ] - [--jdbc-message-table-name ] [--paging ] - [--jdbc-connection-url ] - [--jdbc-large-message-table-name ] [--f] - [--large-messages ] [--broker ] - [--jdbc-page-store-table-name ] - [--jdbc-driver-class-name ] [--jdbc] [--verbose] - [--journal ] [--output ] [--bindings ] - artemis data imp [--user ] [--legacy-prefixes] [--verbose] - [--host ] [--port ] [--transaction] --input - [--password ] [--sort] - artemis data print [--jdbc-bindings-table-name ] - [--jdbc-message-table-name ] [--paging ] - [--jdbc-connection-url ] - [--jdbc-large-message-table-name ] [--f] - [--large-messages ] [--broker ] - [--jdbc-page-store-table-name ] - [--jdbc-driver-class-name ] [--safe] [--jdbc] [--verbose] - [--journal ] [--output ] [--bindings ] + artemis data compact [--journal ] + [--large-messages ] [--paging ] + [--broker ] [--bindings ] [--verbose] + artemis data decode [--journal ] + [--large-messages ] [--file-size ] + [--paging ] [--prefix ] [--suffix ] + [--broker ] [--directory ] + [--bindings ] [--verbose] --input + artemis data encode [--journal ] + [--large-messages ] [--file-size ] + [--paging ] [--prefix ] [--suffix ] + [--broker ] [--bindings ] [--verbose] + [--directory ] + artemis data exp [--jdbc-driver-class-name ] + [--journal ] [--jdbc-connection-url ] + [--large-messages ] + [--jdbc-bindings-table-name ] [--paging ] [--f] + [--jdbc-large-message-table-name ] + [--broker ] [--jdbc-page-store-table-name ] + [--bindings ] [--jdbc] [--verbose] + [--jdbc-message-table-name ] + [--jdbc-node-manager-table-name ] [--output ] + artemis data imp [--legacy-prefixes] [--password ] + [--transaction] [--verbose] [--port ] [--user ] [--sort] + --input [--host ] + artemis data print [--reclaimed] + [--jdbc-driver-class-name ] [--journal ] + [--jdbc-connection-url ] [--large-messages ] + [--jdbc-bindings-table-name ] [--paging ] [--f] + [--jdbc-large-message-table-name ] [--safe] + [--broker ] [--jdbc-page-store-table-name ] + [--bindings ] [--jdbc] [--verbose] + [--jdbc-message-table-name ] + [--jdbc-node-manager-table-name ] [--output ] + artemis data recover [--jdbc-driver-class-name ] + [--journal ] [--jdbc-connection-url ] + [--large-messages ] [--reclaimed] --target + [--jdbc-bindings-table-name ] [--paging ] [--f] + [--jdbc-large-message-table-name ] + [--broker ] [--jdbc-page-store-table-name ] + [--bindings ] [--jdbc] [--verbose] + [--jdbc-message-table-name ] + [--jdbc-node-manager-table-name ] [--output ] COMMANDS With no arguments, Display help information + recover + Recover (undelete) every message on the journal by creating a new + output journal. Rolled backed and acked messages will be sent out to + the output as much as possible. + + With --jdbc-driver-class-name option, JDBC driver classname + + With --journal option, The folder used for messages journal (default + from broker.xml) + + With --jdbc-connection-url option, The connection used for the + database + + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --reclaimed option, This option will try to recover as many + records as possible from reclaimed files + + With --target option, Output folder container the new journal with + all the generated messages + + With --jdbc-bindings-table-name option, Name of the jdbc bindigns + table + + With --paging option, The folder used for paging (default from + broker.xml) + + With --f option, This will allow certain tools like print-data to be + performed ignoring any running servers. WARNING: Changing data + concurrently with a running broker may damage your data. Be careful + with this option. + + With --jdbc-large-message-table-name option, Name of the large + messages table + + With --broker option, This would override the broker configuration + from the bootstrap + + With --jdbc-page-store-table-name option, Name of the page store + messages table + + With --bindings option, The folder used for bindings (default from + broker.xml) + + With --jdbc option, It will activate jdbc + + With --verbose option, Adds more information on the execution + + With --jdbc-message-table-name option, Name of the jdbc messages + table + + With --jdbc-node-manager-table-name option, Name of the jdbc node + manager table + + With --output option, Output name for the file + print Print data records information (WARNING: don't use while a production server is running) - With --jdbc-bindings-table-name option, Name of the jdbc bindigns - table + With --reclaimed option, This option will try to print as many + records as possible from reclaimed files - With --jdbc-message-table-name option, Name of the jdbc messages - table + With --jdbc-driver-class-name option, JDBC driver classname - With --paging option, The folder used for paging (default from - broker.xml) + With --journal option, The folder used for messages journal (default + from broker.xml) With --jdbc-connection-url option, The connection used for the database - With --jdbc-large-message-table-name option, Name of the large - messages table + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --jdbc-bindings-table-name option, Name of the jdbc bindigns + table + + With --paging option, The folder used for paging (default from + broker.xml) With --f option, This will allow certain tools like print-data to be performed ignoring any running servers. WARNING: Changing data concurrently with a running broker may damage your data. Be careful with this option. - With --large-messages option, The folder used for large-messages - (default from broker.xml) + With --jdbc-large-message-table-name option, Name of the large + messages table + + With --safe option, It will print your data structure without + showing your data With --broker option, This would override the broker configuration from the bootstrap - With --jdbc-page-store-table-name option, Name of the page sotre + With --jdbc-page-store-table-name option, Name of the page store messages table - With --jdbc-driver-class-name option, JDBC driver classname - - With --safe option, It will print your data structure without - showing your data + With --bindings option, The folder used for bindings (default from + broker.xml) With --jdbc option, It will activate jdbc With --verbose option, Adds more information on the execution - With --journal option, The folder used for messages journal (default - from broker.xml) + With --jdbc-message-table-name option, Name of the jdbc messages + table + + With --jdbc-node-manager-table-name option, Name of the jdbc node + manager table With --output option, Output name for the file - With --bindings option, The folder used for bindings (default from - broker.xml) - exp Export all message-data using an XML that could be interpreted by any system. - With --jdbc-bindings-table-name option, Name of the jdbc bindigns - table + With --jdbc-driver-class-name option, JDBC driver classname - With --jdbc-message-table-name option, Name of the jdbc messages - table - - With --paging option, The folder used for paging (default from - broker.xml) + With --journal option, The folder used for messages journal (default + from broker.xml) With --jdbc-connection-url option, The connection used for the database - With --jdbc-large-message-table-name option, Name of the large - messages table + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --jdbc-bindings-table-name option, Name of the jdbc bindigns + table + + With --paging option, The folder used for paging (default from + broker.xml) With --f option, This will allow certain tools like print-data to be performed ignoring any running servers. WARNING: Changing data concurrently with a running broker may damage your data. Be careful with this option. - With --large-messages option, The folder used for large-messages - (default from broker.xml) + With --jdbc-large-message-table-name option, Name of the large + messages table With --broker option, This would override the broker configuration from the bootstrap - With --jdbc-page-store-table-name option, Name of the page sotre + With --jdbc-page-store-table-name option, Name of the page store messages table - With --jdbc-driver-class-name option, JDBC driver classname + With --bindings option, The folder used for bindings (default from + broker.xml) With --jdbc option, It will activate jdbc With --verbose option, Adds more information on the execution - With --journal option, The folder used for messages journal (default - from broker.xml) + With --jdbc-message-table-name option, Name of the jdbc messages + table + + With --jdbc-node-manager-table-name option, Name of the jdbc node + manager table With --output option, Output name for the file - With --bindings option, The folder used for bindings (default from - broker.xml) - imp Import all message-data using an XML that could be interpreted by any system. - With --user option, User name used to import the data. (default - null) - With --legacy-prefixes option, Do not remove prefixes from legacy imports - With --verbose option, Adds more information on the execution - - With --host option, The host used to import the data (default - localhost) - - With --port option, The port used to import the data (default 61616) + With --password option, User name used to import the data. (default + null) With --transaction option, If this is set to true you will need a whole transaction to commit at the end. (default false) - With --input option, The input file name (default=exp.dmp) + With --verbose option, Adds more information on the execution - With --password option, User name used to import the data. (default + With --port option, The port used to import the data (default 61616) + + With --user option, User name used to import the data. (default null) With --sort option, Sort the messages from the input (used for older versions that won't sort messages) + With --input option, The input file name (default=exp.dmp) + + With --host option, The host used to import the data (default + localhost) + decode Decode a journal's internal format into a new journal set of files - With --verbose option, Adds more information on the execution + With --journal option, The folder used for messages journal (default + from broker.xml) - With --suffix option, The journal suffix (default amq) + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --file-size option, The journal size (default 10485760) With --paging option, The folder used for paging (default from broker.xml) With --prefix option, The journal prefix (default activemq-data) - With --file-size option, The journal size (default 10485760) + With --suffix option, The journal suffix (default amq) - With --input option, The input file name (default=exp.dmp) - - With --journal option, The folder used for messages journal (default - from broker.xml) + With --broker option, This would override the broker configuration + from the bootstrap With --directory option, The journal folder (default journal folder from broker.xml) + With --bindings option, The folder used for bindings (default from + broker.xml) + + With --verbose option, Adds more information on the execution + + With --input option, The input file name (default=exp.dmp) + + encode + Encode a set of journal files into an internal encoded data format + + With --journal option, The folder used for messages journal (default + from broker.xml) + With --large-messages option, The folder used for large-messages (default from broker.xml) + With --file-size option, The journal size (default 10485760) + + With --paging option, The folder used for paging (default from + broker.xml) + + With --prefix option, The journal prefix (default activemq-data) + + With --suffix option, The journal suffix (default amq) + With --broker option, This would override the broker configuration from the bootstrap With --bindings option, The folder used for bindings (default from broker.xml) - encode - Encode a set of journal files into an internal encoded data format - With --verbose option, Adds more information on the execution With --directory option, The journal folder (default the journal folder from broker.xml) - With --suffix option, The journal suffix (default amq) - - With --paging option, The folder used for paging (default from - broker.xml) - - With --prefix option, The journal prefix (default activemq-data) - - With --file-size option, The journal size (default 10485760) - - With --journal option, The folder used for messages journal (default - from broker.xml) - - With --large-messages option, The folder used for large-messages - (default from broker.xml) - - With --broker option, This would override the broker configuration - from the bootstrap - - With --bindings option, The folder used for bindings (default from - broker.xml) - compact Compacts the journal of a non running server - With --verbose option, Adds more information on the execution - - With --paging option, The folder used for paging (default from - broker.xml) - With --journal option, The folder used for messages journal (default from broker.xml) With --large-messages option, The folder used for large-messages (default from broker.xml) + With --paging option, The folder used for paging (default from + broker.xml) + With --broker option, This would override the broker configuration from the bootstrap With --bindings option, The folder used for bindings (default from broker.xml) -``` \ No newline at end of file + With --verbose option, Adds more information on the execution + +```