Note in docs: As of pt-table-checksum 2.2.5, skipped chunks cause a non-zero exit status. Also report skipped chunks due to lock wait timeout and killed query like other skipped chunks. Enhance explanation of SKIPPED column.

bin/pt-table-checksum

@@ -10541,9 +10541,15 @@ sub exec_nibble {
          ) {
             # These errors/warnings are not fatal but only cause this
             # nibble to be skipped.
-            if ( $o->get('quiet') < 2 ) {
+            my $err = $error =~ /Lock wait timeout exceeded/
-               warn "$error\n";
+                    ? 'lock_wait_timeout'
+                    : 'query_interrupted';
+            if ( !$tbl->{warned}->{$err}++ && $o->get('quiet') < 2 ) {
+               my $msg = "Skipping chunk " . ($nibble_iter->nibble_number() || '?')
+                       . " of $tbl->{db}.$tbl->{tbl} because $error.\n";
+               warn ts($msg);
             }
+            $exit_status |= $PTC_EXIT_STATUS{SKIP_CHUNK};
             return;  # skip this nibble
          }
 
@@ -11528,8 +11534,15 @@ The number of chunks into which the table was divided.
 
 =item SKIPPED
 
-The number of chunks that were skipped due to errors or warnings, or because
+The number of chunks that were skipped due one or more of these problems:
-they were oversized.
+
+   * MySQL not using the L<"--chunk-index">
+   * MySQL not using the full chunk index (L<"--[no]check-plan">)
+   * Chunk size is greater than L<"--chunk-size"> * L<"--chunk-size-limit">
+   * Lock wait timeout exceeded (L<"--retries")
+   * Checksum query killed (L<"--retries">)
+
+As of pt-table-checksum 2.2.5, skipped chunks cause a non-zero L<"EXIT STATUS">.
 
 =item TIME
 
@@ -11621,6 +11634,10 @@ If any flag is set, the exit status will be non-zero.  Use the bitwise C<AND>
 operation to check for a particular flag.  For example, if C<$exit_status & 16>
 is true, then at least one diff was found.
 
+As of pt-table-checksum 2.2.5, skipped chunks cause a non-zero exit status.
+An exit status of zero or 32 is equivalent to a zero exit status with skipped
+chunks in previous versions of the tool.
+
 =head1 OPTIONS
 
 This tool accepts additional command-line arguments.  Refer to the

lib/PerconaTest.pm

@@ -730,6 +730,10 @@ sub normalize_checksum_results {
    printf $fh $output;
    close $fh;
    my $normal_output = `cat $tmp_file | awk '/^[0-9 ]/ {print \$2 " " \$3 " " \$4 " " \$5 " " \$6 " " \$8} /^[A-Z]/ {print \$0}'`;
+   if ( wantarray ) {
+      my $original_output = `cat $tmp_file`;
+      return $normal_output, $original_output;
+   }
    `rm $tmp_file >/dev/null`;
    return $normal_output;
 }

t/pt-table-checksum/basics.t

@@ -123,7 +123,7 @@ $exit_status = pt_table_checksum::main(@args,
 
 is(
    $exit_status,
-   512,  # = TABLE_DIFF but nothing else; https://bugs.launchpad.net/percona-toolkit/+bug/944051
+   16,  # = TABLE_DIFF but nothing else; https://bugs.launchpad.net/percona-toolkit/+bug/944051
    "--replicate-check on by default, detects diff"
 );
 
@@ -297,7 +297,7 @@ is_deeply(
 
 is(
    $exit_status,
-   2048,
+   64,  # SKIP_TABLE
    "Non-zero exit status"
 );
 

t/pt-table-checksum/chunk_index.t

@@ -171,7 +171,7 @@ $output = output(sub {
 
 is(
    $exit_status,
-   1024,
+   32,  # SKIP_CHUNK
    "Bad key_len chunks are not errors"
 ) or diag($output);
 

t/pt-table-checksum/error_handling.t

@@ -72,15 +72,17 @@ $master_dbh->do('begin');
 $master_dbh->do('select * from city for update');
 
 $output = output(
-   sub { pt_table_checksum::main(@args, qw(-t sakila.city)) },
+   sub { $exit_status = pt_table_checksum::main(@args, qw(-t sakila.city)) },
    stderr => 1,
-   trf    => sub { return PerconaTest::normalize_checksum_results(@_) },
 );
 
+my $original_output;
+($output, $original_output) = PerconaTest::normalize_checksum_results($output);
+
 like(
-   $output,
+   $original_output,
    qr/Lock wait timeout exceeded/,
-   "Catches lock wait timeout"
+   "Warns about lock wait timeout"
 );
 
 like(
@@ -89,6 +91,12 @@ like(
    "Skips chunk that times out"
 );
 
+is(
+   $exit_status,
+   32,
+   "Exit 32 (SKIP_CHUNK)"
+);
+
 # Lock wait timeout for sandbox servers is 3s, so sleep 4 then commit
 # to release the lock.  That should allow the checksum query to finish.
 my ($id) = $master_dbh->selectrow_array('select connection_id()');
@@ -153,7 +161,7 @@ like(
 
 is(
    $exit_status,
-   2048,  # https://bugs.launchpad.net/percona-toolkit/+bug/944051
+   64,  # SKIP_TABLE
    "Non-zero exit status (bug 1009510)"
 );
 

t/pt-table-checksum/standard_options.t

@@ -125,8 +125,8 @@ like(
 
 is(
    $exit_status,
-   4,
+   2,
-   "Exit status 4 if if PID file already exist (bug 944051)"
+   "Exit status 2 if if PID file already exist (bug 944051)"
 );
 
 diag(`rm -rf $pid_file >/dev/null 2>&1`);