This article aims at equipping users with the knowledge of extending the snap utility to collect debug data for third-party components installed on a system. Some background understanding of snap such as architectural overview, various components, and so on are also covered as a part of this article. We conclude the article with a full-fledged example.

Share:

Prateek Goel (pragoel1@in.ibm.com), Staff Software Engineer, IBM

photo of Prateek GoelPrateek has been working with the IBM AIX® reliability, availability, and serviceability (RAS) features development team. He has written articles on ProbeVue in IBM developerWorks® and IBM Systems Magazine forums.



11 November 2013

Also available in Chinese Russian

Introduction

To start debugging any problem, the support team or developers might need some background information such as the system configuration, processes that were active, parameters setting of various components, and so on. Because the problem is not known at the data collection time, it is difficult to predict the set of information that is sufficient. Additionally, asking customers to keep sending small sets of information as required during problem analysis might make them unhappy. Customers expect support teams to collect as much data as they might need in a single go and just come back to them with the solution. To do that, though, you would need to give a number of commands to customers to run with various flags and send the details. This is something that a customer can easily get upset about.

To simplify this requirement, AIX provides a utility named snap, which is a debug data collection utility.

It has grouped data collection logically into various components. Support and development team members can decide upon which components are the need of the hour and collect the data only for those. In the recent IBM AIX® release, snap has been improved to provide user the flexibility to add their defined data collection scripts on top of what snap can collect today.

The focus of this article is to get the reader familiar with the type of data collected corresponding to the various snap flags, and how users can plug in their debug data collection scripts with the snap framework. We conclude with an example of integrating user-written data collection scripts with the snap framework.

Architectural view

Every customer system might have different configuration to meet their varied requirements and every different subsystem or configuration might have its own set of commands to collect debug data. To accommodate data collection across this variety of commands, snap has logically divided these data collection commands into various groups. Each group identifies the type of information it is meant to collect. The "general" group collects generic system information, the "kernel" group collects information about the attributes of the kernel, the "tcpip" group gathers information about the networking component of the system, and so on.

With this grouping, users do not have to remember every command and just need to run the snap command with the correct flags. Hence, with snap users (support and customer team members) get a single interface to collect the debug data from various components, irrespective of system setup.

Table 1. Components and data collected by them
snap componentsnap flagRemarks
async-AGather async (tty) information
dump-DGather dump and /unix along with livedump information.
filesys-fGather file system information
general-gGather general information such as list of devices, configuration files, and so on
hacmp-eGather IBM HACMP™ information
IB-YGather InfiniBand® debug information
install-iGather installation information
kernel-kGather kernel information such as various kernel tunables and so on
lang-lGather programming language information for various compilers installed
lvm-LGather Logical Volume Manager (LVM) information
nfs-nGather Network File System (NFS) information
pcixscsi and sissas-IGather PCI-X-SCSI and SISSAS information
printer-pGather printer information such as device attributes and so on
product-zTo run third-party debug commands
scraid-RGather Small Computer System Interface (SCSI) Redundant Array of Independent Disks (RAID) information
sna-sGather Systems Network Architecture (SNA) information
ssa-bGather Serial Storage Architecture (SSA) adapter/disk information
tcpip-tGather TCP/IP information such as various tunables, configurations, and so on
wlm-wGather Workload Manager (WLM) information such as WLM classes installed, and so on
wpars-@Gather Workload Partition (WPAR) information
XS25-XGather X.25 licensed program product (LPP) information

To name a few other components, such as Reliable Scalable Cluster Technology (RSCT), data is captured as part of the general component. System related trace is also captured as part of the general information.

For a complete list of flags and other options of snap, refer to the links in the Resources section.

Whenever snap collects data, the default directory used is /tmp/ibmsupt/. Under this directory, there are sub directories that might be created based on the snap components. That is, for every snap component, users can see one directory.

