Running scrutinize

You can run scrutinize unqualified by any options:

$ /opt/vertica/bin/scrutinize

When run without options, scrutinize collects a wide range of information from all cluster nodes. It stores the results in a .tar file (VerticaScrutinizeNumericID.tar), with minimal effect on database performance. scrutinize output can help diagnose most issues and yet reduces upload size by omitting fine-grained profiling data.

scrutinize requires temporary disk space where it can collect data before posting the final compressed (.tar) output. How much space depends on variables such as the size of the Vertica log and extracted system tables, as well as user-specified options that limit the scope of information collected. Before scrutinize runs, it verifies that the temporary directory contains at least 1 GB of space; however, the amount that it actually needs can be much higher. By default, scrutinize uses /opt/vertica/tmp as the temporary directory. To avoid problems, you can create a temporary directory with as much space as you think scrutinize is likely to need. Then, specify that scrutinize use this temporary directory through its ‑‑tmpdir option.

You can run scrutinize with one or more options that limit the scope of information that it collects. For example, you can limit the time span of collected data, or collect data only from specific cluster nodes. These options can help you narrow the focus of a collection to information that pertains to a specific issue; they can also reduce output size and improve performance. For more information on these options, see Limiting the Scope of scrutinize Data Collection.

Privileges

You must have database administrator (dbadmin) privileges to run scrutinize. If you run scrutinize as root when the dbadmin user exists, Vertica returns the following error:

[root@host01 ~]# /opt/vertica/bin/scrutinize
Root user is not allowed to use this tool.
Try again as the DB administrative user.

Command Options

Option Description
--auth-upload=url
-A url
 
--url=url
-u url

The --auth-upload and --url options both post scrutinize output to a Vertica support-provided URL, where url specifies the URL or FTP address supplied by Vertica Customer Support for file upload:

  • --auth-upload uses your Vertica license to authenticate with the Vertica server.
  • --url requires url to include a user name and password that is supplied by Vertica Customer Support.

For more information, see Uploading scrutinize Results to Support.

--begin=timestamp
--end=timestamp

 

Used together or separately, the --begin and --end options narrow the time frame of diagnostic data that is collected from vertica.log and editor.log:

  • --begin specifies to collect log data from the specified begin time to the specified end time or log end.
  • --end specifies to collect data from the specified begin time or log start to the specified end time.

Note: These options cannot be combined with the --include_gzlogs option.

You can specify timestamp arguments as offsets from the current time or as absolute times:

  • Offset time format: ' DdHhMmSs'

    For example: '3d2h1m'

  • Absolute time format: 'YYYY-MM-DD HH:MM:SS'

    For example: '2014-01-02 13:29:59'

Examples

$ scrutinize --begin='2014-01-01 00:00:00' --end='2014-01-07 23:59:59'
$ scrutinize --begin='2014-01-01 00:00:00'
$ scrutinize --end='2014-01-07 23:59:59'
$ scrutinize --begin='2014-09-23 00:00:00' --end='1d''
‑‑by‑second
‑‑by‑minute=boolean‑value

Specifies the granularity of information that is collected from Data Collector tables with one of the following options:

  • ‑‑by‑second: Highest level of granularity, specifies to collect data down to the second.
  • ‑‑by‑minute=boolean‑value

    where boolean‑value is set to one of the following:

    • {yes|on}: The default setting, specifies to collect data down to the minute.
    •  {no|off}: The lowest level of granularity, specifies to collect data down to the hour.

For example, the following command collects the last five days of data down to the hour:

$ scrutinize --begin=5d --by-minute=no

This command collects the last hour's data down to the second:

$ scrutinize --begin=1h --by-second
--database=DB
-d DB

Gathers diagnostics for the specified database.

This option is required only if the following conditions are true:

  • Multiple databases are defined on the cluster.
  • More than one database is active, or no database is active.

If you omit this option when these conditions are true, scrutinize returns a message that asks you to specify a database.

Example

$ scrutinize -d VMart
--debug
Increases the amount of information written to the log.
--diag-dump
Limits the collection to database design, system tables, and Data Collector tables. Use this option to collect data to analyze system performance.
--diagnostics
Limits the collection to log file data and output from commands that are run against Vertica and its host system. Use this option to collect data to evaluate unexpected behavior in your Vertica system.
--exclude-tasks=tasks
-X tasks
Excludes one or more of the specified types of tasks from the diagnostics collection, where tasks is a comma-separated list of the task types to exclude. To exclude all default tasks, supply the argument all.

