Lightweight::SqlStatistics Class Reference

#include <SqlStatistics.hpp>

Public Member Functions
	SqlStatistics () noexcept=default
	Constructs a collector with every counter at zero.
	SqlStatistics (SqlStatistics const &)=delete
SqlStatistics &	operator= (SqlStatistics const &)=delete
	SqlStatistics (SqlStatistics &&)=delete
SqlStatistics &	operator= (SqlStatistics &&)=delete
LIGHTWEIGHT_API void	RecordOperation (SqlStatisticsOperation operation, std::chrono::microseconds duration, bool failed) noexcept
LIGHTWEIGHT_API void	RecordRetry (SqlStatisticsOperation operation) noexcept
LIGHTWEIGHT_API void	RecordRowsFetched (std::uint64_t rowCount, bool wasBlockFetch) noexcept
LIGHTWEIGHT_API void	RecordConnectionOpened () noexcept
	Records a connection being opened.
LIGHTWEIGHT_API void	RecordConnectionClosed () noexcept
	Records a connection being closed.
LIGHTWEIGHT_API void	RecordPoolAcquire (std::chrono::microseconds waitDuration, bool reused, bool waited) noexcept
LIGHTWEIGHT_API void	RecordPoolRelease (bool discarded) noexcept
LIGHTWEIGHT_API void	RecordPoolOccupancy (std::uint64_t idle, std::uint64_t checkedOut) noexcept
LIGHTWEIGHT_API SqlStatisticsSnapshot	Snapshot () const noexcept
LIGHTWEIGHT_API void	Reset () noexcept

Static Public Member Functions
static LIGHTWEIGHT_API SqlStatistics &	Instance () noexcept
static LIGHTWEIGHT_API void	Enable () noexcept
static LIGHTWEIGHT_API void	Disable () noexcept
static LIGHTWEIGHT_API bool	IsEnabled () noexcept

Detailed Description

Thread-safe, lock-free aggregator of SQL execution and pool statistics.

The collector is always compiled in, but only populated while collection is runtime-enabled (see Enable, Disable, IsEnabled) — OFF by default. While disabled, every recording method is still callable but does nothing, so downstream code never needs to guard a call site. Toggling is orthogonal to Reset : disabling and re-enabling preserves whatever was already collected.

All recording methods use relaxed atomics: they never block, never allocate, and are safe to call from any thread. See SqlStatisticsSnapshot for the consistency caveat that buys.

Lightweight::SqlStatistics::Enable();
// ... run some workload ...
auto const stats = Lightweight::SqlStatistics::Instance().Snapshot();
std::println("executes: {}, p99: {}us",
             stats[Lightweight::SqlStatisticsOperation::Execute].Total(),
             stats[Lightweight::SqlStatisticsOperation::Execute].latency.PercentileMicroseconds(0.99));

See also

SqlStatisticsSnapshot, docs/statistics.md

Definition at line 267 of file SqlStatistics.hpp.

Member Function Documentation

Instance()

static LIGHTWEIGHT_API SqlStatistics & Lightweight::SqlStatistics::Instance ( )

staticnoexcept

Retrieves the process-wide collector that the library's own instrumentation records into.

Returns

A reference to the singleton collector.

RecordOperation()

LIGHTWEIGHT_API void Lightweight::SqlStatistics::RecordOperation ( SqlStatisticsOperation  operation, std::chrono::microseconds  duration, bool  failed  )

noexcept

Records one completed operation.

Parameters

operation	The operation class.
duration	How long the operation took.
failed	Whether the operation raised an ODBC error.

RecordRetry()

LIGHTWEIGHT_API void Lightweight::SqlStatistics::RecordRetry ( SqlStatisticsOperation  operation )

noexcept

Records that an operation was transparently retried.

Parameters

operation

The operation class being retried.

RecordRowsFetched()

LIGHTWEIGHT_API void Lightweight::SqlStatistics::RecordRowsFetched ( std::uint64_t  rowCount, bool  wasBlockFetch  )

noexcept

Records rows produced by a fetch.

Parameters

rowCount	Number of rows materialized.
wasBlockFetch	Whether the rows came from a single block-prefetch round-trip.

RecordPoolAcquire()

LIGHTWEIGHT_API void Lightweight::SqlStatistics::RecordPoolAcquire ( std::chrono::microseconds  waitDuration, bool  reused, bool  waited  )

noexcept

Records a connection acquisition from a pool.

Parameters

waitDuration	Time spent waiting for the connection; zero when it was available immediately.
reused	Whether an already-open connection was handed out rather than a fresh one created.
waited	Whether the caller actually had to block or park.

RecordPoolRelease()

LIGHTWEIGHT_API void Lightweight::SqlStatistics::RecordPoolRelease ( bool  discarded )

noexcept

Records a connection being returned to a pool.

Parameters

discarded

Whether the connection was destroyed instead of idled (pool over capacity).

RecordPoolOccupancy()

LIGHTWEIGHT_API void Lightweight::SqlStatistics::RecordPoolOccupancy ( std::uint64_t  idle, std::uint64_t  checkedOut  )

noexcept

Records the pool's current occupancy. Called whenever the pool's composition changes.

Parameters

idle	Connections currently idle.
checkedOut	Connections currently checked out.

Snapshot()

LIGHTWEIGHT_API SqlStatisticsSnapshot Lightweight::SqlStatistics::Snapshot ( ) const

noexcept

Retrieves a point-in-time copy of every counter.

Returns

The snapshot; all-zero while collection has never been enabled (see Enable).

Reset()

LIGHTWEIGHT_API void Lightweight::SqlStatistics::Reset ( )

noexcept

Resets every counter back to zero. Intended for tests and for exporters that report deltas. Orthogonal to Enable / Disable : resetting does not change whether collection runs.

Enable()

static LIGHTWEIGHT_API void Lightweight::SqlStatistics::Enable ( )

staticnoexcept

Turns statistics collection on. Safe to call from any thread, at any point in the process lifetime; takes effect for every subsequent recording call. Counters already collected are left untouched.

Disable()

static LIGHTWEIGHT_API void Lightweight::SqlStatistics::Disable ( )

staticnoexcept

Turns statistics collection off. Recording methods remain callable but become no-ops; counters already collected are left untouched and continue to read back from Snapshot.

IsEnabled()

static LIGHTWEIGHT_API bool Lightweight::SqlStatistics::IsEnabled ( )

staticnoexcept

Indicates whether statistics collection is currently turned on.

Returns

true after Enable (and before a subsequent Disable); false otherwise, including at process start.

---

The documentation for this class was generated from the following file:

• Lightweight/SqlStatistics.hpp