apdiag command reference

apdiag [-h] [-v] {doc,list,collect}

-h|--help

Displays help for the command.

-v|--version

Displays command version.

doc

Displays more detailed information about command options.

list

Lists available components/symptoms/component sets.

collect

Collects diagnostic data.

apdiag list [-h] [--components] [--symptoms] [--sets] [--system-type {Local|Appliance|IDAA}]

-h|--help

Displays help for the command.

--components

Lists all the components with their subcomponents. For example, database/uptime is an example of a component (database) and subcomponent (uptime).

--symptoms

Lists all the symptoms, such as crash and outofmemory. For a full list of available symptoms, see Running diagnostics by using the apdiag command.

--sets

Lists all the component sets. A component set is a group of components that are frequently used together to accomplish a task. For example, the ha_logs component set contains logs from different components that are useful for investigating HA issues.

--system-type {Local|Appliance|IDAA}

Specifies the system type. This parameter is required only if it is not possible to automatically detect the system type, which results in an error. The system types include the following options:

Local

IBM® Db2® Warehouse.

Appliance

Integrated Analytics System.

IDAA

IBM Db2 Analytics Accelerator

apdiag collect [-h] [--components [COMPONENT [COMPONENT ...]]]
                      [--symptoms [SYMPTOM [SYMPTOM ...]]]
                      [--sets [SET [SET ...]]] [--comp-file COMPFILE]
                      [--minus-components [COMPONENT [COMPONENT ...]]]
                      [--skip-cores] [--ignore-space-check]
                      [--atime TIMESTAMP] [--btime TIMESTAMP]
                      [--nodes [NODE [NODE ...]]] [--headnode HEADNODE]
                      [--datanodes [DATANODE [DATANODE ...]]]
                      [--dumpdir DUMPDIR] [--suffix SUFFIX]
                      [--schemas [SCHEMA [SCHEMA ...]]]
                      [--dsns [DSN [DSN ...]]] [--fsns [FSN [FSN ...]]] 
                      [--fabsws [FABSW [FABSW ...]]]
                      [--fcsws [FCSW [FCSW ...]]]
                      [--mgtsws [MGTSW [MGTSW ...]]]
                      [--timeout-multiply NUMBER] [--estimate-time]
                      [--comp-threads NUMBER]
                      [--system-type {Local,Appliance,IDAA}]
                      [--comp-param [COMP:ARG[,ARG...] [COMP:ARG[,ARG...]...]]] 
                      [--skip-secure-data] [--force]
                     

--components {all|'*'|component [component]}

Specifies whether to collect data for all components (if you specify all or '*') or for one or more specific components. You can specify the component name with or without a subcomponent name. For example, you can specify database to collect data about all subcomponents of the database component or specify database/uptime to collect information for just the uptime subcomponent. You cannot specify a subcomponent name alone (for example, uptime). Separate each component name with a space. For a list of all available components, run apdiag list --components.

--symptoms [symptom [symptom]]

One or more space-separated symptoms for which to collect information. For a list of all available symptoms, run apdiag list --symptoms.

--sets [set [set]]

One or more component sets for which to collect information. For a list of all available sets, run apdiag list --sets.

--comp-file compfile

A plain text file that contains a list of components for which to collect data. Specify each component on a separate line in plain text.

--minus-components [component [component]]

Space-separated list of one or more components to omit when collecting data. For a list of all available components, run apdiag list --components.

--skip-cores

Skips the collection of the core files generated by various components. The core file name pattern mentioned within each component is used to identify the files to skip during collection.

--ignore-space-check

Ignores the minimum space requirement check. When omitted, the tool checks if the system has the required free disk space. Returns error if space requirements are not fulfilled.

--atime timestamp

--btime timestamp

Defines a time window from which to collect the data. --atime specifies the starting point of the window, --btime specifies the ending time. If --atime is not given, then the default starting time is 7 days ago. If --btime is not given, then the default ending time is now(). The following time formats must be used:

• YYYY-mm-dd HH:MM:SS
• nH/D/W where n is a number of hours, days, or weeks respectively, for example: --atime 8H --btime 1H would mean a time window of 7 hour length with starting time now()-8H, and end time now()-1H.

