@rsdk/db 5.15.0-next.1 → 5.15.0-next.11

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.
Files changed (140) hide show
  1. package/dist/index.d.ts +1 -0
  2. package/dist/index.js +15 -0
  3. package/dist/index.js.map +1 -1
  4. package/dist/metrics/call-then.d.ts +30 -0
  5. package/dist/metrics/call-then.js +91 -0
  6. package/dist/metrics/call-then.js.map +1 -0
  7. package/dist/metrics/clock.d.ts +2 -0
  8. package/dist/metrics/clock.js +9 -0
  9. package/dist/metrics/clock.js.map +1 -0
  10. package/dist/metrics/db-client-metrics.d.ts +85 -0
  11. package/dist/metrics/db-client-metrics.js +164 -0
  12. package/dist/metrics/db-client-metrics.js.map +1 -0
  13. package/dist/metrics/db-metric.d.ts +41 -0
  14. package/dist/metrics/db-metric.js +99 -0
  15. package/dist/metrics/db-metric.js.map +1 -0
  16. package/dist/metrics/db-metrics.config.d.ts +7 -0
  17. package/dist/metrics/db-metrics.config.js +60 -0
  18. package/dist/metrics/db-metrics.config.js.map +1 -0
  19. package/dist/metrics/db-metrics.module-base.d.ts +61 -0
  20. package/dist/metrics/db-metrics.module-base.js +61 -0
  21. package/dist/metrics/db-metrics.module-base.js.map +1 -0
  22. package/dist/metrics/db-metrics.providers.d.ts +66 -0
  23. package/dist/metrics/db-metrics.providers.js +83 -0
  24. package/dist/metrics/db-metrics.providers.js.map +1 -0
  25. package/dist/metrics/detach-group.d.ts +19 -0
  26. package/dist/metrics/detach-group.js +31 -0
  27. package/dist/metrics/detach-group.js.map +1 -0
  28. package/dist/metrics/detach.d.ts +24 -0
  29. package/dist/metrics/detach.js +45 -0
  30. package/dist/metrics/detach.js.map +1 -0
  31. package/dist/metrics/entity-operations.recorder.d.ts +17 -0
  32. package/dist/metrics/entity-operations.recorder.js +28 -0
  33. package/dist/metrics/entity-operations.recorder.js.map +1 -0
  34. package/dist/metrics/events.d.ts +11 -0
  35. package/dist/metrics/events.js +20 -0
  36. package/dist/metrics/events.js.map +1 -0
  37. package/dist/metrics/guards.d.ts +12 -0
  38. package/dist/metrics/guards.js +19 -0
  39. package/dist/metrics/guards.js.map +1 -0
  40. package/dist/metrics/index.d.ts +1 -0
  41. package/dist/metrics/index.js +11 -0
  42. package/dist/metrics/index.js.map +1 -0
  43. package/dist/metrics/instrumentation/pg-pool.instrumentation.d.ts +48 -0
  44. package/dist/metrics/instrumentation/pg-pool.instrumentation.js +117 -0
  45. package/dist/metrics/instrumentation/pg-pool.instrumentation.js.map +1 -0
  46. package/dist/metrics/instrumentation/pool-adapters.d.ts +22 -0
  47. package/dist/metrics/instrumentation/pool-adapters.js +16 -0
  48. package/dist/metrics/instrumentation/pool-adapters.js.map +1 -0
  49. package/dist/metrics/instrumentation/pool-close.d.ts +10 -0
  50. package/dist/metrics/instrumentation/pool-close.js +43 -0
  51. package/dist/metrics/instrumentation/pool-close.js.map +1 -0
  52. package/dist/metrics/instrumentation/pool-scope.d.ts +13 -0
  53. package/dist/metrics/instrumentation/pool-scope.js +3 -0
  54. package/dist/metrics/instrumentation/pool-scope.js.map +1 -0
  55. package/dist/metrics/instrumentation/pool.adapter.d.ts +50 -0
  56. package/dist/metrics/instrumentation/pool.adapter.js +3 -0
  57. package/dist/metrics/instrumentation/pool.adapter.js.map +1 -0
  58. package/dist/metrics/instrumentation/pool.recorder.d.ts +74 -0
  59. package/dist/metrics/instrumentation/pool.recorder.js +125 -0
  60. package/dist/metrics/instrumentation/pool.recorder.js.map +1 -0
  61. package/dist/metrics/instrumentation/query-completion.d.ts +12 -0
  62. package/dist/metrics/instrumentation/query-completion.js +76 -0
  63. package/dist/metrics/instrumentation/query-completion.js.map +1 -0
  64. package/dist/metrics/instrumentation/query.instrumentation.d.ts +35 -0
  65. package/dist/metrics/instrumentation/query.instrumentation.js +85 -0
  66. package/dist/metrics/instrumentation/query.instrumentation.js.map +1 -0
  67. package/dist/metrics/instrumentation/tarn-pool.instrumentation.d.ts +44 -0
  68. package/dist/metrics/instrumentation/tarn-pool.instrumentation.js +95 -0
  69. package/dist/metrics/instrumentation/tarn-pool.instrumentation.js.map +1 -0
  70. package/dist/metrics/instrumentation/transaction-tracker.d.ts +32 -0
  71. package/dist/metrics/instrumentation/transaction-tracker.js +64 -0
  72. package/dist/metrics/instrumentation/transaction-tracker.js.map +1 -0
  73. package/dist/metrics/metric-types.d.ts +17 -0
  74. package/dist/metrics/metric-types.js +3 -0
  75. package/dist/metrics/metric-types.js.map +1 -0
  76. package/dist/metrics/metrics.d.ts +82 -0
  77. package/dist/metrics/metrics.js +269 -0
  78. package/dist/metrics/metrics.js.map +1 -0
  79. package/dist/metrics/plugin-kit.d.ts +12 -0
  80. package/dist/metrics/plugin-kit.js +42 -0
  81. package/dist/metrics/plugin-kit.js.map +1 -0
  82. package/dist/metrics/pool-names.d.ts +47 -0
  83. package/dist/metrics/pool-names.js +44 -0
  84. package/dist/metrics/pool-names.js.map +1 -0
  85. package/dist/metrics/pool-stats.registry.d.ts +25 -0
  86. package/dist/metrics/pool-stats.registry.js +32 -0
  87. package/dist/metrics/pool-stats.registry.js.map +1 -0
  88. package/dist/metrics/scrape-source.registry.d.ts +29 -0
  89. package/dist/metrics/scrape-source.registry.js +55 -0
  90. package/dist/metrics/scrape-source.registry.js.map +1 -0
  91. package/dist/metrics/sql.d.ts +34 -0
  92. package/dist/metrics/sql.js +132 -0
  93. package/dist/metrics/sql.js.map +1 -0
  94. package/package.json +2 -2
  95. package/src/index.ts +1 -0
  96. package/src/metrics/call-then.ts +134 -0
  97. package/src/metrics/clock.ts +5 -0
  98. package/src/metrics/db-client-metrics.spec.ts +1894 -0
  99. package/src/metrics/db-client-metrics.ts +206 -0
  100. package/src/metrics/db-metric.spec.ts +185 -0
  101. package/src/metrics/db-metric.ts +186 -0
  102. package/src/metrics/db-metrics.config.ts +46 -0
  103. package/src/metrics/db-metrics.module-base.spec.ts +91 -0
  104. package/src/metrics/db-metrics.module-base.ts +77 -0
  105. package/src/metrics/db-metrics.providers.spec.ts +182 -0
  106. package/src/metrics/db-metrics.providers.ts +134 -0
  107. package/src/metrics/detach-group.spec.ts +41 -0
  108. package/src/metrics/detach-group.ts +30 -0
  109. package/src/metrics/detach.spec.ts +61 -0
  110. package/src/metrics/detach.ts +57 -0
  111. package/src/metrics/entity-operations.recorder.ts +26 -0
  112. package/src/metrics/events.spec.ts +19 -0
  113. package/src/metrics/events.ts +28 -0
  114. package/src/metrics/guards.spec.ts +20 -0
  115. package/src/metrics/guards.ts +19 -0
  116. package/src/metrics/index.ts +6 -0
  117. package/src/metrics/instrumentation/pg-pool.instrumentation.ts +177 -0
  118. package/src/metrics/instrumentation/pool-adapters.ts +35 -0
  119. package/src/metrics/instrumentation/pool-close.ts +59 -0
  120. package/src/metrics/instrumentation/pool-guards.spec.ts +318 -0
  121. package/src/metrics/instrumentation/pool-scope.ts +14 -0
  122. package/src/metrics/instrumentation/pool.adapter.ts +67 -0
  123. package/src/metrics/instrumentation/pool.recorder.ts +167 -0
  124. package/src/metrics/instrumentation/query-completion.spec.ts +209 -0
  125. package/src/metrics/instrumentation/query-completion.ts +107 -0
  126. package/src/metrics/instrumentation/query.instrumentation.ts +136 -0
  127. package/src/metrics/instrumentation/tarn-pool.instrumentation.ts +138 -0
  128. package/src/metrics/instrumentation/transaction-tracker.ts +103 -0
  129. package/src/metrics/metric-types.ts +36 -0
  130. package/src/metrics/metrics.ts +233 -0
  131. package/src/metrics/plugin-kit.ts +39 -0
  132. package/src/metrics/pool-names.spec.ts +79 -0
  133. package/src/metrics/pool-names.ts +77 -0
  134. package/src/metrics/pool-stats.registry.spec.ts +81 -0
  135. package/src/metrics/pool-stats.registry.ts +54 -0
  136. package/src/metrics/public-api.spec.ts +104 -0
  137. package/src/metrics/scrape-source.registry.spec.ts +59 -0
  138. package/src/metrics/scrape-source.registry.ts +55 -0
  139. package/src/metrics/sql.spec.ts +110 -0
  140. package/src/metrics/sql.ts +172 -0
