Storage Manager Statistics
[SHORE Storage Manager Application Programming Interface (SSM API)]

Collaboration diagram for Storage Manager Statistics:

---

Detailed Description

The storage manager contains functions to gather statistics that it collects. These are mostly counters and are described here.

Volumes can be analyzed to gather usage statistics. See ss_m::get_du_statistics and ss_m::get_volume_meta_stats.

Bulk-loading indexes gathers statistics about the bulk-load activity. See ss_m::bulkld_index and ss_m::bulkld_md_index.

Note:

A Perl script facilitates modifying the statistics gathered by generating much of the supporting code, including structure definitions and output operators. The server-writer can generate her own sets of statistics using the same Perl tool. See STATS for more information about how these statistics sets are built.

The storage manager API allows a server to gather statistics on a per-transaction basis or on a global basis. These counters are not segregated by the semantics of the counters. Rather, they are segregated by the thread that performed the action being measured. In other words, an action is attributed to a transaction if it was performed by a thread while attached to that transaction. This means that some actions, such as writing pages to disk, might not be attributable to a transaction even though they are in some sense logically associated with that transaction. If the write is performed by a page writer (background thread), it will show up in the global statistics but not in any per-transaction statistics. On the other hand, if a write is performed by ss_m::set_store_property (which flushes to disk all pages for the store thus changed) it will be attributed to the transaction.

All statistics are collected on a per-smthread_t basis (thus avoiding expensive atomic updates on a per-counter basis). Each smthread has its own local sm_stats_info_t structure for these statistics. Any time this structure is cleared, its contents are added to a single global statistics structure (protected by a mutex) before it is cleared. The clearing happens in two circumstances:

• when an smthread_t is destroyed (in its destructor)
• when an attached instrumented transaction collects the statistics from the thread (see below).

Thus, the single global statistics structure's contents reflect the activities of finished threads and of instrumented transactions' collected statistics, and all other activities are reflected in per-thread statistics structures.

A value-added server may collect the global statistics with the ss_m::gather_stats method. This method first adds together all the per-thread statistics, adds in the global statistics, and returns. The global statistics cannot be reset, and, indeed, they survive the storage manager so that they can be gathered after the storage manager shuts down. This means that to determine incremental statistics, the value-added server has to keep the prior copy of statistics and diff the current statistics from the prior statistics. The sm_stats_info_t has a difference operator to make this easy.

Attention:

Gathering the per-thread statistics from running threads is not atomic; in other words, if threads are updating their counters while the gathering of their counters is going on, some counts may be missed (become stale). (In any case, they will be stale soon after the statistics are gathered.)

A transaction must be instrumented to collect its statistics.

Instrumenting a transaction consists in allocating a structure in which to store the collected statistics, and passing in that structure to the storage manager using using the variants of begin_xct, commit_xct, etc that take an argument of this type.

When a transaction is detached from a thread, the statistics it gathered up to that point by the thread are added to the per-transaction statistics, and the thread statistics are cleared so they don't get over-counted.

A server may gather the per-transaction statistics for the attached running transaction with ss_m::gather_xct_stats.

A server may choose to reset the per-transaction statistics when it gathers them; this facilitates gathering incremental statistics. These counters aren't lost to the world, since their values were added to the global statistics before they were gathered in the first place.

Attention:

The per-transaction statistics structure is not protected against concurrently-attached threads, so its values are best collected and reset when the server knows that only one thread is attached to the transaction when making the call.

Functions
static rc_t	ss_m::gather_stats (sm_stats_info_t &stats)
	Get a copy of the global statistics.

---

Function Documentation

static rc_t ss_m::gather_stats

(

sm_stats_info_t &

stats

)

[static, inherited]

Get a copy of the global statistics.

Parameters:

[out]

stats

A pre-allocated structure.

Examples:

create_rec.cpp, and log_exceed.cpp.

---