And, the following two special directories (snap components) are created:

  • other: This is the directory under which customers can keep any additional information that they would like to share with the IBM support team.
  • testcase: Under this directory, customers can update their test cases for the IBM support team to look at.

Extending snap data collection

There are multiple vendors providing various devices, applications for users to consume as per their requirement. In systems having such third-party devices, the problem might have been caused due to malfunctioning of one of the third-party pieces. Because snap is built by AIX developers, they might not know what third-party devices customers might use, what type of debug information to be collected, and so on. Hence, snap cannot have something inbuilt for all third-party devices.

From a customer point of view, even if, he knows what all commands to run to collect information related to third-party devices, it might be burden on him to run all of them.

To maintain snap as a single interface for all types of debug data collection, it has been extended to let third-party vendors register their debug data collection scripts with the snap framework. Users can run the snap command with an additional flag provided for this functionality to collect third-party debug data along with AIX-specific data. This functionality is expected to reduce load on customers and support team for collection data.

The z flag has been added to the snap command to allow users to perform activities such as registering, unregistering, and running third-party commands. It accepts tags such as ADD, DELETE, and so on along with the following fields as parameters:

  • product_name: Defines the class of the script belongs to. This can be any value with which users can identify a group of scripts together. This help in grouping scripts that are logically similar. For example, assume that there are three different network adapters from three different third parties. If all of them classify their scripts with class as network then users can run the following command to collect the debug data for all the network devices.
    # when no tag is passed it indicates execution of script.
    # snap - z class="network"
  • command_path: Defines the script to run along with its arguments. You need to provide the complete path along with the arguments with which this script must be invoked.

Registering third-party debug script

Use the ADD keyword with the "z" flag.

For example, the following command registers the /myprod/bin/dbgscript -a script as part of the myprod product belonging to the myclass class.

#snap -z ADD "product_name=myprod" "class=myclass" "command_path=/myprod/bin/dbgscript -a"

Key points:

  • If the debug binary is changed or updated, the user must re-register the script to update the snap repository with the latest binary.
  • Special characters such as ', <, and | are not supported as values to the command_path variable.
  • If, there is any entry that has been made previously with same product name, all of them will be unregistered before registering the new one.

Unregistering third-party debug script

Use the DELETE keyword with the "z" flag.

For example, the following command deletes all entries with product_name specified as productname.

#snap -z DELETE "product_name=productname"

Note: Users cannot delete entries based on the class or the command_path attribute.

Running a third-party debug script

In this activity, users actually run the scripts that are registered. There are four ways in which users can run the scripts to collect the required debug information.

  • Single product: Runs the data collection script for a single product. The following example runs the scripts registered under product_name as myproduct.
    # snap -z "product=myproduct"
  • Multiple products: Runs the data collection script for multiple products. The following command runs all the scripts registered under product_name as abc and def.
    # snap -z "product_name=abc" -z "product_name=def"
  • Gather data based on class: Runs the scripts registered with myclass as the class field.
    Note: This might result in running scripts from different products as well if they have registered with the same class.
    # snap -z "class=myclass"
  • Gather data for all the scripts registered: Runs all the scripts irrespective of calls and product.
    # snap -z ALL  # Runs all the scripts irrespective of class and product.

Key points:

  • The snap command's "z" flag can be used along with other snap flags but is exclusive to a flag.
  • The snap command's "a" flag internally is equivalent to snap z ALL.

Because these are user specified scripts, the time taken for data collection might be greater than the default timeout value. Hence, it is advised to use the M option to specify any timeout value other than the default as needed by the script (as shown in the following example).

# snap -z "product_name=abc" -M 500

Usage tips

  • Only root users can register. Additional privilege has to be assigned to the Role Based Access Control (RBAC) user to provide the authority to register third-party scripts.
  • It is useful to register similar products into similar classes such as network or devices, as data collection becomes easy.

Writing pluggable scripts

