@rsdk/db 5.11.5 → 5.11.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +4 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -1
- package/dist/metrics/call-then.d.ts +30 -0
- package/dist/metrics/call-then.js +91 -0
- package/dist/metrics/call-then.js.map +1 -0
- package/dist/metrics/clock.d.ts +2 -0
- package/dist/metrics/clock.js +9 -0
- package/dist/metrics/clock.js.map +1 -0
- package/dist/metrics/db-client-metrics.d.ts +85 -0
- package/dist/metrics/db-client-metrics.js +164 -0
- package/dist/metrics/db-client-metrics.js.map +1 -0
- package/dist/metrics/db-metric.d.ts +41 -0
- package/dist/metrics/db-metric.js +101 -0
- package/dist/metrics/db-metric.js.map +1 -0
- package/dist/metrics/db-metrics.config.d.ts +7 -0
- package/dist/metrics/db-metrics.config.js +60 -0
- package/dist/metrics/db-metrics.config.js.map +1 -0
- package/dist/metrics/db-metrics.module-base.d.ts +61 -0
- package/dist/metrics/db-metrics.module-base.js +61 -0
- package/dist/metrics/db-metrics.module-base.js.map +1 -0
- package/dist/metrics/db-metrics.providers.d.ts +66 -0
- package/dist/metrics/db-metrics.providers.js +83 -0
- package/dist/metrics/db-metrics.providers.js.map +1 -0
- package/dist/metrics/detach-group.d.ts +19 -0
- package/dist/metrics/detach-group.js +31 -0
- package/dist/metrics/detach-group.js.map +1 -0
- package/dist/metrics/detach.d.ts +24 -0
- package/dist/metrics/detach.js +45 -0
- package/dist/metrics/detach.js.map +1 -0
- package/dist/metrics/entity-operations.recorder.d.ts +17 -0
- package/dist/metrics/entity-operations.recorder.js +28 -0
- package/dist/metrics/entity-operations.recorder.js.map +1 -0
- package/dist/metrics/events.d.ts +11 -0
- package/dist/metrics/events.js +20 -0
- package/dist/metrics/events.js.map +1 -0
- package/dist/metrics/guards.d.ts +12 -0
- package/dist/metrics/guards.js +19 -0
- package/dist/metrics/guards.js.map +1 -0
- package/dist/metrics/index.d.ts +1 -0
- package/dist/metrics/index.js +11 -0
- package/dist/metrics/index.js.map +1 -0
- package/dist/metrics/instrumentation/pg-pool.instrumentation.d.ts +48 -0
- package/dist/metrics/instrumentation/pg-pool.instrumentation.js +117 -0
- package/dist/metrics/instrumentation/pg-pool.instrumentation.js.map +1 -0
- package/dist/metrics/instrumentation/pool-adapters.d.ts +22 -0
- package/dist/metrics/instrumentation/pool-adapters.js +16 -0
- package/dist/metrics/instrumentation/pool-adapters.js.map +1 -0
- package/dist/metrics/instrumentation/pool-close.d.ts +10 -0
- package/dist/metrics/instrumentation/pool-close.js +43 -0
- package/dist/metrics/instrumentation/pool-close.js.map +1 -0
- package/dist/metrics/instrumentation/pool-scope.d.ts +13 -0
- package/dist/metrics/instrumentation/pool-scope.js +3 -0
- package/dist/metrics/instrumentation/pool-scope.js.map +1 -0
- package/dist/metrics/instrumentation/pool.adapter.d.ts +50 -0
- package/dist/metrics/instrumentation/pool.adapter.js +3 -0
- package/dist/metrics/instrumentation/pool.adapter.js.map +1 -0
- package/dist/metrics/instrumentation/pool.recorder.d.ts +74 -0
- package/dist/metrics/instrumentation/pool.recorder.js +125 -0
- package/dist/metrics/instrumentation/pool.recorder.js.map +1 -0
- package/dist/metrics/instrumentation/query-completion.d.ts +12 -0
- package/dist/metrics/instrumentation/query-completion.js +76 -0
- package/dist/metrics/instrumentation/query-completion.js.map +1 -0
- package/dist/metrics/instrumentation/query.instrumentation.d.ts +35 -0
- package/dist/metrics/instrumentation/query.instrumentation.js +85 -0
- package/dist/metrics/instrumentation/query.instrumentation.js.map +1 -0
- package/dist/metrics/instrumentation/tarn-pool.instrumentation.d.ts +44 -0
- package/dist/metrics/instrumentation/tarn-pool.instrumentation.js +95 -0
- package/dist/metrics/instrumentation/tarn-pool.instrumentation.js.map +1 -0
- package/dist/metrics/instrumentation/transaction-tracker.d.ts +32 -0
- package/dist/metrics/instrumentation/transaction-tracker.js +64 -0
- package/dist/metrics/instrumentation/transaction-tracker.js.map +1 -0
- package/dist/metrics/metric-types.d.ts +17 -0
- package/dist/metrics/metric-types.js +3 -0
- package/dist/metrics/metric-types.js.map +1 -0
- package/dist/metrics/metrics.d.ts +82 -0
- package/dist/metrics/metrics.js +269 -0
- package/dist/metrics/metrics.js.map +1 -0
- package/dist/metrics/plugin-kit.d.ts +12 -0
- package/dist/metrics/plugin-kit.js +42 -0
- package/dist/metrics/plugin-kit.js.map +1 -0
- package/dist/metrics/pool-names.d.ts +47 -0
- package/dist/metrics/pool-names.js +44 -0
- package/dist/metrics/pool-names.js.map +1 -0
- package/dist/metrics/pool-stats.registry.d.ts +25 -0
- package/dist/metrics/pool-stats.registry.js +32 -0
- package/dist/metrics/pool-stats.registry.js.map +1 -0
- package/dist/metrics/scrape-source.registry.d.ts +29 -0
- package/dist/metrics/scrape-source.registry.js +55 -0
- package/dist/metrics/scrape-source.registry.js.map +1 -0
- package/dist/metrics/sql.d.ts +34 -0
- package/dist/metrics/sql.js +132 -0
- package/dist/metrics/sql.js.map +1 -0
- package/jest.config.unit.js +1 -0
- package/package.json +3 -2
- package/src/index.ts +1 -0
- package/src/metrics/call-then.ts +134 -0
- package/src/metrics/clock.ts +5 -0
- package/src/metrics/db-client-metrics.spec.ts +1894 -0
- package/src/metrics/db-client-metrics.ts +206 -0
- package/src/metrics/db-metric.spec.ts +185 -0
- package/src/metrics/db-metric.ts +188 -0
- package/src/metrics/db-metrics.config.ts +46 -0
- package/src/metrics/db-metrics.module-base.spec.ts +91 -0
- package/src/metrics/db-metrics.module-base.ts +77 -0
- package/src/metrics/db-metrics.providers.spec.ts +182 -0
- package/src/metrics/db-metrics.providers.ts +134 -0
- package/src/metrics/detach-group.spec.ts +41 -0
- package/src/metrics/detach-group.ts +30 -0
- package/src/metrics/detach.spec.ts +61 -0
- package/src/metrics/detach.ts +57 -0
- package/src/metrics/entity-operations.recorder.ts +26 -0
- package/src/metrics/events.spec.ts +19 -0
- package/src/metrics/events.ts +28 -0
- package/src/metrics/guards.spec.ts +20 -0
- package/src/metrics/guards.ts +19 -0
- package/src/metrics/index.ts +6 -0
- package/src/metrics/instrumentation/pg-pool.instrumentation.ts +177 -0
- package/src/metrics/instrumentation/pool-adapters.ts +35 -0
- package/src/metrics/instrumentation/pool-close.ts +59 -0
- package/src/metrics/instrumentation/pool-guards.spec.ts +318 -0
- package/src/metrics/instrumentation/pool-scope.ts +14 -0
- package/src/metrics/instrumentation/pool.adapter.ts +67 -0
- package/src/metrics/instrumentation/pool.recorder.ts +167 -0
- package/src/metrics/instrumentation/query-completion.spec.ts +209 -0
- package/src/metrics/instrumentation/query-completion.ts +107 -0
- package/src/metrics/instrumentation/query.instrumentation.ts +136 -0
- package/src/metrics/instrumentation/tarn-pool.instrumentation.ts +138 -0
- package/src/metrics/instrumentation/transaction-tracker.ts +103 -0
- package/src/metrics/metric-types.ts +36 -0
- package/src/metrics/metrics.ts +233 -0
- package/src/metrics/plugin-kit.ts +39 -0
- package/src/metrics/pool-names.spec.ts +79 -0
- package/src/metrics/pool-names.ts +77 -0
- package/src/metrics/pool-stats.registry.spec.ts +81 -0
- package/src/metrics/pool-stats.registry.ts +54 -0
- package/src/metrics/public-api.spec.ts +94 -0
- package/src/metrics/scrape-source.registry.spec.ts +59 -0
- package/src/metrics/scrape-source.registry.ts +55 -0
- package/src/metrics/sql.spec.ts +110 -0
- package/src/metrics/sql.ts +172 -0
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
import type { ILogger } from '@rsdk/logging';
|
|
2
|
+
|
|
3
|
+
import type { PoolAdapter } from './instrumentation/pool.adapter';
|
|
4
|
+
import { PoolRecorder } from './instrumentation/pool.recorder';
|
|
5
|
+
import type { DbPoolKind } from './instrumentation/pool-adapters';
|
|
6
|
+
import { poolAdapter } from './instrumentation/pool-adapters';
|
|
7
|
+
import { finishOnClose } from './instrumentation/pool-close';
|
|
8
|
+
import { QueryInstrumentation } from './instrumentation/query.instrumentation';
|
|
9
|
+
import { TransactionTracker } from './instrumentation/transaction-tracker';
|
|
10
|
+
import type { DbMetricsConfig } from './db-metrics.config';
|
|
11
|
+
import type { Detach } from './detach';
|
|
12
|
+
import { resolveClientMetrics } from './metrics';
|
|
13
|
+
import type { PoolLabel } from './pool-names';
|
|
14
|
+
import { poolLabelValue, PoolNames } from './pool-names';
|
|
15
|
+
import { PoolStatsRegistry } from './pool-stats.registry';
|
|
16
|
+
|
|
17
|
+
export type { DbPoolKind } from './instrumentation/pool-adapters';
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Метрики пула, запросов и транзакций на уровне драйвера.
|
|
21
|
+
*
|
|
22
|
+
* Запросы и транзакции считаются по SQL, который уходит в клиент `pg`:
|
|
23
|
+
* так одинаково работают TypeORM и MikroORM (через knex), а длительность
|
|
24
|
+
* запроса не включает ожидание соединения из пула.
|
|
25
|
+
*
|
|
26
|
+
* Пул подключается через {@link DbClientMetrics.instrumentPool}: вид пула
|
|
27
|
+
* выбирает адаптер, адаптер отдаёт то, что зависит от библиотеки пула
|
|
28
|
+
* (проверку, события, состояние, метод закрытия). Имя пула, источник gauge
|
|
29
|
+
* и итог при закрытии этот класс ставит одинаково для любого пула, так что
|
|
30
|
+
* новый драйвер — это только новый адаптер.
|
|
31
|
+
*
|
|
32
|
+
* Значение метки `pool` — `<APP_NAME>__<ресурс>`: имя приложения
|
|
33
|
+
* экземпляр получает в {@link DbClientMetrics.create}, ресурс передаёт
|
|
34
|
+
* плагин. Значение уникально в процессе: если имя уже занято подключённым пулом, пул
|
|
35
|
+
* получает имя с суффиксом `#2`, `#3`, …
|
|
36
|
+
*/
|
|
37
|
+
export class DbClientMetrics {
|
|
38
|
+
private constructor(
|
|
39
|
+
private readonly appName: string,
|
|
40
|
+
private readonly createRecorder: (pool: string) => PoolRecorder,
|
|
41
|
+
private readonly queries: QueryInstrumentation,
|
|
42
|
+
) {}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Собирает инструментирование на метриках prom-client. Порог медленного
|
|
46
|
+
* запроса берётся из `DB_METRICS_SLOW_QUERY_THRESHOLD`.
|
|
47
|
+
*
|
|
48
|
+
* Модуль метрик ORM сам его не вызывает: экземпляр (или `null`, если
|
|
49
|
+
* метрики выключены) приходит через DI из провайдера
|
|
50
|
+
* `dbMetricsModuleProviders`, который передаёт и `APP_NAME` приложения
|
|
51
|
+
*
|
|
52
|
+
* @param appName `APP_NAME` приложения: с него начинается значение метки
|
|
53
|
+
* `pool` у всех пулов этого экземпляра
|
|
54
|
+
*/
|
|
55
|
+
static create(config: DbMetricsConfig, appName: string): DbClientMetrics {
|
|
56
|
+
// Все метрики клиента регистрируются здесь. Значения db_pool_connections
|
|
57
|
+
// и db_pool_connections_max считываются при scrape из PoolStatsRegistry,
|
|
58
|
+
// поэтому ниже эти две метрики не используются
|
|
59
|
+
const metrics = resolveClientMetrics();
|
|
60
|
+
const transactions = new TransactionTracker({
|
|
61
|
+
total: metrics.transactions,
|
|
62
|
+
duration: metrics.transactionDuration,
|
|
63
|
+
active: metrics.transactionsActive,
|
|
64
|
+
});
|
|
65
|
+
const queries = new QueryInstrumentation(
|
|
66
|
+
{
|
|
67
|
+
duration: metrics.duration,
|
|
68
|
+
active: metrics.queriesActive,
|
|
69
|
+
slow: metrics.slow,
|
|
70
|
+
errors: metrics.errors,
|
|
71
|
+
},
|
|
72
|
+
transactions,
|
|
73
|
+
config.slowQueryThreshold.millis(),
|
|
74
|
+
);
|
|
75
|
+
const poolMetrics = {
|
|
76
|
+
created: metrics.created,
|
|
77
|
+
closed: metrics.closed,
|
|
78
|
+
acquireDuration: metrics.acquireDuration,
|
|
79
|
+
acquireTimeouts: metrics.acquireTimeouts,
|
|
80
|
+
usage: metrics.usage,
|
|
81
|
+
errors: metrics.poolErrors,
|
|
82
|
+
poolGauges: [metrics.queriesActive, metrics.transactionsActive],
|
|
83
|
+
};
|
|
84
|
+
const createRecorder = (pool: string): PoolRecorder =>
|
|
85
|
+
new PoolRecorder(pool, poolMetrics, transactions);
|
|
86
|
+
|
|
87
|
+
return new DbClientMetrics(appName, createRecorder, queries);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Подключает пул к метрикам. Пул, который не прошёл проверку адаптера
|
|
92
|
+
* (другой драйвер или не хватает членов), не инструментируется: в лог
|
|
93
|
+
* пишется warning, имя не занимается, результат `undefined`. Процесс
|
|
94
|
+
* при этом не падает.
|
|
95
|
+
*
|
|
96
|
+
* Итог по пулу подводится один раз, в тот момент, который наступит
|
|
97
|
+
* первым: пул закрылся (закончился первый вызов его `end`/`destroy`) или
|
|
98
|
+
* вызван возвращённый detach. Итог: соединения, которые инструментирование
|
|
99
|
+
* видело открытыми, учитываются закрытыми (их открытые транзакции —
|
|
100
|
+
* откатом), ряды пула в `db_client_queries_active` и
|
|
101
|
+
* `db_transactions_active` удаляются, пул пропадает из
|
|
102
|
+
* `db_pool_connections*`. После итога сняты подписки на события пула и
|
|
103
|
+
* обёртки его методов (`connect`, `end`/`destroy`), а имя пула снова
|
|
104
|
+
* свободно.
|
|
105
|
+
*
|
|
106
|
+
* Обёртки `query` на соединениях остаются: запрос, который завершится
|
|
107
|
+
* позже, пишет длительность, медленные запросы, ошибки и итог транзакции,
|
|
108
|
+
* но не трогает удалённые ряды пула.
|
|
109
|
+
*
|
|
110
|
+
* Пул, который потерял соединения, но не закрыт, итога не получает: его
|
|
111
|
+
* ряды остаются и показывают это состояние.
|
|
112
|
+
*
|
|
113
|
+
* Если подключение бросило исключение, уже поставленное снимается, имя
|
|
114
|
+
* освобождается, а исключение уходит вызывающему.
|
|
115
|
+
*
|
|
116
|
+
* @param kind вид пула: `pg` — `pg-pool`, `tarn` — пул knex
|
|
117
|
+
* @param pool объект пула из драйвера ORM, как есть
|
|
118
|
+
* @param resource ресурс пула внутри приложения: `typeorm`,
|
|
119
|
+
* `typeorm:slave0`, `mikro-orm`. Значение label `pool` —
|
|
120
|
+
* `<APP_NAME>__<resource>`; если оно занято другим подключённым пулом,
|
|
121
|
+
* к нему добавляется суффикс `#N`
|
|
122
|
+
* @param logger куда писать warning о пуле, который не прошёл проверку
|
|
123
|
+
* @param options `instrumentQueries` — оборачивать ли `query` у
|
|
124
|
+
* соединений пула, одинаково для любого вида пула. `true` передавать
|
|
125
|
+
* только для соединений драйвера `pg` (PostgreSQL): у остальных драйверов
|
|
126
|
+
* другой формат ошибок и ответов
|
|
127
|
+
* @returns detach, который подводит итог по пулу, если тот ещё не
|
|
128
|
+
* закрылся, или `undefined`
|
|
129
|
+
*/
|
|
130
|
+
instrumentPool(
|
|
131
|
+
kind: DbPoolKind,
|
|
132
|
+
pool: unknown,
|
|
133
|
+
resource: string,
|
|
134
|
+
logger: Pick<ILogger, 'warn'>,
|
|
135
|
+
options: { instrumentQueries: boolean },
|
|
136
|
+
): Detach | undefined {
|
|
137
|
+
return this.instrumentWith(
|
|
138
|
+
poolAdapter(kind),
|
|
139
|
+
kind,
|
|
140
|
+
pool,
|
|
141
|
+
{ appName: this.appName, resource },
|
|
142
|
+
logger,
|
|
143
|
+
options.instrumentQueries,
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
private instrumentWith<TPool extends object>(
|
|
148
|
+
adapter: PoolAdapter<TPool>,
|
|
149
|
+
kind: DbPoolKind,
|
|
150
|
+
pool: unknown,
|
|
151
|
+
label: PoolLabel,
|
|
152
|
+
logger: Pick<ILogger, 'warn'>,
|
|
153
|
+
withQueries: boolean,
|
|
154
|
+
): Detach | undefined {
|
|
155
|
+
if (!adapter.isPool(pool)) {
|
|
156
|
+
logger.warn(
|
|
157
|
+
`Pool metrics are disabled for pool ${poolLabelValue(label)}: expected a ${kind} pool`,
|
|
158
|
+
);
|
|
159
|
+
return undefined;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
const claimed = PoolNames.claim(label);
|
|
163
|
+
|
|
164
|
+
// Что уже поставлено, в порядке снятия при итоге. Если подключение
|
|
165
|
+
// бросит исключение, снимается то, что успели поставить
|
|
166
|
+
const steps: Detach[] = [];
|
|
167
|
+
|
|
168
|
+
try {
|
|
169
|
+
const recorder = this.createRecorder(claimed.name);
|
|
170
|
+
|
|
171
|
+
steps.push(() => recorder.detach());
|
|
172
|
+
|
|
173
|
+
const onConnectionCreated = (connection: object): void => {
|
|
174
|
+
recorder.connectionCreated(connection);
|
|
175
|
+
if (withQueries) {
|
|
176
|
+
this.queries.instrument(connection, recorder);
|
|
177
|
+
}
|
|
178
|
+
};
|
|
179
|
+
|
|
180
|
+
// Сначала подписки, потом уже открытые соединения: если о соединении
|
|
181
|
+
// сообщат и событие, и обход, recorder учтёт его один раз
|
|
182
|
+
steps.push(adapter.attach(pool, recorder, onConnectionCreated));
|
|
183
|
+
for (const connection of adapter.openConnections(pool)) {
|
|
184
|
+
onConnectionCreated(connection);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
steps.push(
|
|
188
|
+
PoolStatsRegistry.add({
|
|
189
|
+
pool: claimed.name,
|
|
190
|
+
stats: () => adapter.stats(pool),
|
|
191
|
+
}),
|
|
192
|
+
);
|
|
193
|
+
|
|
194
|
+
return finishOnClose(pool, adapter.closeMethod, [
|
|
195
|
+
...steps,
|
|
196
|
+
claimed.release,
|
|
197
|
+
]);
|
|
198
|
+
} catch (error) {
|
|
199
|
+
for (const step of steps) {
|
|
200
|
+
step();
|
|
201
|
+
}
|
|
202
|
+
claimed.release();
|
|
203
|
+
throw error;
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
}
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
import { Counter, Gauge, Histogram, register } from '@rsdk/core';
|
|
2
|
+
import type { ILogger } from '@rsdk/logging';
|
|
3
|
+
import { LoggerFactory } from '@rsdk/logging';
|
|
4
|
+
|
|
5
|
+
import { DbMetric, resolveDbMetric } from './db-metric';
|
|
6
|
+
import { QUERY_BUCKETS } from './metrics';
|
|
7
|
+
|
|
8
|
+
const NAME = 'db_metric_spec_operations_total';
|
|
9
|
+
|
|
10
|
+
@DbMetric('counter', {
|
|
11
|
+
name: NAME,
|
|
12
|
+
help: 'spec counter',
|
|
13
|
+
labelNames: ['entity', 'op'],
|
|
14
|
+
})
|
|
15
|
+
class SpecCounter extends Counter<'entity' | 'op'> {}
|
|
16
|
+
|
|
17
|
+
const HISTOGRAM_NAME = 'db_metric_spec_duration_seconds';
|
|
18
|
+
|
|
19
|
+
@DbMetric('histogram', {
|
|
20
|
+
name: HISTOGRAM_NAME,
|
|
21
|
+
help: 'spec histogram',
|
|
22
|
+
labelNames: ['op'],
|
|
23
|
+
buckets: [0.1, 1],
|
|
24
|
+
})
|
|
25
|
+
class SpecHistogram extends Histogram<'op'> {}
|
|
26
|
+
|
|
27
|
+
const SHARED_BUCKETS: readonly number[] = [0.5, 5];
|
|
28
|
+
const FIRST_SHARED_NAME = 'db_metric_spec_first_shared_seconds';
|
|
29
|
+
const SECOND_SHARED_NAME = 'db_metric_spec_second_shared_seconds';
|
|
30
|
+
|
|
31
|
+
@DbMetric('histogram', {
|
|
32
|
+
name: FIRST_SHARED_NAME,
|
|
33
|
+
help: 'spec histogram with shared buckets',
|
|
34
|
+
labelNames: [],
|
|
35
|
+
buckets: SHARED_BUCKETS,
|
|
36
|
+
})
|
|
37
|
+
class FirstSharedHistogram extends Histogram<string> {}
|
|
38
|
+
|
|
39
|
+
@DbMetric('histogram', {
|
|
40
|
+
name: SECOND_SHARED_NAME,
|
|
41
|
+
help: 'spec histogram with shared buckets',
|
|
42
|
+
labelNames: [],
|
|
43
|
+
buckets: SHARED_BUCKETS,
|
|
44
|
+
})
|
|
45
|
+
class SecondSharedHistogram extends Histogram<string> {}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* `true`, если в массив можно писать (`push`, `sort`). Проверку делает tsc:
|
|
49
|
+
* если `QUERY_BUCKETS` снова станет `number[]`, присваивание `false` ниже
|
|
50
|
+
* не скомпилируется
|
|
51
|
+
*/
|
|
52
|
+
type IsMutable<T> = T extends unknown[] ? true : false;
|
|
53
|
+
|
|
54
|
+
const queryBucketsAreMutable: IsMutable<typeof QUERY_BUCKETS> = false;
|
|
55
|
+
|
|
56
|
+
describe('resolveDbMetric', () => {
|
|
57
|
+
afterEach(() => {
|
|
58
|
+
register.removeSingleMetric(NAME);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
it('creates the metric when it is not in the registry', () => {
|
|
62
|
+
const metric = resolveDbMetric(SpecCounter);
|
|
63
|
+
|
|
64
|
+
expect(metric).toBeInstanceOf(SpecCounter);
|
|
65
|
+
expect(register.getSingleMetric(NAME)).toBe(metric);
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
it('returns an already registered metric of the same type and labels', () => {
|
|
69
|
+
const existing = new Counter({
|
|
70
|
+
name: NAME,
|
|
71
|
+
help: 'registered elsewhere',
|
|
72
|
+
labelNames: ['op', 'entity'],
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
expect(resolveDbMetric(SpecCounter)).toBe(existing);
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
it('throws an error naming the metric when the type differs', () => {
|
|
79
|
+
new Gauge({ name: NAME, help: 'gauge', labelNames: ['entity', 'op'] });
|
|
80
|
+
|
|
81
|
+
expect(() => resolveDbMetric(SpecCounter)).toThrow(
|
|
82
|
+
`Metric "${NAME}" is already registered as gauge with labels [entity, op], expected counter with labels [entity, op]`,
|
|
83
|
+
);
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
it('throws an error naming the metric when labelNames differ', () => {
|
|
87
|
+
new Counter({ name: NAME, help: 'counter', labelNames: ['entity'] });
|
|
88
|
+
|
|
89
|
+
expect(() => resolveDbMetric(SpecCounter)).toThrow(
|
|
90
|
+
`Metric "${NAME}" is already registered as counter with labels [entity], expected counter with labels [entity, op]`,
|
|
91
|
+
);
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
it('does not accept a histogram in place of a counter', () => {
|
|
95
|
+
new Histogram({ name: NAME, help: 'h', labelNames: ['entity', 'op'] });
|
|
96
|
+
|
|
97
|
+
expect(() => resolveDbMetric(SpecCounter)).toThrow(`Metric "${NAME}"`);
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
describe('buckets of an existing histogram', () => {
|
|
101
|
+
let warn: jest.Mock;
|
|
102
|
+
|
|
103
|
+
beforeEach(() => {
|
|
104
|
+
warn = jest.fn();
|
|
105
|
+
jest
|
|
106
|
+
.spyOn(LoggerFactory, 'create')
|
|
107
|
+
.mockReturnValue({ warn } as unknown as ILogger);
|
|
108
|
+
});
|
|
109
|
+
|
|
110
|
+
afterEach(() => {
|
|
111
|
+
register.removeSingleMetric(HISTOGRAM_NAME);
|
|
112
|
+
jest.restoreAllMocks();
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
it('different buckets: returns the existing one and logs a warning naming the metric', () => {
|
|
116
|
+
const existing = new Histogram({
|
|
117
|
+
name: HISTOGRAM_NAME,
|
|
118
|
+
help: 'registered elsewhere',
|
|
119
|
+
labelNames: ['op'],
|
|
120
|
+
buckets: [100],
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
expect(resolveDbMetric(SpecHistogram)).toBe(existing);
|
|
124
|
+
expect(warn).toHaveBeenCalledTimes(1);
|
|
125
|
+
expect(warn).toHaveBeenCalledWith(
|
|
126
|
+
`Metric "${HISTOGRAM_NAME}" is already registered with buckets [100], expected [0.1, 1]; the registered buckets are used`,
|
|
127
|
+
);
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
it('same buckets: logs no warning', () => {
|
|
131
|
+
const existing = new Histogram({
|
|
132
|
+
name: HISTOGRAM_NAME,
|
|
133
|
+
help: 'registered elsewhere',
|
|
134
|
+
labelNames: ['op'],
|
|
135
|
+
buckets: [0.1, 1],
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
expect(resolveDbMetric(SpecHistogram)).toBe(existing);
|
|
139
|
+
expect(warn).not.toHaveBeenCalled();
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
it('counter with the same name and labels: logs no warning', () => {
|
|
143
|
+
const existing = new Counter({
|
|
144
|
+
name: NAME,
|
|
145
|
+
help: 'registered elsewhere',
|
|
146
|
+
labelNames: ['entity', 'op'],
|
|
147
|
+
});
|
|
148
|
+
|
|
149
|
+
expect(resolveDbMetric(SpecCounter)).toBe(existing);
|
|
150
|
+
expect(warn).not.toHaveBeenCalled();
|
|
151
|
+
});
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
it('exports shared buckets as a readonly array', () => {
|
|
155
|
+
expect(queryBucketsAreMutable).toBe(false);
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
it('gives each histogram its own copy of shared buckets', () => {
|
|
159
|
+
try {
|
|
160
|
+
const first = resolveDbMetric(FirstSharedHistogram) as unknown as {
|
|
161
|
+
upperBounds: number[];
|
|
162
|
+
};
|
|
163
|
+
const second = resolveDbMetric(SecondSharedHistogram) as unknown as {
|
|
164
|
+
upperBounds: number[];
|
|
165
|
+
};
|
|
166
|
+
|
|
167
|
+
expect(first.upperBounds).toEqual([0.5, 5]);
|
|
168
|
+
expect(second.upperBounds).toEqual([0.5, 5]);
|
|
169
|
+
expect(first.upperBounds).not.toBe(SHARED_BUCKETS);
|
|
170
|
+
expect(second.upperBounds).not.toBe(SHARED_BUCKETS);
|
|
171
|
+
expect(first.upperBounds).not.toBe(second.upperBounds);
|
|
172
|
+
} finally {
|
|
173
|
+
register.removeSingleMetric(FIRST_SHARED_NAME);
|
|
174
|
+
register.removeSingleMetric(SECOND_SHARED_NAME);
|
|
175
|
+
}
|
|
176
|
+
});
|
|
177
|
+
|
|
178
|
+
it('throws for a class without @DbMetric', () => {
|
|
179
|
+
class Plain extends Counter<string> {}
|
|
180
|
+
|
|
181
|
+
expect(() => resolveDbMetric(Plain)).toThrow(
|
|
182
|
+
'Plain is not a database metric',
|
|
183
|
+
);
|
|
184
|
+
});
|
|
185
|
+
});
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
import type { Constructor } from '@rsdk/common';
|
|
2
|
+
import type { AnyMetric } from '@rsdk/core';
|
|
3
|
+
import {
|
|
4
|
+
Counter,
|
|
5
|
+
Gauge,
|
|
6
|
+
Histogram,
|
|
7
|
+
Metric,
|
|
8
|
+
register,
|
|
9
|
+
Summary,
|
|
10
|
+
} from '@rsdk/core';
|
|
11
|
+
import { LoggerFactory } from '@rsdk/logging';
|
|
12
|
+
|
|
13
|
+
type Described<T> = T & { description?: string };
|
|
14
|
+
type CounterConfig = Described<
|
|
15
|
+
ConstructorParameters<typeof Counter<string>>[0]
|
|
16
|
+
>;
|
|
17
|
+
type GaugeConfig = Described<ConstructorParameters<typeof Gauge<string>>[0]>;
|
|
18
|
+
type HistogramConfig = Described<
|
|
19
|
+
Omit<ConstructorParameters<typeof Histogram<string>>[0], 'buckets'> & {
|
|
20
|
+
buckets?: readonly number[];
|
|
21
|
+
}
|
|
22
|
+
>;
|
|
23
|
+
|
|
24
|
+
type DbMetricType = 'counter' | 'gauge' | 'histogram';
|
|
25
|
+
|
|
26
|
+
interface DbMetricDefinition {
|
|
27
|
+
type: DbMetricType;
|
|
28
|
+
config: CounterConfig | GaugeConfig | HistogramConfig;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
// eslint-disable-next-line @typescript-eslint/ban-types
|
|
32
|
+
const BASE_CLASSES: Record<DbMetricType, Function> = {
|
|
33
|
+
counter: Counter,
|
|
34
|
+
gauge: Gauge,
|
|
35
|
+
histogram: Histogram,
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
// eslint-disable-next-line @typescript-eslint/ban-types
|
|
39
|
+
const definitions = new Map<Function, DbMetricDefinition>();
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Обёртка над `@Metric`, которая дополнительно запоминает тип и конфигурацию
|
|
43
|
+
* метрики. Она нужна, чтобы создавать метрики без `MetricsModule.forFeature`
|
|
44
|
+
* (см. {@link resolveDbMetric}).
|
|
45
|
+
*
|
|
46
|
+
* Границы bucket'ов гистограммы принимаются как `readonly number[]`, чтобы
|
|
47
|
+
* общие константы границ можно было объявить неизменяемыми. prom-client
|
|
48
|
+
* получает их копию (см. {@link resolveDbMetric}).
|
|
49
|
+
*
|
|
50
|
+
* Типы конфигурации записаны в перегрузках целиком, а не через внутренние
|
|
51
|
+
* псевдонимы: сигнатура входит в `plugin-kit` и не должна ссылаться на
|
|
52
|
+
* неэкспортированные типы
|
|
53
|
+
*/
|
|
54
|
+
export function DbMetric(
|
|
55
|
+
type: 'counter',
|
|
56
|
+
config: ConstructorParameters<typeof Counter<string>>[0] & {
|
|
57
|
+
description?: string;
|
|
58
|
+
},
|
|
59
|
+
): ClassDecorator;
|
|
60
|
+
export function DbMetric(
|
|
61
|
+
type: 'gauge',
|
|
62
|
+
config: ConstructorParameters<typeof Gauge<string>>[0] & {
|
|
63
|
+
description?: string;
|
|
64
|
+
},
|
|
65
|
+
): ClassDecorator;
|
|
66
|
+
export function DbMetric(
|
|
67
|
+
type: 'histogram',
|
|
68
|
+
config: Omit<
|
|
69
|
+
ConstructorParameters<typeof Histogram<string>>[0],
|
|
70
|
+
'buckets'
|
|
71
|
+
> & {
|
|
72
|
+
buckets?: readonly number[];
|
|
73
|
+
description?: string;
|
|
74
|
+
},
|
|
75
|
+
): ClassDecorator;
|
|
76
|
+
export function DbMetric(type: any, config: any): ClassDecorator {
|
|
77
|
+
return (target) => {
|
|
78
|
+
definitions.set(target, { type, config });
|
|
79
|
+
Metric(type, config)(target);
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Конфиг для конструктора метрики prom-client. prom-client не копирует
|
|
85
|
+
* `buckets` и хранит переданный массив как `upperBounds`: без копии две
|
|
86
|
+
* гистограммы с одной константой границ делили бы один массив между собой
|
|
87
|
+
* и с константой
|
|
88
|
+
*/
|
|
89
|
+
const metricConfig = (
|
|
90
|
+
config: DbMetricDefinition['config'],
|
|
91
|
+
): DbMetricDefinition['config'] => {
|
|
92
|
+
const { buckets } = config as HistogramConfig;
|
|
93
|
+
|
|
94
|
+
return buckets ? { ...config, buckets: [...buckets] } : config;
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
const typeOf = (metric: AnyMetric): string => {
|
|
98
|
+
if (metric instanceof Counter) return 'counter';
|
|
99
|
+
if (metric instanceof Gauge) return 'gauge';
|
|
100
|
+
if (metric instanceof Histogram) return 'histogram';
|
|
101
|
+
if (metric instanceof Summary) return 'summary';
|
|
102
|
+
|
|
103
|
+
return (metric as object).constructor.name;
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
const sortedLabels = (labels: readonly string[] | undefined): string[] =>
|
|
107
|
+
[...(labels ?? [])].sort();
|
|
108
|
+
|
|
109
|
+
const sameItems = <T>(a: readonly T[], b: readonly T[]): boolean =>
|
|
110
|
+
a.length === b.length && a.every((item, i) => item === b[i]);
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Предупреждает, если у уже зарегистрированной гистограммы другие границы
|
|
114
|
+
* bucket'ов. Границы задаёт тот, кто зарегистрировал метрику первым,
|
|
115
|
+
* поменять их при общем реестре нельзя
|
|
116
|
+
*/
|
|
117
|
+
const warnOnForeignBuckets = (
|
|
118
|
+
existing: AnyMetric,
|
|
119
|
+
config: DbMetricDefinition['config'],
|
|
120
|
+
): void => {
|
|
121
|
+
const expected = (config as HistogramConfig).buckets;
|
|
122
|
+
const actual = (existing as { upperBounds?: readonly number[] }).upperBounds;
|
|
123
|
+
if (!expected || !actual) {
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
if (sameItems(actual, expected)) {
|
|
128
|
+
return;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
LoggerFactory.create('DbMetrics').warn(
|
|
132
|
+
`Metric "${config.name}" is already registered with buckets ` +
|
|
133
|
+
`[${actual.join(', ')}], expected [${expected.join(', ')}]; ` +
|
|
134
|
+
`the registered buckets are used`,
|
|
135
|
+
);
|
|
136
|
+
};
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Метрика на весь процесс. `MetricsModule.forFeature` создаёт метрику заново
|
|
140
|
+
* для каждого экземпляра приложения, и prom-client падает на повторной
|
|
141
|
+
* регистрации имени. Для метрик, которые плагин подключает сам, это недопустимо:
|
|
142
|
+
* тесты сервисов поднимают приложение много раз в одном процессе.
|
|
143
|
+
*
|
|
144
|
+
* Новая метрика получает свою копию границ bucket'ов.
|
|
145
|
+
*
|
|
146
|
+
* Если метрика с этим именем уже есть в общем реестре, берётся она, но только
|
|
147
|
+
* когда совпадают тип и набор `labelNames`. Иначе бросается ошибка с именем
|
|
148
|
+
* метрики: чужая метрика другого типа сломалась бы позже и непонятно где.
|
|
149
|
+
* Если у существующей гистограммы другие границы bucket'ов, ошибки нет:
|
|
150
|
+
* остаются её границы, а в лог пишется warning с именем метрики
|
|
151
|
+
*/
|
|
152
|
+
export const resolveDbMetric = <T extends AnyMetric>(
|
|
153
|
+
ctor: Constructor<T>,
|
|
154
|
+
): T => {
|
|
155
|
+
const definition = definitions.get(ctor);
|
|
156
|
+
if (!definition) {
|
|
157
|
+
throw new Error(`${ctor.name} is not a database metric`);
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
const { type, config } = definition;
|
|
161
|
+
const existing = register.getSingleMetric(config.name);
|
|
162
|
+
if (!existing) {
|
|
163
|
+
return new ctor(metricConfig(config));
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
const expectedLabels = sortedLabels(config.labelNames);
|
|
167
|
+
const existingLabels = sortedLabels(
|
|
168
|
+
(existing as { labelNames?: readonly string[] }).labelNames,
|
|
169
|
+
);
|
|
170
|
+
|
|
171
|
+
if (
|
|
172
|
+
!(existing instanceof BASE_CLASSES[type]) ||
|
|
173
|
+
!sameItems(existingLabels, expectedLabels)
|
|
174
|
+
) {
|
|
175
|
+
throw new Error(
|
|
176
|
+
`Metric "${config.name}" is already registered as ${typeOf(existing)} ` +
|
|
177
|
+
`with labels [${existingLabels.join(', ')}], ` +
|
|
178
|
+
`expected ${type} with labels [${expectedLabels.join(', ')}]`,
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
if (type === 'histogram') {
|
|
183
|
+
warnOnForeignBuckets(existing, config);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
// Тип и метки проверены выше: это метрика того же вида, что создал бы ctor
|
|
187
|
+
return existing as T;
|
|
188
|
+
};
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { text, Timespan } from '@rsdk/common';
|
|
2
|
+
import {
|
|
3
|
+
BoolParser,
|
|
4
|
+
Config,
|
|
5
|
+
ConfigSection,
|
|
6
|
+
ConfigTag,
|
|
7
|
+
Property,
|
|
8
|
+
TimespanParser,
|
|
9
|
+
} from '@rsdk/core';
|
|
10
|
+
|
|
11
|
+
@ConfigSection({
|
|
12
|
+
name: 'Database metrics config',
|
|
13
|
+
tags: [ConfigTag.infrastructure, ConfigTag.storage, ConfigTag.metric],
|
|
14
|
+
prefix: 'DB_METRICS',
|
|
15
|
+
})
|
|
16
|
+
export class DbMetricsConfig extends Config {
|
|
17
|
+
@Property('ENABLED', new BoolParser(), {
|
|
18
|
+
defaultValue: true,
|
|
19
|
+
description: text`
|
|
20
|
+
Enables database metrics. When false, the application registers
|
|
21
|
+
no database metrics and instruments nothing.
|
|
22
|
+
TypeORM: pool, query and transaction metrics only for postgres and cockroachdb;
|
|
23
|
+
for other drivers only ORM metrics.
|
|
24
|
+
MikroORM: pool metrics for any knex driver, query and transaction
|
|
25
|
+
metrics only for PostgreSQL; for MongoDB only ORM metrics.
|
|
26
|
+
`,
|
|
27
|
+
})
|
|
28
|
+
isEnabled!: boolean;
|
|
29
|
+
|
|
30
|
+
@Property('SLOW_QUERY_THRESHOLD', new TimespanParser(), {
|
|
31
|
+
defaultValue: new Timespan(500, 'ms'),
|
|
32
|
+
description:
|
|
33
|
+
'Queries longer than this are counted in db_client_slow_queries_total',
|
|
34
|
+
})
|
|
35
|
+
slowQueryThreshold!: Timespan;
|
|
36
|
+
|
|
37
|
+
@Property('ORM_ENTITY_OPERATIONS_TOTAL_ENABLED', new BoolParser(), {
|
|
38
|
+
defaultValue: false,
|
|
39
|
+
description: text`
|
|
40
|
+
Enables orm_entity_operations_total. Works only with
|
|
41
|
+
DB_METRICS_ENABLED=true. Off by default because the entity label
|
|
42
|
+
multiplies the number of series.
|
|
43
|
+
`,
|
|
44
|
+
})
|
|
45
|
+
ormEntityOperationsTotalEnabled!: boolean;
|
|
46
|
+
}
|