From a7b9711befbf68712edd28ecd4b8cc15f88a37c9 Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Wed, 24 Apr 2024 17:10:35 +0530 Subject: [PATCH] TS-153 kpm diagnostic documentation --- .idea/dictionaries/default.xml | 22 +-- html5/_main_toc.html.slim | 3 + userguide/tutorials/debugging.adoc | 43 +---- .../tutorials/how-to-use-kpm-diagnostic.adoc | 174 ++++++++++++++++++ 4 files changed, 189 insertions(+), 53 deletions(-) create mode 100644 userguide/tutorials/how-to-use-kpm-diagnostic.adoc diff --git a/.idea/dictionaries/default.xml b/.idea/dictionaries/default.xml index e3b8a7540..dbe02ccfc 100644 --- a/.idea/dictionaries/default.xml +++ b/.idea/dictionaries/default.xml @@ -1,21 +1,21 @@ - docinfo - killbill - kaui - failover - elasticsearch - jconsole - healthcheck - uncollectible + Boleto Zuora arrear - proration autodetection - instance - Boleto + docinfo eXtensible + elasticsearch + failover + healthcheck + instance + jconsole + kaui + killbill + proration + uncollectible \ No newline at end of file diff --git a/html5/_main_toc.html.slim b/html5/_main_toc.html.slim index e891f5773..6aaf7f7d5 100644 --- a/html5/_main_toc.html.slim +++ b/html5/_main_toc.html.slim @@ -193,6 +193,9 @@ nav.sidebar-nav li a.nav-link href="/latest/kill_bill_events.html" | Kill Bill Events + li + a.nav-link href="/latest/how-to-use-kpm-diagnostic.html" + | KPM Diagnostic Usage li .icon-title a.bd-toc-link.main-link role="button" Plugin Development diff --git a/userguide/tutorials/debugging.adoc b/userguide/tutorials/debugging.adoc index 0dfc0ccf5..e7bcdf769 100644 --- a/userguide/tutorials/debugging.adoc +++ b/userguide/tutorials/debugging.adoc @@ -484,46 +484,5 @@ In your message, specify: * What you are seeing and what you are expecting * How to reproduce your scenario (cURL commands, code snippet, ...) -* https://github.com/killbill/killbill-cloud/tree/9305e1abb8840f22a03d2c36269710bff3dc1996/kpm#kpm-diagnostic[KPM diagnostic] output (see notes below) +* `kpm diagnostic` output (see https://docs.killbill.io/latest/how-to-use-kpm-diagnostic[KPM Diagnostic Usage]) -=== KPM Diagnostics Notes - -The `kpm diagnostic` command gathers information about your Kill Bill installation (Kill Bill/Kaui versions, Java version, plugins that you use, etc), Kill Bill logs, tenant configuration data and account data. It generates a zip file with this data. When this file is shared with us, it allows us to replicate your Kill Bill environment and diagnose the issue. - -In case of a https://docs.killbill.io/latest/getting_started.html#_tomcat[Tomcat installation], the `kpm diagnostic` command can be run as follows: - -[source,bash] ----- -kpm diagnostic --killbill-api-credentials=bob lazar --account-export=ACCOUNT_ID ----- - -Note that the parameters specified above are optional and refer to the following: - -* `killbill-api-credentials` - specifies the *tenant api key* and *tenant api secret* corresponding to the tenant for which you want to export data. If this parameter is skipped, data is exported for the default tenant (`bob/lazar`) -* `--account-export` specifies the *account id* for which account data (data from the Kill Bill database tables related) needs to be exported. If this parameter is skipped, account data is not exported. - -For a complete list of `kpm diagnostic` options, you can run `kpm help diagnostic`. - -If you are using a https://docs.killbill.io/latest/getting_started.html#_docker[Docker installation], you can simply run the following command in the Kill Bill container: - -[source,bash] ----- -$KPM_DIAGNOSTIC_CMD -e killbill_user=admin \ - -e killbill_password=password \ - -e killbill_api_key=bob \ - -e killbill_api_secret=lazar \ - -e killbill_account=ACCOUNT_ID ----- - -If you are using an https://docs.killbill.io/latest/getting_started.html#_aws_one_click[AWS installation], you can run the `kpm diagnostic` command as specified https://docs.killbill.io/latest/aws-singletier.html#_diagnostic_command[here]. - - -Once the `kpm diagnostic` command completes, it displays the path of the generated file. -For example, with a Tomcat installation on a Windows machine, it displays the following: - -[source,bash] ----- -Diagnostic data exported under C:/Users//AppData/Local/Temp/killbill-diagnostics-20220215-10768-1pplgn6/killbill-diagnostics-02-15-22.zip ----- - -The zip file named `killbill-diagnostics-02-15-22.zip` can be copied from this path and shared with us. \ No newline at end of file diff --git a/userguide/tutorials/how-to-use-kpm-diagnostic.adoc b/userguide/tutorials/how-to-use-kpm-diagnostic.adoc new file mode 100644 index 000000000..19d77c394 --- /dev/null +++ b/userguide/tutorials/how-to-use-kpm-diagnostic.adoc @@ -0,0 +1,174 @@ += How to use the KPM Diagnostic Tool + +The `kpm diagnostic` command gathers information about your Kill Bill installation (Kill Bill/Kaui versions, Java version, plugins that you use, etc.), Kill Bill logs, tenant configuration data and account data. It generates a zip file with this data. When this file is shared with us, it allows us to replicate your Kill Bill environment and diagnose the issue. + +== Running the Diagnostic Tool + +The kpm diagnostic tool can be run as follows: + +[source,bash] +---- +kpm diagnostic --killbill-api-credentials=bob lazar --killbill-credentials admin password --account-export=ACCOUNT_ID +---- + +Note that the parameters specified above are optional. The complete set of parameters are documented in the subsequent section. + +Once the kpm diagnostic command completes, it displays the path of the generated file. For example, with a Tomcat installation on a Windows machine, it displays the following: + +[source,bash] +---- +Diagnostic data exported under C:/Users//AppData/Local/Temp/killbill-diagnostics-20220215-10768-1pplgn6/killbill-diagnostics-02-15-22.zip +---- + +The zip file named `killbill-diagnostics-02-15-22.zip` can be copied from this path and shared with the KB Team. + + +== KPM Diagnostic Command Parameters + +The following table documents the complete list of parameters that can be specified with the `kpm diagnostic` command: + +|=== +|Options |Description | Default + +|--account-export +|Account Id. If specified, includes data from the KB database tables for the specified `accountId`. +| None (no account data is included) + +|--log-dir +|Log directory. If specified, includes the contents of the specified directory as a zip file +|Logs from `/logs` (`var/lib/tomcat/logs`) + +|--config-file +| Yml that contains the various config options. Alternative to specifying the individual parameters +|None + +|--killbill-api-credentials +|Tenant API Key and Tenant API Secret corresponding to the tenant for which you want to export data +|bob/lazar + +|--killbill-credentials +|KB authentication credentials +|admin/password + +|--killbill-url +|The KB URL to connect to +|http://127.0.0.1:8080 + +|--kaui-web-path +|The path to the Kaui war file. If specified, includes the Kaui version +|None (no version information is included) + +|--killbill-web-path +|The path to the KB war file. If specified, includes the KB version +|None (no version information is included) + +|--bundles-dir +|Plugin installation directory. If specified, includes information about the plugins installed at this path +|None (no plugin information is included) +|=== + +== Examples + +=== Example 1 + +[source,bash] +---- +kpm diagnostic --account-export=88a0f329-2893-46fe- +b3b7-4e21cafa2118 +---- +Exports data for the specified `accountId` (Assuming the account belongs to the `bob/lazar` tenant and the killbill credentials are `admin/password`). + +=== Example 2 + +[source,bash] +---- +kpm diagnostic --killbill-api-credentials=test test --killbill-credentials root root --account-export=88a0f329-2893-46fe-b3b7-4e21cafa2118 +---- + +Exports data for the specified `accountId` belonging to the `test/test` tenant. Uses the `root/root` KB credentials. + +=== Example 3 + +[source,bash] +---- +kpm diagnostic --killbill-api-credentials=bob lazar --killbill-credentials admin password +---- + +Exports only system and tenant data. No account information in exported since the `--account-export=` parameter is not specified + +=== Example 4 + +[source,bash] +---- +kpm diagnostic --account-export=88a0f329-2893-46fe-b3b7-4e21cafa2118 --bundles-dir=d:/var/tmp/bundles +---- + +Exports data for the specified `accountId`. Includes plugin information from the `d:/var/tmp/bundles` path. + +=== Example 5 + +[source,bash] +---- +kpm diagnostic --account-export=88a0f329-2893-46fe-b3b7-4e21cafa2118 --kaui-web-path=/var/lib/tomcat/webapps2/ROOT.war --killbill-web-path=/var/lib/tomcat/webapps/ROOT.war +---- + +Exports data for the specified `accountId`. Includes Kaui/KB version. + +=== Example 6 + +Create a file called `config.yml` as follows: + +[source,yml] +---- +killbill: + api_key: bob + api_secret: lazar + port: 8080 + host: localhost + user: admin + password: password + plugins_dir: /var/tmp/bundles +---- + +[source,bash] +---- +kpm diagnostic --account-export=88a0f329-2893-46fe-b3b7-4e21cafa2118 --config_file=D:/D +ata/Temp/config.yml +---- + +Exports data for the specified `accountId` using the details from `config.yml` + +== Environment Specific Notes + +=== Tomcat + +In a Tomcat installation, the `kpm` tool needs to be explicitly installed if not already done. Refer to the https://github.com/killbill/killbill-cloud/tree/master/kpm#kpm-installation[kpm installation notes]. + +After the `kpm` tool is installed, you can run the `kpm diagnostic` command as explained above. + +=== Docker + +In case of a Docker installation, the `kpm diagnostic` command needs to be run within the Kill Bill Docker container. + +Alternatively, you can also run the following command within the Kill Bill Docker container: + +[source,bash] +---- +$KPM_DIAGNOSTIC_CMD -e killbill_user=admin \ +-e killbill_password=password \ +-e killbill_api_key=bob \ +-e killbill_api_secret=lazar \ +-e killbill_account=ACCOUNT_ID +---- + +=== AWS + +In case of an AWS installation, you would need to login as Tomcat using the following command: + +[source,bash] +---- +# Login as 'tomcat' +sudo su - tomcat +---- + +After this, you can run the kpm diagnostic command as mentioned above. \ No newline at end of file