Docs: Transaction retry guidance and error reference

Created on 25 Sep 2019 · 8Comments · Source: cockroachdb/docs

In https://github.com/cockroachdb/docs/issues/4331 we identified a need to add guidance around transaction retries. Unfortunately, this is insufficient. We need to be able to list all of the major transaction retry types as well as likely causes and most importantly, what to _do_ about these errors.

Recently this came up for a customer in https://github.com/cockroachlabs/support/issues/334. We need a thorough audit of this information.

[ ] ReadWithinUncertaintyIntervalError
[ ] Write Too Old
[ ] Forwarded timestamp (delete range)
[ ] Forwarded timestamp (iso=serializable)
[ ] Possible replay
[ ] Aynsc consensus failure
[ ] Transaction aborted error
[ ] Transaction push error (may not be possible)
[ ] TransactionRetryWithProtoRefreshError

And so on

A-kv-storage A-sql P-1

Source

awoods187

Most helpful comment

Although we won't be able to tackle this docs work for the 20.1 release

I think that's fine as 20.1 is basically right around the corner. Keep up the great work on the docs team!

jasobrown on 24 Mar 2020

👍2

All 8 comments

In addition to reference docs on the error types, we should also show the user where to look in the admin UI to get the list of KV Transaction Restarts (from Metrics > Dashboard: Distributed), which could help when troubleshooting.

(Caveat: I did a quick search for Admin UI docs on the above but did not find, so those may also need updating.)

Screenshot 2019-09-28 12 48 15

rmloveland on 28 Sep 2019

@awoods187 I'd like to bump this ticket. An app team that is quite sophisticated is running into problems with contention, they've read the retry docs, and still keep bumping up against different errors that get returned to them. They are reasonably fine grokking that serializability errors can occur, but without any documentation as to why or what happened, the best they can do is come to the CockroachDB team (a/k/a/ me).

jasobrown on 24 Mar 2020

@jseldess, @rmloveland: I'll echo the same. I see it's labelled P-1. Are we expecting to have this done by 20.1?

irfansharif on 24 Mar 2020

@jasobrown, thank you for bumping this. We value your input deeply. Although we won't be able to tackle this docs work for the 20.1 release, it will be a priority soon after.

@ericharmeling, @rmloveland, let's think this through together, with @awoods187 and others, following the release.