@rsdk/db.mikro-orm 5.15.0-next.9 → 5.15.0

package/src/metrics/entity-operations.subscriber.ts

@@ -0,0 +1,60 @@
+import type {
+  ChangeSet,
+  EventArgs,
+  EventSubscriber,
+  FlushEventArgs,
+} from '@mikro-orm/core';
+import type {
+  EntityOperation,
+  EntityOperationsRecorder,
+} from '@rsdk/db/dist/metrics/plugin-kit';
+
+import { DetachableSubscriber } from './subscribers';
+
+/**
+ * Ключи — значения `ChangeSetType`. Строками, а не через enum: в MikroORM 5
+ * нет части значений (`update_early`, `delete_early`)
+ */
+const CHANGESET_OPERATIONS: Record<string, EntityOperation | undefined> = {
+  create: 'insert',
+  update: 'update',
+  update_early: 'update',
+  delete: 'delete',
+  delete_early: 'delete',
+};
+
+/**
+ * Пишет `orm_entity_operations_total`: загрузки по onLoad, изменения
+ * по changesets после flush. Подписка на onLoad заставляет MikroORM
+ * отправлять событие для каждой загруженной сущности, поэтому subscriber
+ * регистрируется только при включённой метрике
+ */
+export class EntityOperationsSubscriber
+  extends DetachableSubscriber
+  implements EventSubscriber
+{
+  constructor(private readonly recorder: EntityOperationsRecorder) {
+    super();
+  }
+
+  onLoad({ meta }: EventArgs<object>): void {
+    if (!this.attached) {
+      return;
+    }
+
+    this.recorder.record(meta.className, 'load');
+  }
+
+  afterFlush({ uow }: FlushEventArgs): void {
+    if (!this.attached) {
+      return;
+    }
+
+    for (const changeSet of uow.getChangeSets() as ChangeSet<object>[]) {
+      const op = CHANGESET_OPERATIONS[changeSet.type];
+      if (op) {
+        this.recorder.record(changeSet.meta.className, op);
+      }
+    }
+  }
+}

package/src/metrics/flush-metrics.subscriber.ts

@@ -0,0 +1,48 @@
+import type { EventSubscriber, FlushEventArgs } from '@mikro-orm/core';
+import type { HistogramLike } from '@rsdk/db/dist/metrics/plugin-kit';
+import { now, secondsSince } from '@rsdk/db/dist/metrics/plugin-kit';
+
+import { DetachableSubscriber } from './subscribers';
+
+export interface FlushMetrics {
+  duration: HistogramLike;
+  changesets: HistogramLike;
+}
+
+/**
+ * Меряет длительность flush и число changesets в нём.
+ * Упавший flush не доходит до afterFlush и не учитывается
+ */
+export class FlushMetricsSubscriber
+  extends DetachableSubscriber
+  implements EventSubscriber
+{
+  private readonly startedAt = new WeakMap<object, number>();
+
+  constructor(private readonly metrics: FlushMetrics) {
+    super();
+  }
+
+  beforeFlush({ uow }: FlushEventArgs): void {
+    if (!this.attached) {
+      return;
+    }
+
+    this.startedAt.set(uow, now());
+  }
+
+  afterFlush({ uow }: FlushEventArgs): void {
+    if (!this.attached) {
+      return;
+    }
+
+    const startedAt = this.startedAt.get(uow);
+    if (startedAt === undefined) {
+      return;
+    }
+
+    this.startedAt.delete(uow);
+    this.metrics.duration.observe(secondsSince(startedAt));
+    this.metrics.changesets.observe(uow.getChangeSets().length);
+  }
+}

package/src/metrics/identity-map.registry.spec.ts