Note: The --atime and --btime options can be applied only to components that recognize a time window restriction. When you use --btime, you must consider that a log file might include entries that are time stamped before the specified --btime value of interest, but the log file might be modified after the specified --btime value. In such a case, the log file is not collected because the modification time is outside of the time window.

--nodes node [node]

Specifies the names of one or more nodes to collect logs for. This parameter is required in two cases:

• If you want to run the command against a subset of nodes. By default, the command runs against all nodes.
• If you want to run the command against all nodes but the nodes and their roles cannot be automatically detected, which results in an error.

For the node values, use the host names and not the IP addresses. Separate each node name with a space.

--headnode headnode

Specifies the name of the head node. This parameter is required only if you want to run the command against the head node but it cannot be automatically detected, which results in an error.

For the headnode value, use the host name and not the IP address.

--datanodes datanode [datanode]

Specifies the names of one or more data nodes. This parameter is required only if you want to run the command against data nodes but they cannot be automatically detected, which results in an error.

For the datanode values, use the host names and not the IP addresses. Separate each node name with a space.

--dumpdir dump_directory

Specify the dump directory as an absolute path on localhost. By default, the directory name is based on time stamp and it is created in /opt/ibm/appliance/storage/scratch/apdiag/dump/<timestamp_pid>.

It is the user responsibility to clean up the custom dump directory after use. The default dump directory is cleaned up automatically.

--suffix suffix

Specifies a suffix to append to the name of the .tgz file to make it easier to identify. The name of the .tgz file is timestamp_pid_optionalsuffix.tgz. An example is 20171010_121253_10740_pmr1234.tgz, where pmr1234 is the suffix.

--schemas [schema [schema ...]]

Space-separated list of one or more schema names to use in eligible components.

--dsns [DSN [DSN ...]]

Space-separated list of one or more DSNs for which the information needs to be collected.

--fsns [FSN [FSN ...]]

Space-separated list of one or more FSNs for which the information needs to be collected.

--fabsws [FABSW [FABSW ...]]

Space-separated list of fabric switches for which the information needs to be collected.

--fcsws [FCSW [FCSW ...]]

Space-separated list of Fibre Channel switches for which the information needs to be collected.

--mgtsws [MGTSW [MGTSW ...]]

Space-separated list of management switches for which the information needs to be collected.

--timeout-multiply number

If for any reason commands are timing out prematurely, you can use the --timeout-multiply option to increase in-built timeouts by a factor of the specified argument. The argument must be in the range 1 - 1000 (inclusive). The default value is individual and command dependent.

--estimate-time

Shows estimated time only, without collecting diagnostic data.

--comp-threads number

Specifies the maximum number of threads that an eligible component can use for running commands in parallel. Use 0 to disable threads within a component. The default value is component-dependent with a cap of 10.

This option is useful if the system is overwhelmed by multiple commands. Each plug-in runs in parallel on different nodes. The --comp-threads option does not affect or control that parallelism.

--system-type {Local|Appliance|IDAA}

Specifies system type. This parameter is required only if it is not possible to automatically detect the system type, which results in an error.

--comp-param [COMP:ARG[,ARG...] [COMP:ARG[,ARG...] ...]]

Some components can use extra arguments that are meant for only those components. Such arguments can be passed by using the --comp-param option. If , or : are part of the argument, then you must escape them with \ character.

Following are some examples:

apdiag collect --components database/dart_inspection --force --comp-param database/dart_inspection:'/T /TN mytbl /TSI 123'
  apdiag collect --components database/exfmt --comp-param database/exfmt:'-1 -d bludb'
  apdiag collect --components database/explain --comp-param database/explain:'-stmtfile /tmp/test.sql -database bludb'
  apdiag collect --components database/pd_monitor --comp-param database/pd_monitor:'-locks -wlocks -db bludb'
  apdiag collect --components database/support --comp-param database/support:'-d bludb'
  apdiag collect --components spark/logs_app --comp-param spark/logs_app:'user1,user2'

--skip-secure-data

Specifies that the components that contain secure data are not included in data collection. The log file indicates which components were not included in data collection.

--force

You can use this option if you need to run a command that must be run with caution in a controlled environment. For example, the command might impact performance or the functions of the storage array. Without the --force option, an error message is displayed when you run such potentially harmful commands.