scrutinize

Runs the scrutinize utility to collect diagnostic information about a database.

Runs the scrutinize utility to collect diagnostic information about a database. The cusotmer support team might request you to run this utility when resolving a case.

By default, diagnostics are stored in a /tmp/scrutinize/VerticaScrutinize.timestamp.tar.

For details, see Running scrutinize.

Note

To run VCluster CLI commands from a different database node, use vcluster manage_config recover to create or refresh the vertica_cluster.yaml file on that host.

Syntax

vcluster scrutinize options

Required options

{ -c | --config } string: The path to the configuration file. If a configuration file is present in the default location (automatically generated by create_db), you do not need to specify this option.
Default: /opt/vertica/config/vertica_cluster.yaml

Options

--cert-file string: The absolute path to the certificate file. If you specify this option, you must also specify --key-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--db-slow: This is used when the database is very slow or when vsql is not responsive. This is equivalent to --type basic --vsql-off --log-limit 3 --log_age_hours 24 --no-active-queries --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--db-user string: The username of a database user.
--exclude-active-queries: Exclude information affected by currently running queries.
--exclude-containers: Excludes information in system tables that can scale with the number of ROS containers.
--external-tables: Debugging prest for external tables, database in Eon mode, and data lake. This is equivalent to --type context --external_table_details --log-limit 5 --log_age_hours 24 --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.

{ -h | --help }: Prints help text.

--hot_deep: Second pass deep diagnostics on identified problem nodes. This is equivalent to --type context --log-limit 2 --log_age_hours 12 --no-containers --with-active-queries --save-system-table-as-parquet --hosts <node list>. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--hot_min: Fastest possible diagnostic collection for very large clusters during P1 incidents. This is equivalent to --diagnostics --log-limit 1 --log_age_hours 6 --no-containers --no-active-queries --ignore-unreachable-nodes. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--hot_sample: This is used when full cluster collection is too slow. Only selected nodes are scanned. This is equivalent to --diagnostics --log-limit 1 --log_age_hours 6 --no-containers --no-active-queries --hosts <node list>. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--incident_min: Incident-minimal preset. logs + basic system outputs; avoids DB-heavy queries. This is equivalent to scrutinize --type basic --diagnostics --log-limit 2 --log_age_hours 12 --no-active-queries --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--incident_std: Incident-standard preset. support-friendly with controlled size. It includes system tables and some DATA_COLLECTOR tables. This is equivalent to --type context -X MemoryReportLog --log-limit 5 --log_age_hours 24 --by-minute=yes --no-containers --with-active-queries --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--include-external-table-details: Include information about external tables. This option is computationally expensive.
--include-ros: Include information about ROS containers.
--include-udx-details: Include information describing all UDX functions. This option can be computationally expensive for Eon Mode databases.

--ipv6: Specifies if the hosts use IPv6 addresses.
Default: IPv4

--kafka: Focused diagnostic bundle for debugging Kafka pipelines. This is equivalent to --type context -X UdxLog,MemoryReportLog --log-limit 3 --log_age_hours 24 --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.

--key-file string: Path to the key file. If you specify this option, you must also specify --cert-file. You should only use --cert-file and --key-file if you have configured the Node Management Agent (NMA) to use custom certificates.

--log-age-hours int: The maximum age, in hours, of archived database log files to collect.
Default: 24
--log-age-newest-time YYYY-MM-DD HH [+|-XX]: Timestamp of the minimum age of archived database log files to collect with an optional UTC hour offset [+|-XX].
--log-age-oldest-time YYYY-MM-DD HH [+|-XX]: Timestamp of the maximum age of archived database log files to collect with an optional UTC hour offset [+/-XX].

{ -l | --log-path } string: The absolute path for debug logs.
Default: /opt/vertica/log/vcluster.log

--log-time-range="START" ["END"]: Collects logs only within a specific time range to reduce unnecessary data collection. This is equivalent to --udx --log-time-range="2026-03-01 10:00:00" "2026-03-01 11:00:00" -o /tmp/output. The format is "YYYY-MM-DD HH:MM:SS" ["YYYY-MM-DD HH:MM:SS"].

{ -p | --password } string: The database password.

--password-file string: The absolute path to a file containing the database password.
If you pass a dash(-) (that is, `--password-file -`), the password is read from STDIN.

Important
Your database password cannot include single quotes.

--perf: Performance diagnostics preset. Analyze query performance, system load, and runtime behavior while controlling the bundle size. This is equivalent to --type profiling --log-limit 5 --log_age_hours 24 --with-active-queries --by-minute=yes --no-containers --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--perf_bysec: Performance diagnostics with per-second DC data for spike correlation. This is equivalent to scrutinize --type profiling --log-limit 5 --log_age_hours 12 --by-second --no-containers. Explicitly passed options take precedence over the default value passed in the wrapper argument.

--read-password-from-prompt: Prompts the user to enter the password.

--skip-collect-libraries: Skips gathering linked and catalog-shared libraries.
--split=SIZE: Splits large Scrutinize output tar files into smaller chunks for easier handling and reliable uploads. Using this option disables automatic S3 upload. SIZE must include an unit: B (bytes), M (MB), or G (GB). This is equivalent to --perf --split=2G -o /tmp/output. An example is --split 2G.
--storage: Analyze disk usage, ROS containers, and projection layout. This is equivalent to --type context -X Query --include-ros-info --no-active-queries --log-limit 3 --log_age_hours 24 --save-system-table-as-parquet. Explicitly passed options take precedence over the default value passed in the wrapper argument.
--tarball-name string: Name of the generated .tar.
Default: VerticaScrutinize.timestamp.tar
--udx: Focused diagnostic bundle for debugging user-defined extensions (UDx). This is equivalent to --type basic -X DC,SystemTable,CatalogObject,Query,KafkaLog,MemoryReportLog --log-limit 3 --log_age_hours 24. Explicitly passed options take precedence over the default value passed in the wrapper argument.

--verbose: Shows the details of VCluster run in the console.

Examples

Runs scrutinize on all nodes in the database:

$ vcluster scrutinize --db-name vertica_db --db-user dbadmin \
  --password testpassword --config /opt/vertica/config/vertica_cluster.yaml