@@ -0,0 +1,121 @@
+import { IdentityMap } from '@mikro-orm/core';
+import { register } from '@rsdk/core';
+import type { DbMetricsConfig } from '@rsdk/db';
+import { dbMetricsModuleProviders } from '@rsdk/db/dist/metrics/plugin-kit';
+
+import { countIdentityMap, IdentityMapRegistry } from './identity-map.registry';
+import { MikroOrmIdentityMapSize } from './mikro-orm.metrics';
+
+class Account {}
+
+const scrapeIdentityMapSize = async (): Promise<number | undefined> => {
+  const metrics = await register.metrics();
+  const line = metrics
+    .split('\n')
+    .find((x) => x.startsWith('mikro_orm_identity_map_size '));
+
+  return line === undefined ? undefined : Number(line.split(' ')[1]);
+};
+
+describe('IdentityMapRegistry', () => {
+  const detach: (() => void)[] = [];
+
+  beforeAll(() => {
+    // Метрику регистрирует провайдер с включёнными метриками, как в модуле
+    // метрик MikroORM
+    const provider = dbMetricsModuleProviders([MikroOrmIdentityMapSize]).find(
+      ({ provide }) => provide === MikroOrmIdentityMapSize,
+    );
+
+    expect(
+      provider?.useFactory({ isEnabled: true } as DbMetricsConfig, 'spec'),
+    ).toBeInstanceOf(MikroOrmIdentityMapSize);
+  });
+
+  afterEach(() => {
+    for (const remove of detach.splice(0)) {
+      remove();
+    }
+  });
+
+  it('sums sources and forgets removed ones', () => {
+    const removeFirst = IdentityMapRegistry.add(() => 2);
+    const removeSecond = IdentityMapRegistry.add(() => 3);
+
+    expect(IdentityMapRegistry.total()).toBe(5);
+
+    removeFirst();
+    expect(IdentityMapRegistry.total()).toBe(3);
+
+    removeSecond();
+    expect(IdentityMapRegistry.total()).toBe(0);
+  });
+
+  it('does nothing on a second detach', () => {
+    const remove = IdentityMapRegistry.add(() => 2);
+
+    detach.push(IdentityMapRegistry.add(() => 3));
+
+    remove();
+    remove();
+
+    expect(IdentityMapRegistry.total()).toBe(3);
+  });
+
+  it('skips a source that throws or returns a non-number', () => {
+    detach.push(
+      IdentityMapRegistry.add(() => {
+        throw new Error('orm is closed');
+      }),
+      IdentityMapRegistry.add(() => undefined as unknown as number),
+      IdentityMapRegistry.add(() => 3),
+    );
+
+    expect(IdentityMapRegistry.total()).toBe(3);
+  });
+
+  it('does not fail scrape when one source throws', async () => {
+    detach.push(
+      IdentityMapRegistry.add(() => {
+        throw new RangeError('Maximum call stack size exceeded');
+      }),
+      IdentityMapRegistry.add(() => 2),
+      IdentityMapRegistry.add(() => 5),
+    );
+
+    await expect(register.metrics()).resolves.toEqual(expect.any(String));
+    expect(await scrapeIdentityMapSize()).toBe(7);
+  });
+});
+
+describe('countIdentityMap', () => {
+  it('counts a real identity map with hundreds of thousands of entities of one class', async () => {
+    const size = 250_000;
+    const map = new IdentityMap();
+    const store = new Map<string, object>();
+
+    for (let i = 0; i < size; i++) {
+      store.set(String(i), {});
+    }
+
+    // Публичный store() требует управляемую сущность с __helper; заполняем
+    // внутреннее хранилище напрямую
+    (map as unknown as { registry: Map<unknown, unknown> }).registry.set(
+      Account,
+      store,
+    );
+
+    // Проверяем, что при таком размере старый способ через keys() падает
+    expect(() => map.keys()).toThrow(RangeError);
+
+    expect(countIdentityMap(map)).toBe(size);
+
+    const remove = IdentityMapRegistry.add(() => countIdentityMap(map));
+
+    try {
+      expect(await scrapeIdentityMapSize()).toBe(size);
+    } finally {
+      remove();
+    }
+  });
+});

package/src/metrics/identity-map.registry.ts

