MySQL Bugs: #60927: com_*commit/rollback etc. status variables poorly documented.

Bug #60927	com_*commit/rollback etc. status variables poorly documented.
Submitted:	19 Apr 2011 19:51	Modified:	20 May 2011 6:03
Reporter:	Peter Laursen (Basic Quality Contributor)	Email Updates:
Status:	No Feedback	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	any	OS:	Any
Assigned to:		CPU Architecture:	Any
Tags:	com_commit, com_xa_commit, commit, qc

Description:
I got a surprise! 'com_commit' status variable does not count XA commits. Searching docs for details has absolute no information whether it should or not.

How to repeat:
SHOW SESSION STATUS LIKE 'com_commit'; -- returns 0

-- perform an ordinary transaction 
START TRANSACTION; 
SELECT 1; -- do anything; 
COMMIT;

SHOW SESSION STATUS LIKE 'com_commit'; -- returns 1

-- perform an XA transaction
XA START 'me'; 
SELECT 1; -- do anything; 
XA END 'me';
XA COMMIT 'me' ONE PHASE;

SHOW SESSION STATUS LIKE 'com_commit'; -- returns 1 - and I expected 2.

Suggested fix:
If this is intentional this page should be updated stating that com_commit etc. do not consider XA transactions:
http://dev.mysql.com/doc/refman/5.0/en/server-status-variables.html

(and in general the description on com_' status variables is pretty poor.  There will probably be more examples where a more verbose description is useful.)

"The Com_xxx statement counter variables indicate the number of times each xxx statement has been executed. "

As the message implies, a "XA COMMIT" statement is not the same as a "COMMIT" statement.

"There is one status variable for each type of statement."

There is a Com_xa_commit status variable.

Any suggestions for better wording?

I know there is a Com_xa_commit status variable.  I found out as my *commit count* obviously was not what I expected.

I do not advocate any change in the server (it would be an imcompatible change what should generally be avoided to the extend possible), but just like the docs page http://dev.mysql.com/doc/refman/5.5/en/server-status-variables.html has a more detailed explanation for Com_stmt_xxx status variables I request similar for transaction-related com_xxx status variables - something like "the server maintains status variables for non-xa-transactions and xa-transactions independently. Thus com_commit and com_rollback does not include information about xa transactions" (and the table summary on the page should link)

Such statment in docs would have saved me at least 1 hour.  It is not obvious that "xa commit" is not (some kind of) 'commit' in my opinion.

""the server maintains status variables for non-xa-transactions and xa-transactions independently."

The server maintains status variables for each statement independently. That is, it is not a matter of non-XA and XA, they are simply different statements. So, perhaps, something like: "XA COMMIT and any of the XA statements are not the same statements as a regular COMMIT and the other transaction statements".

> I know there is a Com_xa_commit status variable.  I found out as my *commit count*
> obviously was not what I expected.

Also, just to make it clear, these counts are for statements, not commits (e.g. they are incremented even if nothing is committed). The actual status variable that reflects the count of actual commits is Handler_commit.

So, after this nice discussion, does anybody think there is still anything to document/explain additionally in the manual?

No feedback was provided for this bug for over a month, so it is
being suspended automatically. If you are able to provide the
information that was originally requested, please do so and change
the status of the bug back to "Open".