StormByte-Database 3.0.0
C++26 database module of the StormByte suite
Loading...
Searching...
No Matches
telemetry.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Database.
5 *
6 * StormByte-Database original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Database source in this
20 * repository. They do not cover other StormByte modules or any third-party
21 * material shipped with this repository (including everything under
22 * thirdparty/, and in particular the bundled StormByte-Logger tree and
23 * the PostgreSQL, MariaDB and SQLite trees), which remain under their own
24 * licenses.
25 *
26 * Neither license grants any patent rights. Any patent licenses required
27 * to use this software or third-party components must be obtained separately
28 * from the patent holders.
29 *
30 * StormByte-Database is distributed in the hope that it will be useful,
31 * but WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 * GNU Lesser General Public License for more details.
34 *
35 * You should have received a copy of the GNU Lesser General Public License
36 * version 3 along with StormByte-Database. If not, see
37 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
38 *
39 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
40 */
41
42#pragma once
43
45#include <StormByte/safe/atomic.hxx>
46#include <StormByte/safe/pointers.hxx>
47#include <StormByte/safe/string.hxx>
48#include <StormByte/telemetry.hxx>
49
50#include <array>
51#include <chrono>
52#include <cstddef>
53#include <cstdint>
54#include <limits>
55#include <string>
56
61namespace StormByte {
66 namespace Database {
83
100
106 std::uint64_t Attempts{};
107 std::uint64_t Successes{};
108 std::uint64_t Failures{};
109 std::uint64_t TotalNanoseconds{};
110 std::uint64_t MinimumNanoseconds{};
111 std::uint64_t MaximumNanoseconds{};
112
117 std::uint64_t MeanNanoseconds() const noexcept {
118 return Attempts == 0 ? 0 : TotalNanoseconds / Attempts;
119 }
120 };
121
131 public:
137 public:
144
149
154
160 void Complete(bool success, std::uint64_t rows_returned = 0) noexcept;
161
165 ~OperationScope() noexcept;
166
167 private:
168 StormByte::Safe::Shared<Telemetry> m_telemetry;
169 Operation m_operation;
170 StormByte::Clock::Sample m_sample;
171 std::uint64_t m_rows_returned;
172 bool m_success;
173 bool m_completed;
174 };
175
179 virtual ~Telemetry() noexcept;
180
185
191 OperationMetrics Metrics(Operation operation) const noexcept;
192
197 std::uint64_t RowsReturned() const noexcept;
198
204 std::uint64_t Events(BackendEvent event) const noexcept;
205
210 virtual operator StormByte::Safe::String() const override;
211
216 STORMBYTE_FORCE_INLINE operator std::string() const {
217 return static_cast<std::string>(static_cast<StormByte::Safe::String>(*this));
218 }
219
220 protected:
221 Telemetry(const Telemetry&) = delete;
222 Telemetry(Telemetry&&) = delete;
223 Telemetry& operator=(const Telemetry&) = delete;
225
230 virtual void RecordEvent(BackendEvent event) noexcept;
231
237 void RecordEvents(BackendEvent event, std::uint64_t count) noexcept;
238
239 private:
240 friend class Database;
241 friend class PreparedSTMT;
242 friend class OperationScope;
243
248 struct STORMBYTE_DATABASE_PRIVATE Counter {
251 StormByte::Safe::Atomic<std::uint64_t> minimum_nanoseconds{std::numeric_limits<std::uint64_t>::max()};
252 StormByte::Safe::Atomic<std::uint64_t> maximum_nanoseconds{0};
253 };
254
262 void RecordOperation(Operation operation, bool success, std::chrono::nanoseconds elapsed, std::uint64_t rows_returned) noexcept;
263
264 std::array<Counter, static_cast<std::size_t>(Operation::Count)> m_operations;
265 std::array<StormByte::Safe::Atomic<std::uint64_t>, static_cast<std::size_t>(BackendEvent::Count)> m_events;
266 StormByte::Safe::Atomic<std::uint64_t> m_rows_returned;
267 };
268 }
269}
270
272STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Database::OperationMetrics);
273
275STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Database::Telemetry);
276
Records one operation and its elapsed time on destruction.
Definition telemetry.hxx:136
OperationScope(StormByte::Safe::Shared< Telemetry > telemetry, Operation operation) noexcept
OperationScope(OperationScope &&)=delete
Move constructor is deleted.
OperationScope(const OperationScope &)=delete
Copy constructor is deleted.
void Complete(bool success, std::uint64_t rows_returned=0) noexcept
Record the result and optional returned row count.
friend class OperationScope
Definition telemetry.hxx:242
virtual void RecordEvent(BackendEvent event) noexcept
Telemetry & operator=(const Telemetry &)=delete
Copy assignment is disabled.
virtual operator StormByte::Safe::String() const override
Telemetry(Telemetry &&)=delete
Moving counters is disabled.
Telemetry(const Telemetry &)=delete
Copying counters is disabled.
Telemetry & operator=(Telemetry &&)=delete
Move assignment is disabled.
friend class PreparedSTMT
Definition telemetry.hxx:241
friend class Database
Definition telemetry.hxx:240
std::uint64_t RowsReturned() const noexcept
Total rows successfully returned by Query and prepared statements.
OperationMetrics Metrics(Operation operation) const noexcept
Obtain a thread-safe metrics snapshot for an operation.
void RecordEvents(BackendEvent event, std::uint64_t count) noexcept
Add a known number of occurrences for one backend event.
Telemetry()
Construct zeroed counters.
std::uint64_t Events(BackendEvent event) const noexcept
Number of backend events in a shared category.
class Clock & Clock(std::string_view name)
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Logger::Exception)
Database module of the StormByte suite.
BackendEvent
Shared error and warning categories for backend-specific telemetry.
Definition telemetry.hxx:88
@ Warning
Non-fatal warning reported by a backend.
Definition telemetry.hxx:89
@ Serialization
Transaction serialization conflict.
Definition telemetry.hxx:94
@ LockTimeout
Lock wait timed out.
Definition telemetry.hxx:96
@ Io
Storage or transport I/O failure.
Definition telemetry.hxx:92
@ Constraint
Constraint violation.
Definition telemetry.hxx:91
@ Other
Backend failure without a narrower category.
Definition telemetry.hxx:97
@ Deadlock
Deadlock victim or equivalent conflict.
Definition telemetry.hxx:95
@ Connection
Connection or protocol failure.
Definition telemetry.hxx:93
@ Busy
Busy, locked, or lock-timeout condition.
Definition telemetry.hxx:90
Operation
Database operation categories measured by telemetry.
Definition telemetry.hxx:71
@ RollbackTransaction
Explicit and automatic rollback attempts.
Definition telemetry.hxx:80
@ CommitTransaction
Transaction commit attempts.
Definition telemetry.hxx:79
@ Disconnect
Disconnect calls.
Definition telemetry.hxx:73
@ Connect
Connection attempts.
Definition telemetry.hxx:72
@ PreparedStatement
Prepared-statement execution attempts.
Definition telemetry.hxx:77
@ Query
Queries that return rows.
Definition telemetry.hxx:74
@ SilentQuery
Queries that return only success or failure.
Definition telemetry.hxx:75
@ BeginTransaction
Transaction begin attempts.
Definition telemetry.hxx:78
@ PrepareStatement
Prepared-statement registration attempts.
Definition telemetry.hxx:76
@ Count
Number of operation categories.
Definition telemetry.hxx:81
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Immutable view of cumulative metrics for one operation category.
Definition telemetry.hxx:105
std::uint64_t Attempts
Number of recorded attempts.
Definition telemetry.hxx:106
std::uint64_t Failures
Number of failed attempts.
Definition telemetry.hxx:108
std::uint64_t MeanNanoseconds() const noexcept
Mean duration across attempts.
Definition telemetry.hxx:117
std::uint64_t MaximumNanoseconds
Maximum measured duration.
Definition telemetry.hxx:111
std::uint64_t Successes
Number of successful attempts.
Definition telemetry.hxx:107
std::uint64_t TotalNanoseconds
Sum of measured durations.
Definition telemetry.hxx:109
std::uint64_t MinimumNanoseconds
Minimum measured duration, or zero when empty.
Definition telemetry.hxx:110
#define STORMBYTE_DATABASE_PRIVATE
Definition visibility.h:57
#define STORMBYTE_DATABASE_PUBLIC
Definition visibility.h:54