[MB-5304] stats for key are not defined in documentation, many stats are not defined Created: 15/May/12  Updated: 03/Jul/12  Resolved: 04/Jun/12

Status: Resolved
Project: Couchbase Server
Component/s: documentation
Affects Version/s: 1.7.2, 1.8.0, 2.0-developer-preview-4
Fix Version/s: 2.0-beta
Security Level: Public

Type: Bug Priority: Blocker
Reporter: Matt Ingenthron Assignee: Mike Wiederhold
Resolution: Fixed Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


To work through the implementation of OBSERVE[1], we were looking for the details on STATS KEY, only to find it's not documented. It exists in the server implementation, but it's not even in the stats.org[2] associated with the code repository.

This statistic and all others that are public interface should be documented in the manual.

Implementation of OBSERVE operations in the various client libraries will need this information.

1. http://www.couchbase.com/wiki/display/couchbase/Observe
2. https://github.com/couchbase/ep-engine/blob/master/docs/stats.org

Comment by Dipti Borkar [ 15/May/12 ]
Chiyoung, can you provide details on stats key so that documentation can be added?
Comment by Chiyoung Seo [ 24/May/12 ]

We should provide the "stats key" documentation for the client library team, so that they can refer to this documentation to implement OBSERVE command in the client libraries.
Comment by Chiyoung Seo [ 01/Jun/12 ]
Assign it to Mike as he was mainly involved in the initial OBSERVE design.
Comment by Thuan Nguyen [ 02/Jun/12 ]
Integrated in github-ep-engine-2-0 #301 (See [http://qa.hq.northscale.net/job/github-ep-engine-2-0/301/])
    MB-5304: Document stats key/vkey in stats.org (Revision df4dd0f9aa65b69a36a304ca76a8389090bd3297)

     Result = SUCCESS
Mike Wiederhold :
Files :
* docs/stats.org
Comment by Matt Ingenthron [ 04/Jun/12 ]
Documentation mixes stats key and stats vkey, though the return values for each need to be understood. Also, see MB-5435. This documentation appears to be wrong with respect to the key valid field, or there's some subtlety that is not explained by the table.
Comment by Mike Wiederhold [ 04/Jun/12 ]
Stats key and vkey return the same data. The only difference is the key_valid field returned by stats vkey. I have marked each stat with the command that returns it in the column on the left. I made a few minor wording changes to the documentation, but I disagree that the documentation is wrong. Please provide an explanation of what is confusing or contact me over Skype to discuss anything you think is incorrect.

** Stats Key and Vkey
| key_cas | The keys current cas value |KV|
| key_data_age | How long the key has waited for its |KV|
| | value to be persisted (0 if clean) |KV|
| key_exptime | Expiration time from the epoch |KV|
| key_flags | Flags for this key |KV|
| key_is_dirty | If the value is not yet persisted |KV|
| key_last_modified_time | Last updated time |KV|
| key_valid | See description below | V|
| key_vb_state | The vbucket state of this key |KV|

=key_valid= can have the following responses:

this_is_a_bug - Some case we didn't take care of.
dirty - The value in memory has not been persisted yet.
length_mismatch - Data length in memory doesn't match the data length on disk.
data_mismatch - The data in memory doesn't match the data on disk.
flags_mismatch - The flags in memory don't match the flags on disk.
valid - The data on disk and in memory match
ram_but_not_disk - The value doesn't exist yet on disk.
item_deleted - The item has been deleted.
Comment by Sergey Avseyev [ 04/Jun/12 ]
What is KV in the last column? I think it should be KV instead of V for key_valid
Comment by Mike Wiederhold [ 04/Jun/12 ]
K = Key
V = VKey

And key_valid is not included in stats key.
Comment by Sergey Avseyev [ 04/Jun/12 ]
What does mean "is not included in stats"? I can have key "x" with value "test" in the default bucket on couchbase 2.0. Here is the output of the command line tools:

    $ cbc cat x
    "x" Size 5 Flags 0x0 CAS 0x69cf70ff8de90000
    $ curl -s http://localhost:8091/pools/default/buckets/default | vbuckettool - x
    key: x master: vBucketId: 220 couchApiBase: replicas:
    $ cbc stats "key x 220" key_is_dirty 0 key_exptime 0 key_flags 0 key_cas 256796085243753 key_dirtied 0 key_data_age 0 key_last_modification_time 1338826758
    $ cbc stats "vkey x 220" key_is_dirty 0 key_exptime 0 key_flags 0 key_cas 256796085243753 key_dirtied 0 key_data_age 0 key_last_modification_time 1338826854 key_valid valid

You can see the last line says there is key "key_valid" and value "valid"
Comment by Sergey Avseyev [ 04/Jun/12 ]
:) I see now sorry. VKey. So I have no objections any more
Comment by Mike Wiederhold [ 04/Jun/12 ]
Sergey appears to be okay with the documentation. PLease reopen if any other issues come up.
Comment by Matt Ingenthron [ 04/Jun/12 ]
My confusion too was based on the last column. Could we clarify that (if not done already)? I thought you were saying whether or not each stat returned a key and value for the stat.
Generated at Thu Apr 24 09:14:29 CDT 2014 using JIRA 5.2.4#845-sha1:c9f4cc41abe72fb236945343a1f485c2c844dac9.