KB-2250 How to run the Appian Log Generator and Diagnostics scripts

Purpose

Appian is made up of multiple components, all of which must remain healthy for the platform to function properly. Traditionally, checking the health of each component requires running separate built-in scripts, which can be time consuming. Troubleshooting often involves collecting various log files based on the issue at hand - a process that typically requires manually identifying, zipping, and compressing multiple files and folders across different components.

This article introduces the following tools that simplify and streamline this process:

• The Appian Log Generator scripts - Quickly creates a tar file containing relevant logs from different Appian components, reducing the manual effort involved in log collection.
• The Appian Diagnostics script - Gathers essential health metrics from the Appian environment and the underlying server in a fast and efficient way.
• The Appian on Kubernetes Log Generator and Diagnostics script - Gathers logging, metrics, and configuration details from the Appian environment, designed specifically for Appian on Kubernetes.

Table of Contents:

• What are the Appian Log Generator scripts?
• What is the Appian Diagnostics script?
• Equivalent for Appian on Kubernetes
• Instructions (non-Kubernetes)
  
  • Log Generator
  • Diagnostics
• Instructions (Kubernetes)

What are the Appian Log Generator scripts?

Appian Support maintains two scripts for log generation for non-containerized Appian (running on Windows or Linux OS):

1. appian_tomcat_ss_ads_log_generator.sh - This script retrieves:
   1. The five most  recent service_manager*.log.
   2. The logs/service-manager directory which has the kafka and zookeeper logs.
   3. The forty five most recent db_* logs.
2. appian_tomcat_ss_ads_log_generator.sh - This script retrieves:
   1. The five most recent tomcat-stdOut* log.
   2. The search-server directory hosting the search-server logs.
   3. The data-server directory hosting the data-server logs. 

Note that the script only gathers the logs from the server that the script is run on. The script should be run individually on each server that the logs should be fetched from.

What is the Appian Diagnostics script?

The Appian Diagnostics script appian_health_diagnostics.sh combines the different diagnostic scripts into a single script so that the state of each component in the environment can be understood by running one single script. In addition to the health of the Appian components the script also provides system level details like the RAM, CPU and disk usage of the server used to host Appian.

Note that this script does not interact with log files or retrieves any information that could be deemed sensitive in nature, apart from server hostnames. The script only leverages the existing out-of-the-box diagnostic scripts and prints the output to a new log file. The script only gathers the details of the Appian components which are hosted on the server that the script is run on.

Equivalent for Appian on Kubernetes

In addition to the above scripts, Appian Support also maintains one script for both log generation and diagnostics for Appian on Kubernetes.

1. aok_log_diagnostic_script.sh - This script retrieves:
   1. Pod logs for all core Appian components in the site's namespace.
   2. Pod and node resource metrics and status outputs.
   3. The Appian custom resource definition (CRD).

Instructions (non-Kubernetes)

Log Generation Scripts

The script to gather engine, service-manager, kafka, and zookeeper logs can be downloaded here.

The script to gather tomcat, search-server, and Appian data-server logs can be downloaded here.

Run the following steps to execute the script:

1. Place the relevant script in the <APPIAN_HOME>/logs of the server the logs need to be generated on.
   1. For high availability environments, the script should be placed in <APPIAN_HOME>/shared-logs/*server_name* folder of the server the logs need to be generated on. For example: <APPIAN_HOME>/shared-logs/machine1.example.com/
2. Make the script executable. For example:
   1. chmod +x appian_tomcat_ss_ads_log_generator.sh
3. Execute the script. For example:
   1. ./appian_tomcat_ss_ads_log_generator.sh
4. The script will generate the a file of the format hostname_date*.tar.gz in the directory the script is executed in.
5. Attach the newly generated tar.gz file to the Support Case.

Diagnostic Script

Run the following steps to execute the script:

1. Download the script to the server which hosts Appian.
2. Make the appian_health_diagnostics.sh script executable.
   1. chmod +x appian_health_diagnostics.sh
3. Run the following command: appian_health_diagnostics.sh -d *APPIAN_HOME* -p *SERVICE_MANAGER_PASSWORD*
   1. eg: ./appian_health_diagnostics.sh -d /usr/local/appian/ae -p password
4. The script will generate the diagnostic file in the APPIAN_HOME/logs directory.
5. Attach the newly created diagnostic file to the support case.

Instructions (Appian on Kubernetes)

The script to gather logs and metrics for Appian on Kubernetes can be downloaded here.

Run the following steps to execute the script

1. Place the script in a location where it can reach the cluster. The script works by executing a series of kubectl commands, so any CLI that can reach the cluster's API Server should work.
2. Make the script executable. For example:
   1. chmod +x aok_log_diagnostic_script.sh
3. Execute the script, passing in a parameter for the namespace for your Appian site. For example:
   1. ./aok_log_diagnostic_script.sh *my-appian-site*
4. Optionally you can also pass in a parameter to specify how many days of logging to collect (default is logs from the last 2 days). For example, to collect logs from the past 3 days you would run
   1. ./aok_log_diagnostic_script.sh *my-appian-site* 3
5. The script will generate a file called aok_log_diagnostic_bundle.tar in the directory the script is executed in.
6. Attach the newly generated .tar file to the Support Case.

Affected Versions

This article applies to Appian 18.3 and later.

Last Reviewed: May 2025