snap has been designed to be a two-pass data collection tool.

  • Pass 1 - The size of the data to be collected is determined.
  • Pass 2 - Real work of data collection is to be carried out.

Any third-party script that is registered with snap must also comply with this design. The design to be adhered is shown in the following example.

##########################################
# Log what action your script is taking
##########################################
if [ "$PASSNO" = 1 ]
then
    echo " Checking space requirement for myproduct...\c" >> $SCRIPTLOG
else
    echo "Gathering myproduct information...\c" >> $SCRIPTLOG
fi
##############################################
# do common work if, any
# remember this code will be
# executed for both pass 1 and pass 2
##############################################
If [  "$PASSNO" = 1 ]
then
    let total_bytes=$size_for_one*$ No_of_adapters
       ############################################
       # Update the size of data into file so that snap can use it.
       ############################################
echo "$total_bytes" > $SCRIPTSIZE
exit 0
fi
if [[ -z $SNAPDIR ]]
then
             ###################################
             #do data collection and redirect output to 
             # $SNAPDIR/yourfilename
             ##################################
 fi
#######################################
# Update in log before exiting the script..
# this is required in PASS 2 only.
#######################################
echo " done." >> $SCRIPTLOG

Variables exported by snap, which are to be used in user script:

  • $PASSNO: This indicated for which pass ( pass 1 or pass 2 ) it needs to process the data.
  • $SCRIPTLOG: This contains the file name to which the script needs to log any action it needs to.
  • $SCRIPTSIZE: This contains the file name where the size of the data to be collected needs to be mentioned.
  • $SNAPDIR: This points to the directory under which all the debug data can be stored. Users are free to use this directory in the way they prefer. For example, if there are multiple data files collected, each file can be kept in different sub-directories or in one directory but named differently, or even combine all the data into a file.

Note: snap internally makes a copy of the script in its own privileged directory. So, if a user modifies the script in the existing location, it will not be reflected. In such cases, the user must re-register this script.

Example

User debug data collection script

# cat /home/bin/myscript.sh
Size_For_One=$1
                                                
if [ "$PASSNO" = 1 ]
then
    echo "Checking space requirement for myproduct...\c" >> $SCRIPTLOG
else
    echo "Gathering myproduct information...\c" >> $SCRIPTLOG
fi
#####################################################
# do common work if, any
# remember this code will be executed for both pass 1 and pass 2
#####################################################
Number_Of_Files=`ls -l /home/ibm/  | wc -l`
if [  $quot;$PASSNO" = 1 ]
then
       let total_bytes=$Size_For_One*$Number_Of_Files
       echo "$total_bytes" > $SCRIPTSIZE
       exit 0
fi
if [[ -z $SNAPDIR ]]
then
       ###################################
       #do data collection and redirect output to 
       # $SNAPDIR/yourfilename
       ##################################
       cp /home/ibm/* $SNAPDIR/
fi
echo " done." >> $SCRIPTLOG

Registering user debug data collection script

In the following command, the command_path field contains the complete path of the script and an argument to be passed to the script.

#snap -z ADD "product=myproduct" "class=myclass" "command_path=/home/ibm/myscript.sh 1024"

Running user debug data collection script

In the following command, we are asking snap to collect general debug data along with that run the scripts registered with the product or the class as specified. Users are free to use other snap flags along with the -z flag.

# snap -g -z "product=myproduct"
---  OR ----
# snap -g -z "class=myclass"

Unregistering user debug data collection script

# snap -z DELETE "product=myproduct"

zsnap tool

The zsnap tool complements the snap command. It calls snap for all standard data gathering. This tool provides additional information gathering routines that extend the IBM ability to obtain information for improved customer service. The zsnap tool was created and is supported by the technical support team. IBM recommends that you install zsnap before you call the AIX or PowerHA technical support center.

You can find more information about zsnap and the download links in the Resources section.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into AIX and Unix on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX
ArticleID=952077
ArticleTitle=Extending snap data collection
publish-date=11112013