Important: Use --exclude-tasks only in consultation with your Vertica Customer Support contact.

For detailed information, see Limiting the Scope of scrutinize Data Collection.

--get-files file-list
Specifies extra files to collect, including globs, where file-list is a semicolon-delimited list of files.
--help
-h

Outputs all scrutinize options to the console.

--hosts=host-list
-n host-list

Collects diagnostics for the specified hosts, where host-list is a comma-separated list of IP addresses or host names. By default, scrutinize collects diagnostics on all cluster hosts.

To collect data only from the node on which scrutinize was invoked, use the ‑‑local_diags (-s) option.

Example

scrutinize -n host1,host2,host3
scrutinize --hosts=127.0.0.1,host_3,host_1

--include_gzlogs=num‑files
-z num-files

Specifies to include num-files rotated log files (vertica.log*.gz) in the scrutinize output, where num-files can be one of the following:

  • An integer specifies how many of the most recent rotated log files to collect.
  • all specifies to collect all rotated log files.

By default, scrutinize includes one rotated log file.

Note: This option cannot be combined with the ‑‑begin and ‑‑end options.

Example

scrutinize includes the four most recent rotated log files:

$ scrutinize --include_gzlogs 4
--include-ros-info
Includes ROS related information from system tables.
--local_diags
-s

Gathers diagnostics from the host where scrutinize was invoked. By default, scrutinize collects data from all nodes in the cluster.

Tip: To collect data from multiple nodes in the cluster, use the ‑‑hosts (-n) option.

--log-limit limit
Limits how much data is collected from Vertica logs, where limit specifies, in gigabytes, how much log data to collect, starting from the most recent log entry. By default, 1 GB of log data is collected.
--message= message
-m message
Includes a message in the scrutinize output, in the file reason.txt.

Messages are typically included when you upload scrutinize to Vertica Customer Support.

You can set a message several ways:

  • Supply a message string enclosed by double quotation marks ( " ).
  • Supply the path to a file enclosed by double quotation marks. scrutinize includes the file contents in its output file.
  • Use the PROMPT keyword to open an input stream. scrutinize reads input until you type a period (.) on a new line. This closes the input stream, and scrutinize writes the message to the collected output.

For detailed information and examples, see Uploading scrutinize Results to Support.

--no-active-queries
--with-active-queries

Specifies whether to collect diagnostic information from system tables and Data Collector tables about currently running queries. By default, scrutinize always collects active query information (‑‑with-active-queries).

--no-containers
Omits running system table queries from the scrutinize collection. Omitting these queries can help reduce scrutinize run time.
--no-package-info
Excludes information collected about Vertica add-on packages Like Vertica Kafka.
--output_dir=path
-o path

Redirects output to a location that is not the current directory. By default, scrutinize places its output in the current directory.

Example

$ scrutinize --output_dir="/my_diagnostics/"
--password='password'
-P 'password'

Specifies the database password. scrutinize supports VSQL_PASSWORD.

Omitting this argument on a password-protected database returns a warning. Enclose the password with single quotation marks ( ' ) to protect passwords with special characters.

Use this option if the Vertica administrator account (default dbadmin) has password authentication.

Example

$ scrutinize -P '@passWord**'

$ scrutinize --password='$password1*'
--tasks=tasks
-T tasks

Specifies that scrutinize gather diagnostics on one or more specified tasks, as specified in a file or JSON list.

Note: Use this option only in consultation with Vertica Customer Support.

--type=type
-t type

Specifies the type of diagnostics collection to perform, where type can be set to one of the following arguments:

  • profiling: Gather profiling data.
  • context: Gather summary information.
--tmpdir=path

Specifies the temporary directory to use on all nodes. By default, the temporary directory is in the Administration Tools directory /tmp. Use this option to ensure that the temporary directory has enough free space so scrutinize can complete execution.

The following requirements apply:

  • The temporary directory must have at least 1 GB of free space.
  • You must have write permission to the directory.
--user=username
-U username

Specifies the dbadmin user name. By default, scrutinize uses the user name of the invoking user.

--version
Displays the version number of the Vertica server and the scrutinize version number.
--vsql-off
-v

Excludes Query and SystemTable tasks, which are used to connect to the database. This option can help you deal with problems that occur during an upgrade, and is typically used in the following cases:

  • Vertica is running but is slow to respond.
  • You haven't created a database but need help troubleshooting other cluster issues.
-W
--prompt-password

scrutinize displays a DB Password prompt at the command line, where users must enter their database passwords.