@@ -0,0 +1,48 @@
+import type { MikroORM } from '@mikro-orm/core';
+import type { Detach } from '@rsdk/db/dist/metrics/plugin-kit';
+import { ScrapeSourceRegistry } from '@rsdk/db/dist/metrics/plugin-kit';
+
+export type IdentityMapSize = () => number;
+
+/**
+ * Число сущностей в identity map. Считается обходом, а не через `keys()`:
+ * `keys()` собирает массив через `push(...spread)` и на сотнях тысяч
+ * сущностей одного класса падает с `RangeError` (переполнение стека)
+ */
+export const countIdentityMap = (map: Iterable<unknown>): number => {
+  let size = 0;
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  for (const _ of map) {
+    size++;
+  }
+
+  return size;
+};
+
+/**
+ * Размер identity map глобального EntityManager
+ */
+export const identityMapSize = (orm: MikroORM): number =>
+  countIdentityMap(orm.em.getUnitOfWork(false).getIdentityMap());
+
+const isSize = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+const registry = new ScrapeSourceRegistry(isSize);
+
+/**
+ * EntityManager-ы, размер identity map которых gauge читает при scrape.
+ * Метрика живёт на весь процесс, а MikroORM — вместе с приложением.
+ * Источник, который бросил исключение или вернул не размер (не конечное
+ * число ≥ 0), в сумму не попадает: см. `ScrapeSourceRegistry`
+ */
+export class IdentityMapRegistry {
+  static add(source: IdentityMapSize): Detach {
+    return registry.add(source);
+  }
+
+  static total(): number {
+    return registry.snapshots().reduce((total, size) => total + size, 0);
+  }
+}

package/src/metrics/knex-pool.spec.ts

@@ -0,0 +1,38 @@
+import type { MikroORM } from '@mikro-orm/core';
+
+import { findKnexPool } from './knex-pool';
+
+/**
+ * MikroORM, у которого `getKnex()` отдаёт `knex`. Без `knex` у соединения
+ * нет `getKnex`, как у драйверов не на SQL
+ */
+const orm = (knex?: object): MikroORM =>
+  ({
+    em: {
+      getConnection: () => (knex ? { getKnex: () => knex } : {}),
+    },
+  }) as unknown as MikroORM;
+
+describe('findKnexPool', () => {
+  it('finds the pool and names its resource mikro-orm', () => {
+    const pool = {};
+
+    expect(
+      findKnexPool(orm({ client: { dialect: 'postgresql', pool } })),
+    ).toEqual({ resource: 'mikro-orm', pool, isPostgres: true });
+  });
+
+  it('marks a pool of another dialect as not postgres', () => {
+    expect(
+      findKnexPool(orm({ client: { dialect: 'mysql', pool: {} } }))?.isPostgres,
+    ).toBe(false);
+  });
+
+  it.each([
+    ['knex', undefined],
+    ['a client', {}],
+    ['a pool', { client: { dialect: 'postgresql' } }],
+  ])('returns undefined when there is no %s', (_title, knex) => {
+    expect(findKnexPool(orm(knex))).toBeUndefined();
+  });
+});

package/src/metrics/knex-pool.ts

@@ -0,0 +1,37 @@
+import type { MikroORM } from '@mikro-orm/core';
+
+export interface KnexPool {
+  resource: string;
+  pool: unknown;
+  isPostgres: boolean;
+}
+
+interface KnexLike {
+  client?: { dialect?: string; pool?: unknown };
+}
+
+/**
+ * Пул knex основного соединения. Knex есть только у SQL-драйверов, и пул
+ * у него — tarn при любом диалекте. Без knex или без пула результат
+ * `undefined`.
+ *
+ * Здесь пул только находится: что это действительно пул tarn, проверяет
+ * `DbClientMetrics.instrumentPool`.
+ *
+ * `resource` — вторая часть значения метки `pool`, всегда `mikro-orm`. Имя
+ * приложения из `APP_NAME` к нему добавляет `DbClientMetrics`
+ */
+export const findKnexPool = (orm: MikroORM): KnexPool | undefined => {
+  const connection = orm.em.getConnection() as { getKnex?: () => KnexLike };
+  const client = connection.getKnex?.().client;
+
+  if (!client?.pool) {
+    return undefined;
+  }
+
+  return {
+    resource: 'mikro-orm',
+    pool: client.pool,
+    isPostgres: client.dialect === 'postgresql',
+  };
+};

package/src/metrics/mikro-orm.metrics.ts