@@ -0,0 +1,318 @@
1
+ import { Timespan } from '@rsdk/common';
2
+ // eslint-disable-next-line import/no-extraneous-dependencies -- pg приходит в корневой node_modules от других пакетов, зависимостью @rsdk/db он не становится
3
+ import { Pool as PgPool } from 'pg';
4
+ // eslint-disable-next-line import/no-extraneous-dependencies -- tarn приходит с knex в корневой node_modules, зависимостью @rsdk/db он не становится
5
+ import { Pool as TarnPool } from 'tarn';
6
+
7
+ import { DbClientMetrics } from '../db-client-metrics';
8
+ import type { DbMetricsConfig } from '../db-metrics.config';
9
+
10
+ import {
11
+ connectedClients,
12
+ isPgPoolLike,
13
+ pgPoolAdapter,
14
+ } from './pg-pool.instrumentation';
15
+ import { isTarnPoolLike, openResources } from './tarn-pool.instrumentation';
16
+
17
+ const noop = (): void => {};
18
+
19
+ /**
20
+ * Все члены, которые использует инструментирование pg-pool
21
+ */
22
+ const pgPoolLike = (): Record<string, unknown> => ({
23
+ totalCount: 0,
24
+ idleCount: 0,
25
+ waitingCount: 0,
26
+ options: { max: 10 },
27
+ connect: noop,
28
+ end: noop,
29
+ on: noop,
30
+ removeListener: noop,
31
+ _clients: [],
32
+ });
33
+
34
+ /**
35
+ * Все члены, которые использует инструментирование tarn
36
+ */
37
+ const tarnPoolLike = (): Record<string, unknown> => ({
38
+ max: 1,
39
+ numUsed: () => 0,
40
+ numFree: () => 0,
41
+ numPendingAcquires: () => 0,
42
+ destroy: noop,
43
+ on: noop,
44
+ removeListener: noop,
45
+ free: [],
46
+ used: [],
47
+ });
48
+
49
+ /**
50
+ * Как пул mysql2: события есть, счётчиков нет
51
+ */
52
+ const mysql2PoolLike = (): Record<string, unknown> => ({
53
+ getConnection: noop,
54
+ query: noop,
55
+ on: noop,
56
+ removeListener: noop,
57
+ config: { connectionLimit: 10 },
58
+ });
59
+
60
+ const without = (
61
+ pool: Record<string, unknown>,
62
+ key: string,
63
+ ): Record<string, unknown> => {
64
+ const { [key]: _removed, ...rest } = pool;
65
+
66
+ return rest;
67
+ };
68
+
69
+ describe('isPgPoolLike', () => {
70
+ it('accepts a real pg.Pool and rejects it as a tarn pool', async () => {
71
+ const pool = new PgPool();
72
+
73
+ try {
74
+ expect(isPgPoolLike(pool)).toBe(true);
75
+ expect(isTarnPoolLike(pool)).toBe(false);
76
+ } finally {
77
+ await pool.end();
78
+ }
79
+ });
80
+
81
+ it('accepts a pool with every used member', () => {
82
+ expect(isPgPoolLike(pgPoolLike())).toBe(true);
83
+ });
84
+
85
+ it('accepts a pool without optional members and options.max', () => {
86
+ const pool = without(without(pgPoolLike(), 'end'), '_clients');
87
+
88
+ expect(isPgPoolLike({ ...pool, options: {} })).toBe(true);
89
+ });
90
+
91
+ it('rejects a mysql2-like pool', () => {
92
+ expect(isPgPoolLike(mysql2PoolLike())).toBe(false);
93
+ });
94
+
95
+ it.each([null, undefined, 1, 'pool', {}])('rejects %p', (value) => {
96
+ expect(isPgPoolLike(value)).toBe(false);
97
+ });
98
+
99
+ it.each([
100
+ 'totalCount',
101
+ 'idleCount',
102
+ 'waitingCount',
103
+ 'options',
104
+ 'connect',
105
+ 'on',
106
+ 'removeListener',
107
+ ])('rejects a pool without %s', (key) => {
108
+ expect(isPgPoolLike(without(pgPoolLike(), key))).toBe(false);
109
+ });
110
+
111
+ it.each<[string, unknown]>([
112
+ ['totalCount', '0'],
113
+ ['idleCount', '0'],
114
+ ['waitingCount', null],
115
+ ['options', null],
116
+ ['options', { max: '10' }],
117
+ ['connect', {}],
118
+ ['end', true],
119
+ ['on', {}],
120
+ ['removeListener', 1],
121
+ ['_clients', {}],
122
+ ])('rejects a pool with %s = %p', (key, value) => {
123
+ expect(isPgPoolLike({ ...pgPoolLike(), [key]: value })).toBe(false);
124
+ });
125
+ });
126
+
127
+ describe('isTarnPoolLike', () => {
128
+ it('accepts a real tarn.Pool and rejects it as a pg pool', async () => {
129
+ const pool = new TarnPool({
130
+ create: (
131
+ callback: (error: Error | null, resource: object) => void,
132
+ ): void => callback(null, {}),
133
+ destroy: noop,
134
+ min: 0,
135
+ max: 1,
136
+ });
137
+
138
+ try {
139
+ expect(isTarnPoolLike(pool)).toBe(true);
140
+ expect(isPgPoolLike(pool)).toBe(false);
141
+ } finally {
142
+ await pool.destroy();
143
+ }
144
+ });
145
+
146
+ it('accepts a pool with every used member', () => {
147
+ expect(isTarnPoolLike(tarnPoolLike())).toBe(true);
148
+ });
149
+
150
+ it('accepts a pool without optional members', () => {
151
+ const pool = ['destroy', 'free', 'used'].reduce(without, tarnPoolLike());
152
+
153
+ expect(isTarnPoolLike(pool)).toBe(true);
154
+ });
155
+
156
+ it('rejects a mysql2-like pool', () => {
157
+ expect(isTarnPoolLike(mysql2PoolLike())).toBe(false);
158
+ });
159
+
160
+ it.each([null, undefined, 1, 'pool', {}])('rejects %p', (value) => {
161
+ expect(isTarnPoolLike(value)).toBe(false);
162
+ });
163
+
164
+ it.each([
165
+ 'max',
166
+ 'numUsed',
167
+ 'numFree',
168
+ 'numPendingAcquires',
169
+ 'on',
170
+ 'removeListener',
171
+ ])('rejects a pool without %s', (key) => {
172
+ expect(isTarnPoolLike(without(tarnPoolLike(), key))).toBe(false);
173
+ });
174
+
175
+ it.each<[string, unknown]>([
176
+ ['max', '1'],
177
+ ['numUsed', 0],
178
+ ['numFree', 0],
179
+ ['numPendingAcquires', 0],
180
+ ['destroy', true],
181
+ ['on', {}],
182
+ ['removeListener', 1],
183
+ ['free', {}],
184
+ ['used', {}],
185
+ ])('rejects a pool with %s = %p', (key, value) => {
186
+ expect(isTarnPoolLike({ ...tarnPoolLike(), [key]: value })).toBe(false);
187
+ });
188
+ });
189
+
190
+ /**
191
+ * Внутренние массивы пула с мусором: такого у настоящих pg-pool и tarn
192
+ * не бывает, но проверка элементов не доверяет пулу
193
+ */
194
+ const JUNK: unknown[] = [null, undefined, 1, 'client', true];
195
+
196
+ describe('connectedClients', () => {
197
+ it('skips non-objects and clients that are not connected', () => {
198
+ const connected = { _connected: true };
199
+ const pool = {
200
+ ...pgPoolLike(),
201
+ _clients: [...JUNK, connected, { _connected: false }, {}],
202
+ };
203
+
204
+ expect(isPgPoolLike(pool)).toBe(true);
205
+ if (isPgPoolLike(pool)) {
206
+ expect(connectedClients(pool)).toEqual([connected]);
207
+ }
208
+ });
209
+
210
+ it('returns nothing without _clients', () => {
211
+ const pool = without(pgPoolLike(), '_clients');
212
+
213
+ expect(isPgPoolLike(pool)).toBe(true);
214
+ if (isPgPoolLike(pool)) {
215
+ expect(connectedClients(pool)).toEqual([]);
216
+ }
217
+ });
218
+ });
219
+
220
+ describe('pgPoolAdapter.stats', () => {
221
+ it('counts a connecting client as waiting, not as open or active', () => {
222
+ const pool = {
223
+ ...pgPoolLike(),
224
+
225
+ // Как в pg-pool: клиент попадает в `_clients` до подключения
226
+ _clients: [
227
+ { _connected: true },
228
+ { _connected: true },
229
+ { _connected: false },
230
+ ],
231
+ totalCount: 3,
232
+ idleCount: 1,
233
+ waitingCount: 4,
234
+ };
235
+
236
+ expect(isPgPoolLike(pool)).toBe(true);
237
+ if (isPgPoolLike(pool)) {
238
+ expect(pgPoolAdapter.stats(pool)).toEqual({
239
+ total: 2,
240
+ idle: 1,
241
+ active: 1,
242
+ waiting: 5,
243
+ max: 10,
244
+ });
245
+ }
246
+ });
247
+
248
+ it('uses the pool counters as is without _clients', () => {
249
+ const pool = {
250
+ ...without(pgPoolLike(), '_clients'),
251
+ totalCount: 3,
252
+ idleCount: 1,
253
+ waitingCount: 4,
254
+ };
255
+
256
+ expect(isPgPoolLike(pool)).toBe(true);
257
+ if (isPgPoolLike(pool)) {
258
+ expect(pgPoolAdapter.stats(pool)).toEqual({
259
+ total: 3,
260
+ idle: 1,
261
+ active: 2,
262
+ waiting: 4,
263
+ max: 10,
264
+ });
265
+ }
266
+ });
267
+ });
268
+
269
+ describe('openResources', () => {
270
+ it('skips non-object items and resources', () => {
271
+ const free = {};
272
+ const used = {};
273
+ const pool = {
274
+ ...tarnPoolLike(),
275
+ free: [...JUNK, { resource: free }, { resource: null }, {}],
276
+ used: [...JUNK, { resource: used }, { resource: 'connection' }],
277
+ };
278
+
279
+ expect(isTarnPoolLike(pool)).toBe(true);
280
+ if (isTarnPoolLike(pool)) {
281
+ expect(openResources(pool)).toEqual([free, used]);
282
+ }
283
+ });
284
+ });
285
+
286
+ describe('DbClientMetrics.instrumentPool with junk in pool internals', () => {
287
+ const metrics = DbClientMetrics.create(
288
+ {
289
+ slowQueryThreshold: new Timespan(500, 'ms'),
290
+ } as DbMetricsConfig,
291
+ 'junk',
292
+ );
293
+ const logger = { warn: jest.fn() };
294
+
295
+ it('does not throw for a pg pool', () => {
296
+ const pool = { ...pgPoolLike(), _clients: [...JUNK, { _connected: true }] };
297
+ const detach = metrics.instrumentPool('pg', pool, 'pg', logger, {
298
+ instrumentQueries: true,
299
+ });
300
+
301
+ expect(detach).toBeInstanceOf(Function);
302
+ detach?.();
303
+ });
304
+
305
+ it('does not throw for a tarn pool', () => {
306
+ const pool = {
307
+ ...tarnPoolLike(),
308
+ free: [...JUNK, { resource: null }],
309
+ used: [...JUNK, { resource: { query: noop } }],
310
+ };
311
+ const detach = metrics.instrumentPool('tarn', pool, 'tarn', logger, {
312
+ instrumentQueries: true,
313
+ });
314
+
315
+ expect(detach).toBeInstanceOf(Function);
316
+ detach?.();
317
+ });
318
+ });
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Пул, которому принадлежит соединение. Через него запросы и транзакции
3
+ * соединения узнают значение label `pool` и то, что итог по пулу уже
4
+ * подведён
5
+ */
6
+ export interface PoolScope {
7
+ readonly pool: string;
8
+
9
+ /**
10
+ * `false` после итога по пулу: ряды пула в gauge уже удалены, и
11
+ * `inc`/`dec` создали бы их заново
12
+ */
13
+ readonly attached: boolean;
14
+ }
@@ -0,0 +1,67 @@
1
+ import type { Detach } from '../detach';
2
+ import type { PoolStats } from '../pool-stats.registry';
3
+
4
+ import type { PoolRecorder } from './pool.recorder';
5
+
6
+ /**
7
+ * Методы записи пула, которые разрешено вызывать адаптеру. Учёт нового
8
+ * соединения (`connectionCreated`) и итог по пулу (`detach`) сюда не входят:
9
+ * их делает `DbClientMetrics`, а адаптер сообщает о новом соединении через
10
+ * `onConnectionCreated`
11
+ */
12
+ export type PoolEvents = Pick<
13
+ PoolRecorder,
14
+ | 'acquireFinished'
15
+ | 'connectionAcquired'
16
+ | 'connectionReleased'
17
+ | 'connectionClosed'
18
+ >;
19
+
20
+ /**
21
+ * То, что зависит от библиотеки пула: проверка, события, обёртки методов,
22
+ * состояние для gauge и метод закрытия. Имя пула, источник gauge, итог при
23
+ * закрытии и обёртку `query` у соединений адаптер не трогает: их по одной
24
+ * схеме для всех пулов ставит `DbClientMetrics`. Новый драйвер — новый
25
+ * адаптер и строка в таблице `POOL_ADAPTERS`
26
+ */
27
+ export interface PoolAdapter<TPool> {
28
+ /**
29
+ * Метод, которым пул закрывается: итог подводится, когда закончился
30
+ * первый его вызов
31
+ */
32
+ readonly closeMethod: keyof TPool & string;
33
+
34
+ /**
35
+ * Проверяет каждый член пула, который читает адаптер
36
+ */
37
+ isPool(value: unknown): value is TPool;
38
+
39
+ /**
40
+ * Соединения, которые пул открыл до подключения метрик
41
+ */
42
+ openConnections(pool: TPool): Iterable<object>;
43
+
44
+ /**
45
+ * Состояние пула для `db_pool_connections*` на момент scrape. Состояния
46
+ * значат одно и то же для любого пула: соединение, которое ещё
47
+ * открывается, не входит ни в `total`, ни в `active`, а тот, кто его
48
+ * ждёт, входит в `waiting`
49
+ */
50
+ stats(pool: TPool): PoolStats;
51
+
52
+ /**
53
+ * Подписывается на события пула и оборачивает его методы, чтобы
54
+ * передавать в `events` получение, возврат и закрытие соединений.
55
+ * О новом соединении — только через `onConnectionCreated`: учёт
56
+ * соединения и обёртку его запросов делает `DbClientMetrics`, и
57
+ * {@link PoolEvents} других методов адаптеру не даёт
58
+ *
59
+ * @returns detach: снимает все подписки и обёртки, поставленные здесь.
60
+ * Повторный вызов ничего не делает
61
+ */
62
+ attach(
63
+ pool: TPool,
64
+ events: PoolEvents,
65
+ onConnectionCreated: (connection: object) => void,
66
+ ): Detach;
67
+ }
@@ -0,0 +1,167 @@
1
+ import { errorMonitor } from 'node:events';
2
+
3
+ import { now, secondsSince } from '../clock';
4
+ import type { Detach } from '../detach';
5
+ import { noop } from '../detach';
6
+ import { isEventSource } from '../guards';
7
+ import type {
8
+ CounterLike,
9
+ HistogramLike,
10
+ RemovableGaugeLike,
11
+ } from '../metric-types';
12
+
13
+ import type { PoolScope } from './pool-scope';
14
+ import type { TransactionTracker } from './transaction-tracker';
15
+
16
+ export interface PoolMetrics {
17
+ created: CounterLike<'pool'>;
18
+ closed: CounterLike<'pool'>;
19
+ acquireDuration: HistogramLike<'pool'>;
20
+ acquireTimeouts: CounterLike<'pool'>;
21
+ usage: HistogramLike<'pool'>;
22
+ errors: CounterLike<'pool'>;
23
+
24
+ /**
25
+ * Gauge с label `pool`, которые ведутся через `inc`/`dec`: при итоге
26
+ * по пулу его ряд из них удаляется
27
+ */
28
+ poolGauges: RemovableGaugeLike<'pool'>[];
29
+ }
30
+
31
+ /**
32
+ * Записывает события жизненного цикла соединений одного пула.
33
+ * Не знает, откуда события приходят: это дело инструментирования
34
+ * конкретного пула. Ошибки соединений слушает сам, на каждом соединении,
35
+ * поэтому они считаются одинаково для любого пула
36
+ */
37
+ export class PoolRecorder implements PoolScope {
38
+ private readonly acquiredAt = new WeakMap<object, number>();
39
+
40
+ /**
41
+ * Соединения, которые пул открыл и ещё не закрыл, и отписка от их
42
+ * ошибок. Закрытие тех, что останутся здесь, досчитывается в итоге
43
+ */
44
+ private readonly open = new Map<object, Detach>();
45
+
46
+ /**
47
+ * Соединения, ошибка которых уже учтена: `pg.Client` на один обрыв
48
+ * эмитит `error` больше одного раза
49
+ */
50
+ private readonly failed = new WeakSet<object>();
51
+ private detached = false;
52
+
53
+ constructor(
54
+ readonly pool: string,
55
+ private readonly metrics: PoolMetrics,
56
+ private readonly transactions: TransactionTracker,
57
+ ) {}
58
+
59
+ get attached(): boolean {
60
+ return !this.detached;
61
+ }
62
+
63
+ /**
64
+ * Соединение открыто пулом. Соединения, которые пул открыл до подключения
65
+ * метрик, тоже учитываются здесь, в момент подключения: иначе их закрытие
66
+ * попало бы в закрытые без пары в созданных. Одно соединение учитывается
67
+ * один раз, сколько бы раз о нём ни сообщили
68
+ */
69
+ connectionCreated(connection: object): void {
70
+ if (this.detached || this.open.has(connection)) {
71
+ return;
72
+ }
73
+
74
+ this.metrics.created.inc({ pool: this.pool });
75
+ this.open.set(connection, this.watchErrors(connection));
76
+ }
77
+
78
+ connectionClosed(connection: object): void {
79
+ const unwatch = this.open.get(connection);
80
+
81
+ if (unwatch) {
82
+ this.open.delete(connection);
83
+ unwatch();
84
+ this.metrics.closed.inc({ pool: this.pool });
85
+ }
86
+ this.transactions.onConnectionClosed(connection);
87
+ }
88
+
89
+ /**
90
+ * @param startedAt когда начали ждать соединение
91
+ */
92
+ acquireFinished(startedAt: number, timedOut: boolean): void {
93
+ this.metrics.acquireDuration.observe(
94
+ { pool: this.pool },
95
+ secondsSince(startedAt),
96
+ );
97
+ if (timedOut) {
98
+ this.metrics.acquireTimeouts.inc({ pool: this.pool });
99
+ }
100
+ }
101
+
102
+ connectionAcquired(connection: object): void {
103
+ this.acquiredAt.set(connection, now());
104
+ }
105
+
106
+ connectionReleased(connection: object): void {
107
+ const acquiredAt = this.acquiredAt.get(connection);
108
+ if (acquiredAt === undefined) {
109
+ return;
110
+ }
111
+
112
+ this.acquiredAt.delete(connection);
113
+ this.metrics.usage.observe({ pool: this.pool }, secondsSince(acquiredAt));
114
+ }
115
+
116
+ /**
117
+ * Подводит итог по пулу. Инструментирование вызывает его, когда пул
118
+ * закрылся, или раньше, если приложение останавливается, а пул ещё не
119
+ * закрыт. Соединения, которые к этому моменту ещё открыты, считаются
120
+ * закрытыми: пул закрывается вместе с приложением, и БД откатит их
121
+ * транзакции. Если пул уже закрыл все соединения, досчитывать нечего.
122
+ *
123
+ * Затем ряды пула удаляются из gauge, а запросы и транзакции, которые
124
+ * завершатся позже, их не трогают (см. {@link PoolScope.attached}).
125
+ * Повторный вызов ничего не делает
126
+ */
127
+ detach(): void {
128
+ if (this.detached) {
129
+ return;
130
+ }
131
+
132
+ for (const connection of this.open.keys()) {
133
+ this.connectionClosed(connection);
134
+ }
135
+
136
+ this.detached = true;
137
+ for (const gauge of this.metrics.poolGauges) {
138
+ gauge.remove({ pool: this.pool });
139
+ }
140
+ }
141
+
142
+ /**
143
+ * Слушает ошибки соединения через `errorMonitor`: он не считается
144
+ * обработчиком `error`, поэтому ошибка без обработчика у владельца
145
+ * соединения по-прежнему бросается, как без метрик
146
+ */
147
+ private watchErrors(connection: object): Detach {
148
+ if (!isEventSource(connection)) {
149
+ return noop;
150
+ }
151
+
152
+ const onError = (): void => this.connectionError(connection);
153
+
154
+ connection.on(errorMonitor, onError);
155
+
156
+ return () => connection.removeListener(errorMonitor, onError);
157
+ }
158
+
159
+ private connectionError(connection: object): void {
160
+ if (this.failed.has(connection)) {
161
+ return;
162
+ }
163
+
164
+ this.failed.add(connection);
165
+ this.metrics.errors.inc({ pool: this.pool });
166
+ }
167
+ }