# mco_statrt_register_counter
RT

> Register a new runtime statistics counter with an optional histogram.

### Prototype

        mco_stat_hdl mco_statrt_register_counter(
            /*IN*/ const char *name,
            /*IN*/ mco_bool collect_histogram
        );

### Arguments

`name`
Null-terminated string containing the human-readable name of the counter (e.g., `"api_call_count"`). The string must remain valid for the lifetime of the application.
`collect_histogram`
Flag indicating whether to enable histogram collection for this counter:

- `MCO_YES` — enable histogram (useful for time-based or distribution metrics),
- `MCO_NO` — disable histogram (for simple counters like event counts).

### Description

> This function registers a new custom statistics counter in the global registry. It returns a unique handle that can be used with `mco_statrt_update()`, `mco_statrt_get()`, and other statistics APIs.

> Registration must occur before any database with statistics support is opened. Once a database is initialized, registration is locked and further calls will return `MCO_STAT_INVALID_HANDLE`.

> The counter is stored in the database's statistics memory region and is shared across all connections. If histogram collection is enabled, each update to the counter automatically appends its value to an internal histogram, which can later be retrieved via `mco_stat_get_histogram_source()` and `mco_stat_histogram_get()`.

> Built-in counters (e.g., `MCO_STATRT_COMMIT_COUNT`) are registered automatically; this function is intended for application-specific metrics.

### Return Value

`mco_stat_hdl`
A valid counter handle on success, or `MCO_STAT_INVALID_HANDLE` (0xFF) if registration failed (e.g., called after database initialization or maximum counter limit reached).

### Example

        // Register a custom counter before opening any database
        mco_stat_hdl my_counter = mco_statrt_register_counter("custom_api_calls", MCO_NO);

        if (my_counter != MCO_STAT_INVALID_HANDLE) {
            // Later, in application code:
            mco_statrt_update(my_counter, mco_statrt_op_inc, 0);
            mco_stat_counter_value val = mco_statrt_get(my_counter);
            printf("API calls: %u\n", val);
        }

### Files

Header file:
mco.h
Source file:
mcostat.c
Library:
libmcolib.a