diff --git a/trento/adoc/trento-analyze-problems.adoc b/trento/adoc/trento-analyze-problems.adoc index fecc50f..b762dd1 100644 --- a/trento/adoc/trento-analyze-problems.adoc +++ b/trento/adoc/trento-analyze-problems.adoc @@ -2,98 +2,90 @@ include::product-attributes.adoc[] [[sec-trento-problemanalysis]] == Problem Analysis -:revdate: 2025-06-10 +:revdate: 2025-10-27 -This section covers common problems and how to analyze them. - === {trserver} -There are two tools you can use to analyze issues with {trserver} in a -{k8s} scenario. These tools collect information and data that can be -useful when troubleshooting and analyzing the issue. +There are two tools you can use to collect information and data that can be useful when troubleshooting and analyzing issues with {trento} Server. + +==== {trento} support plugin + +The {trento} support plugin consists of the `trento-support.sh` script and the support plugin itself. The tool automates the collection of logs and relevant runtime information on the server side. It can be used in two different scenarios: + +* A deployment on K3s +* A systemd deployment -==== {trento} Support Plugin +==== Using the {trento} support plugin with a K3s deployment -The {trento} support plugin automates the collection of logs and -relevant runtime information on the server side. Using the plugin -requires a host with the following setup: +Using the plugin with a K3s deployment requires a {sles4sap} 15 SP3 or higher host with the following setup: -* The packages jq and python3-yq are installed. -* Helm is installed. -* The command `+kubectl+` is installed and connected to the {k8s} -cluster where {trserver} is running. +* Packages `jq` and `yq` are installed +* Helm is installed +* `kubectl` is installed and connected to the {k8s} cluster where {trserver} is running To use the plugin, proceed as follows: -. Download the {trento} support plugin script: +. Install the {trento} support plugin: + ==== [source,subs="attributes"] ---- -{prompt_root}wget https://raw.githubusercontent.com/trento-project/support/refs/heads/main/trento-support.sh +{prompt_root}zypper ref +{prompt_root}zypper install supportutils-plugin-trento ---- ==== + -[NOTE] -.Package available in {sles4sap} 15 SP3 and higher -==== -Customers of {sles4sap} 15 SP3 and higher can install the -trento-supportconfig-plugin package directly from the official -{sles4sapa} 15 repos using {zypper}. The Containers Module is required -for installation. -==== -. Make the script executable: +. Run the `trento-support.sh` script: + ==== [source,subs="attributes"] ---- -{prompt_root}chmod +x trento-support.sh +{prompt_root}trento-support.sh --output file-tgz --collect all ---- ==== + -. Make sure that `+kubectl+` is connected to the {k8s} cluster where -{trserver} is running and execute the script: +. Send the generated archive file to support for analysis. + +The script accepts the following options: + +* `-o`, `--output` Output type (`stdout`, `file`, `file-tgz`) +* `-c`, `--collect` Collection options (`configuration`, `base`, `kubernetes`, `all`) +* `-r`, `--release-name` Release name to use for the chart installation. Default is `trento-server` +* `-n`, `--namespace` {k8s} namespace used when installing the chart.Default is `default` +* `--help` Shows help messages + +==== Using the {trento} support plugin with a systemd deployment + +To use the plugin in this scenario, proceed as follows: + +. Install the {trento} support plugin: + ==== [source,subs="attributes"] ---- -{prompt_root}./trento-support.sh --output file-tgz --collect all +{prompt_root}zypper ref +{prompt_root}zypper install supportutils-plugin-trento ---- ==== + -. Send the generated archive file to support for analysis. +. Execute supportconfig as described in https://documentation.suse.com/sles/html/SLES-all/cha-adm-support.html\#sec-admsupport-cli. The `supportconfig` tool will call the {trento} support plugin. +. Send the generated output to support for analysis. -The {trento} support plugin accepts the following options: +=== Scenario dump script -`+-o+`, `+--output+`:: - Output type. Options: stdout|file|file-tgz -`+-c+`, `+--collect+`:: - Collection options: configuration|base|kubernetes|all -`+-r+`, `+--release-name+`:: - Release name to use for the chart installation. "trento-server" by - default. -`+-n+`, `+--namespace+`:: - {kube} namespace used when installing the chart. "default" by - default. -`+--help+`:: - Shows help messages +A scenario dump is a dump of the {trento} database. It helps the {trento} team to recreate the scenario to test it. -==== Scenario dump +A script is available in the {trento} upstream project. The script helps generate a scenario dump when the server is running on a {k8s} cluster. Using this script requires a host with the following setup: -The scenario dump is a dump of the {trento} database. It helps the -{trento} team to recreate the scenario to test it. Using the script -that generates the dump requires a host with the following setup: - -* The command `+kubectl+` is installed and connected to the {k8s} -cluster where {trento} Server is running. +* `kubectl` is installed and connected to the {k8s} cluster where {trserver} is running. To generate the dump, proceed as follows: . Download the latest version of the dump script: + ==== -[source,bash,subs="attributes"] +[source,subs="attributes"] ---- {prompt_user}wget https://raw.githubusercontent.com/trento-project/web/main/hack/dump_scenario_from_k8.sh ---- @@ -102,53 +94,47 @@ To generate the dump, proceed as follows: . Make the script executable: + ==== -[source,bash,subs="attributes"] +[source,subs="attributes"] ---- {prompt_user}chmod +x dump_scenario_from_k8.sh ---- ==== + -. Make sure that `+kubectl+` is connected to the {k8s} cluster where -{trserver} is running and execute the script as follows: +. Make sure that `kubectl` is connected to the {k8s} cluster where {trserver} is running and run the script: + ==== -[source,bash,subs="attributes"] +[source,subs="attributes"] ---- {prompt_user}./dump_scenario_from_k8.sh -n SCENARIO_NAME -p PATH ---- ==== + -. Go to `+/scenarios/+`, collect all the JSON files and send them to -support for analysis. +. Go to `PATH/scenarios/SCENARIO_NAME`, package all the generated JSON files, and send the package to support for analysis. -==== Pods descriptions and logs +=== Pods descriptions and logs -In addition to the output of the {trento} Support Plugin and the Dump -Scenario script, the descriptions and logs of the {trserver} pods can -be useful for analysis and troubleshooting purposes. These descriptions -and logs can be easily retrieved with the `+kubectl+` command. For this -to work, you need a host where kubectl is installed and connected to the -{k8s} cluster running {trserver}. +In case of a deployment on K3s, the descriptions and logs of the {trserver} pods can be useful for analysis and troubleshooting purposes (in addition to the output of the trento-support.sh script and the dump scenario script). These descriptions and logs can be obtained with the `kubectl` command. For this to work, you need a host with `kubectl` is installed and connected to the K3s cluster running {trserver}. -. List the pods running in {k8s} cluster and their statuses. -{trserver} currently consists of the following six pods: +. List the pods running in {k8s} cluster and their statuses. Run the command below to view {trserver} pods: + ==== -[source,bash,subs="attributes"] +[source,subs="attributes"] ---- {prompt_user}kubectl get pods -trento-server-prometheus-server-* -trento-server-postgresql-0 -trento-server-web-* -trento-server-wanda-* -trento-server-rabbitmq-0 + +NAME READY STATUS RESTARTS AGE +trento-server-postgresql-0 1/1 Running 0 87m +trento-server-prometheus-server-7b5c9474bc-wmv8s 2/2 Running 0 87m +trento-server-rabbitmq-0 1/1 Running 0 87m +trento-server-wanda-67ffbb79dc-7t6xw 1/1 Running 0 87m +trento-server-web-7df8f65794-vdbhs 1/1 Running 0 87m ---- ==== + . Retrieve the description of a pod as follows: + ==== -[source,bash,subs="attributes"] +[source,subs="attributes"] ---- {prompt_user}kubectl describe pod POD_NAME ---- @@ -157,7 +143,7 @@ trento-server-rabbitmq-0 . Retrieve the log of a pod as follows: + ==== -[source,bash,subs="attributes"] +[source,subs="attributes"] ---- {prompt_user}kubectl logs POD_NAME ---- @@ -166,60 +152,8 @@ trento-server-rabbitmq-0 . Monitor the log of a pod as follows: + ==== -[source,bash,subs="attributes"] +[source,subs="attributes"] ---- {prompt_user}kubectl logs POD_NAME --follow ---- -==== - -=== {tragent} - -The first source to analyze issues with the {tragent} is the {tragent} -status. It can be retrieved as follows: - -==== -[source,bash,subs="attributes"] ----- -{prompt_sudo}systemctl status trento-agent ----- -==== - -If further analysis is required, activate debug log level for the agent. -A detailed log can be then retrieved from the journal: - -. Add parameter `+log-level+` with value `+debug+` to the -`+/etc/trento/agent.yaml+` configuration file. -+ -==== -[source,bash,subs="attributes"] ----- -{prompt_sudo}vi /etc/trento/agent.yaml ----- -==== -+ -. Add the following entry: -+ -==== -[source,bash] ----- -log-level: debug ----- -==== -+ -. Restart the agent: -+ -==== -[source,bash,subs="attributes"] ----- -{prompt_sudo}systemctl restart trento-agent ----- -==== -+ -. Retrieve the log from the journal: -+ -==== -[source,bash,subs="attributes"] ----- -{prompt_sudo}journalctl -u trento-agent ----- -==== +==== \ No newline at end of file diff --git a/trento/adoc/trento-report-issue.adoc b/trento/adoc/trento-report-issue.adoc index 90b88b9..eb266ed 100644 --- a/trento/adoc/trento-report-issue.adoc +++ b/trento/adoc/trento-report-issue.adoc @@ -2,7 +2,7 @@ include::product-attributes.adoc[] [[sec-trento-report-problem]] == Reporting an Issue -:revdate: 2025-06-10 +:revdate: 2025-10-27 {suse} customers with registered {sles4sap}{nbsp}15 (SP3 or higher) @@ -12,14 +12,13 @@ Problems must be reported under {sles4sap}{nbsp}15 and component trento. When opening a support case for {trento}, provide the relevant -deployment option for {trserver}: {k8s}, systemd or containerized. +deployment option for {trserver}: {k8s}, systemd or containerized ({docker}-based). In case of a {k8s} deployment, provide the output of the {trento} -support plugin and the scenario dump, as explained in section +support script as explained in section <>. -In case of a systemd deployment, provide the status and the journal of -the trento-web and trento-wanda services. +In case of a systemd deployment, provide the output of the {trento} support plugin, as explained in section <>. In case of a containerized deployment, provide the logs of the trento-web and trento-wanda containers. Use `+docker ps+` to retrieve