@@ -0,0 +1,35 @@
+import { Gauge, Histogram } from '@rsdk/core';
+import { DbMetric, QUERY_BUCKETS } from '@rsdk/db/dist/metrics/plugin-kit';
+
+import { IdentityMapRegistry } from './identity-map.registry';
+
+const CHANGESET_BUCKETS: readonly number[] = [
+  1, 5, 10, 25, 50, 100, 250, 500, 1000,
+];
+
+@DbMetric('histogram', {
+  name: 'mikro_orm_flush_duration_seconds',
+  help: 'Duration of EntityManager flush',
+  description: 'Длительность em.flush()',
+  buckets: QUERY_BUCKETS,
+})
+export class MikroOrmFlushDuration extends Histogram {}
+
+@DbMetric('histogram', {
+  name: 'mikro_orm_flush_changesets',
+  help: 'Number of changesets per flush',
+  description: 'Число changesets за один flush',
+  buckets: CHANGESET_BUCKETS,
+})
+export class MikroOrmFlushChangesets extends Histogram {}
+
+@DbMetric('gauge', {
+  name: 'mikro_orm_identity_map_size',
+  help: 'Number of entities in the global EntityManager identity map',
+  description:
+    'Размер identity map глобального EntityManager. Рост означает, что забыли fork или clear',
+  collect(this: Gauge): void {
+    this.set(IdentityMapRegistry.total());
+  },
+})
+export class MikroOrmIdentityMapSize extends Gauge {}

package/src/metrics/subscribers.spec.ts

@@ -0,0 +1,164 @@
+import type { EventArgs, FlushEventArgs } from '@mikro-orm/core';
+import { EventManager, EventType } from '@mikro-orm/core';
+import type { EntityOperationsRecorder } from '@rsdk/db/dist/metrics/plugin-kit';
+
+import { EntityOperationsSubscriber } from './entity-operations.subscriber';
+import { FlushMetricsSubscriber } from './flush-metrics.subscriber';
+import { registerSubscriber } from './subscribers';
+
+const flushArgs = (types: string[]): FlushEventArgs =>
+  ({
+    uow: {
+      getChangeSets: () =>
+        types.map((type) => ({ type, meta: { className: 'Cat' } })),
+    },
+  }) as unknown as FlushEventArgs;
+
+const loadArgs = {
+  meta: { className: 'Cat' },
+} as unknown as EventArgs<object>;
+
+describe('FlushMetricsSubscriber', () => {
+  const duration = { observe: jest.fn() };
+  const changesets = { observe: jest.fn() };
+  let subscriber: FlushMetricsSubscriber;
+
+  beforeEach(() => {
+    duration.observe.mockClear();
+    changesets.observe.mockClear();
+    subscriber = new FlushMetricsSubscriber({ duration, changesets });
+  });
+
+  it('measures flush between beforeFlush and afterFlush', () => {
+    const args = flushArgs(['create', 'update']);
+
+    subscriber.beforeFlush(args);
+    subscriber.afterFlush(args);
+
+    expect(duration.observe).toHaveBeenCalledWith(expect.any(Number));
+    expect(changesets.observe).toHaveBeenCalledWith(2);
+  });
+
+  it('records nothing without beforeFlush', () => {
+    subscriber.afterFlush(flushArgs(['create']));
+
+    expect(duration.observe).not.toHaveBeenCalled();
+    expect(changesets.observe).not.toHaveBeenCalled();
+  });
+
+  it('records nothing after detach', () => {
+    const args = flushArgs(['create']);
+
+    subscriber.detach();
+    subscriber.beforeFlush(args);
+    subscriber.afterFlush(args);
+
+    expect(duration.observe).not.toHaveBeenCalled();
+    expect(changesets.observe).not.toHaveBeenCalled();
+  });
+
+  it('records nothing for a flush started before detach and finished after it', () => {
+    const args = flushArgs(['create']);
+
+    subscriber.beforeFlush(args);
+    subscriber.detach();
+    subscriber.afterFlush(args);
+
+    expect(duration.observe).not.toHaveBeenCalled();
+    expect(changesets.observe).not.toHaveBeenCalled();
+  });
+});
+
+describe('EntityOperationsSubscriber', () => {
+  const record = jest.fn();
+  let subscriber: EntityOperationsSubscriber;
+
+  beforeEach(() => {
+    record.mockClear();
+    subscriber = new EntityOperationsSubscriber({
+      record,
+    } as unknown as EntityOperationsRecorder);
+  });
+
+  it('maps changesets to operations', () => {
+    subscriber.afterFlush(
+      flushArgs([
+        'create',
+        'update',
+        'update_early',
+        'delete',
+        'delete_early',
+        'unknown',
+      ]),
+    );
+
+    expect(record.mock.calls).toEqual([
+      ['Cat', 'insert'],
+      ['Cat', 'update'],
+      ['Cat', 'update'],
+      ['Cat', 'delete'],
+      ['Cat', 'delete'],
+    ]);
+  });
+
+  it('counts a load', () => {
+    subscriber.onLoad(loadArgs);
+
+    expect(record).toHaveBeenCalledWith('Cat', 'load');
+  });
+
+  it('records nothing after detach', () => {
+    subscriber.detach();
+    subscriber.onLoad(loadArgs);
+    subscriber.afterFlush(flushArgs(['create', 'update', 'delete']));
+
+    expect(record).not.toHaveBeenCalled();
+  });
+});
+
+describe('registerSubscriber', () => {
+  const record = jest.fn();
+
+  beforeEach(() => record.mockClear());
+
+  it('registers the subscriber in EventManager and Detach turns it off', async () => {
+    const events = new EventManager([]);
+    const detach = registerSubscriber(
+      events,
+      new EntityOperationsSubscriber({
+        record,
+      } as unknown as EntityOperationsRecorder),
+    );
+
+    await events.dispatchEvent(EventType.afterFlush, flushArgs(['create']));
+
+    expect(record.mock.calls).toEqual([['Cat', 'insert']]);
+
+    detach();
+    await events.dispatchEvent(EventType.afterFlush, flushArgs(['create']));
+
+    expect(record).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the subscriber off on a second detach', async () => {
+    const events = new EventManager([]);
+    const detach = registerSubscriber(
+      events,
+      new EntityOperationsSubscriber({
+        record,
+      } as unknown as EntityOperationsRecorder),
+    );
+
+    detach();
+    expect(() => detach()).not.toThrow();
+    await events.dispatchEvent(EventType.afterFlush, flushArgs(['create']));
+
+    expect(record).not.toHaveBeenCalled();
+  });
+
+  it('does not treat detach, detached and attached as hooks', () => {
+    expect(Object.keys(EventType)).not.toContain('detach');
+    expect(Object.keys(EventType)).not.toContain('detached');
+    expect(Object.keys(EventType)).not.toContain('attached');
+  });
+});

package/src/metrics/subscribers.ts

@@ -0,0 +1,40 @@
+import type { EventManager, EventSubscriber } from '@mikro-orm/core';
+import type { Detach } from '@rsdk/db/dist/metrics/plugin-kit';
+
+/**
+ * Subscriber метрик, которого можно выключить: у EventManager нет способа
+ * удалить подписчика. Каждый хук наследника первым делом проверяет `attached`.
+ * Выключить можно только через {@link DetachableSubscriber.detach}, включить
+ * обратно нельзя.
+ *
+ * `detach`, `detached` и `attached` не совпадают ни с одним ключом
+ * `EventType`, поэтому MikroORM не принимает их за хуки. `EventSubscriber`
+ * реализуют наследники: у него все поля необязательные, и класс без хуков
+ * TypeScript не примет
+ */
+export abstract class DetachableSubscriber {
+  private detached = false;
+
+  protected get attached(): boolean {
+    return !this.detached;
+  }
+
+  detach(): void {
+    this.detached = true;
+  }
+}
+
+/**
+ * Регистрирует subscriber в EventManager. Detach не удаляет subscriber из
+ * EventManager, а выключает его: subscriber остаётся зарегистрированным,
+ * но больше ничего не пишет. Повторный вызов ничего не меняет:
+ * {@link DetachableSubscriber.detach} только ставит флаг
+ */
+export const registerSubscriber = (
+  events: EventManager,
+  subscriber: DetachableSubscriber & EventSubscriber,
+): Detach => {
+  events.registerSubscriber(subscriber);
+
+  return () => subscriber.detach();
+};

package/src/mikro-orm.plugin.ts

@@ -20,6 +20,7 @@ import { LoggerFactory } from '@rsdk/logging';
 import _ from 'lodash';
 import path from 'node:path';
 
+import { MikroOrmMetricsModule } from './modules/metrics.module';
 import { MikroOrmPluginConfig } from './providers/mikro-orm.config';
 import { MikroOrmAdapter } from './providers/mikro-orm-logger.adapter';
 import { MikroOrmErrorTransformer } from './mikro-orm.errors-transformer';
@@ -188,6 +189,7 @@ export class MikroOrmPlugin implements PlatformAppPlugin {
             .value();
         },
       }),
+      MikroOrmMetricsModule,
     ];
   }