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

package/src/modules/metrics.module.spec.ts

@@ -0,0 +1,267 @@
+import type { MikroORM } from '@mikro-orm/core';
+import { EventManager, EventType } from '@mikro-orm/core';
+import type { DbMetricsConfig } from '@rsdk/db';
+import type {
+  DbClientMetrics,
+  DbMetricProvider,
+  EntityOperationsRecorder,
+} from '@rsdk/db/dist/metrics/plugin-kit';
+import {
+  DB_CLIENT_METRICS_TOKEN,
+  dbMetricsModuleProviders,
+} from '@rsdk/db/dist/metrics/plugin-kit';
+import type { ILogger } from '@rsdk/logging';
+
+import type {
+  MikroOrmFlushChangesets,
+  MikroOrmFlushDuration,
+} from '../metrics/mikro-orm.metrics';
+
+import { MikroOrmMetricsModule } from './metrics.module';
+
+const noop = (): void => {};
+
+/**
+ * Все члены, которые проверяет и использует инструментирование tarn
+ */
+const tarnPool = (): { on: jest.Mock } & Record<string, unknown> => ({
+  max: 1,
+  numUsed: () => 0,
+  numFree: () => 0,
+  numPendingAcquires: () => 0,
+  destroy: noop,
+  on: jest.fn(),
+  removeListener: noop,
+  free: [],
+  used: [],
+});
+
+const pgPool = (): object => ({
+  totalCount: 0,
+  idleCount: 0,
+  waitingCount: 0,
+  options: { max: 10 },
+  connect: noop,
+  on: noop,
+  removeListener: noop,
+});
+
+/**
+ * Пул tarn без счётчиков ожидания и свободных соединений
+ */
+const partialPool = (): object => ({ max: 1, numUsed: () => 0, on: noop });
+
+const config = {
+  isEnabled: true,
+  slowQueryThreshold: { millis: () => 500 },
+  ormEntityOperationsTotalEnabled: false,
+} as unknown as DbMetricsConfig;
+
+/**
+ * `DbClientMetrics` из провайдера по токену, так же как его получает Nest:
+ * фабрика провайдера с включённым конфигом и `APP_NAME`
+ */
+const clientMetrics = (appName: string): DbClientMetrics => {
+  const provider = dbMetricsModuleProviders().find(
+    (
+      candidate,
+    ): candidate is Extract<
+      DbMetricProvider,
+      { provide: typeof DB_CLIENT_METRICS_TOKEN }
+    > => candidate.provide === DB_CLIENT_METRICS_TOKEN,
+  );
+  const client = provider?.useFactory(config, appName);
+
+  if (!client) {
+    throw new Error('The DbClientMetrics provider gave no client');
+  }
+
+  return client;
+};
+
+/**
+ * MikroORM, у которого `getKnex()` отдаёт `knex`. Без `knex` у соединения
+ * нет `getKnex`, как у драйверов не на SQL
+ */
+const orm = (knex?: object): MikroORM =>
+  ({
+    em: {
+      getConnection: () => (knex ? { getKnex: () => knex } : {}),
+      getEventManager: () => new EventManager([]),
+    },
+  }) as unknown as MikroORM;
+
+describe('MikroOrmMetricsModule pool instrumentation', () => {
+  const logger = { warn: jest.fn(), info: jest.fn() };
+  let module: MikroOrmMetricsModule | undefined;
+
+  const init = (
+    source: MikroORM,
+    client: DbClientMetrics | null = clientMetrics('app'),
+  ): void => {
+    module = new MikroOrmMetricsModule(
+      source,
+      client,
+      null,
+      null,
+      null,
+      logger as unknown as ILogger,
+    );
+    module.onModuleInit();
+  };
+
+  afterEach(() => {
+    module?.onApplicationShutdown();
+    module = undefined;
+    logger.warn.mockReset();
+    logger.info.mockReset();
+  });
+
+  it('instruments the knex pool', () => {
+    const pool = tarnPool();
+
+    init(orm({ client: { dialect: 'postgresql', pool } }));
+
+    expect(pool.on).toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.info).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['a pg-like pool', pgPool()],
+    ['a partial pool', partialPool()],
+  ])('warns once without info when the knex pool is %s', (_title, pool) => {
+    expect(() =>
+      init(orm({ client: { dialect: 'postgresql', pool } })),
+    ).not.toThrow();
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('app__mikro-orm: expected a tarn pool'),
+    );
+    expect(logger.info).not.toHaveBeenCalled();
+  });
+
+  // Имя приложения модуль не передаёт: его знает `DbClientMetrics`,
+  // которому провайдер внедряет `APP_NAME`
+  it('labels the pool with the application name of the injected client', () => {
+    init(
+      orm({ client: { dialect: 'postgresql', pool: partialPool() } }),
+      clientMetrics('other'),
+    );
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('other__mikro-orm: expected a tarn pool'),
+    );
+  });
+
+  it.each([
+    ['postgresql', true],
+    ['mysql', false],
+  ])(
+    'passes only the resource and instrumentQueries %s: %s',
+    (dialect, instrumentQueries) => {
+      const client = clientMetrics('app');
+      const instrumentPool = jest.spyOn(client, 'instrumentPool');
+      const pool = tarnPool();
+
+      init(orm({ client: { dialect, pool } }), client);
+
+      expect(instrumentPool.mock.calls).toEqual([
+        ['tarn', pool, 'mikro-orm', logger, { instrumentQueries }],
+      ]);
+    },
+  );
+
+  it('instruments nothing without an injected client', () => {
+    const pool = tarnPool();
+
+    init(orm({ client: { dialect: 'postgresql', pool } }), null);
+
+    expect(pool.on).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.info).not.toHaveBeenCalled();
+  });
+
+  it('logs info without a warning when there is no knex', () => {
+    init(orm());
+
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.info).toHaveBeenCalledWith(
+      'Pool metrics are not supported for this driver',
+    );
+  });
+});
+
+describe('MikroOrmMetricsModule injected metrics', () => {
+  const logger = { warn: jest.fn(), info: jest.fn() };
+  const duration = { observe: jest.fn() };
+  const changesets = { observe: jest.fn() };
+  const record = jest.fn();
+
+  const flushArgs = {
+    uow: {
+      getChangeSets: (): object[] => [
+        { type: 'create', meta: { className: 'Cat' } },
+      ],
+    },
+  };
+
+  const create = (
+    events: EventManager,
+    client: DbClientMetrics | null,
+  ): MikroOrmMetricsModule =>
+    new MikroOrmMetricsModule(
+      {
+        em: { getConnection: () => ({}), getEventManager: () => events },
+      } as unknown as MikroORM,
+      client,
+      { record } as unknown as EntityOperationsRecorder,
+      duration as unknown as MikroOrmFlushDuration,
+      changesets as unknown as MikroOrmFlushChangesets,
+      logger as unknown as ILogger,
+    );
+
+  const flush = async (events: EventManager): Promise<void> => {
+    await events.dispatchEvent(EventType.beforeFlush, flushArgs as never);
+    await events.dispatchEvent(EventType.afterFlush, flushArgs as never);
+  };
+
+  beforeEach(() => {
+    duration.observe.mockClear();
+    changesets.observe.mockClear();
+    record.mockClear();
+  });
+
+  it('writes flush and entity operations to the injected metrics until shutdown', async () => {
+    const events = new EventManager([]);
+    const module = create(events, clientMetrics('app'));
+
+    module.onModuleInit();
+    await flush(events);
+
+    expect(duration.observe).toHaveBeenCalledWith(expect.any(Number));
+    expect(changesets.observe).toHaveBeenCalledWith(1);
+    expect(record).toHaveBeenCalledWith('Cat', 'insert');
+
+    module.onApplicationShutdown();
+    await flush(events);
+
+    expect(duration.observe).toHaveBeenCalledTimes(1);
+    expect(changesets.observe).toHaveBeenCalledTimes(1);
+    expect(record).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses no injected metric without an injected client', async () => {
+    const events = new EventManager([]);
+    const module = create(events, null);
+
+    module.onModuleInit();
+    await flush(events);
+
+    expect(duration.observe).not.toHaveBeenCalled();
+    expect(changesets.observe).not.toHaveBeenCalled();
+    expect(record).not.toHaveBeenCalled();
+
+    module.onApplicationShutdown();
+  });
+});

package/src/modules/metrics.module.ts

@@ -0,0 +1,128 @@
+import { MikroORM } from '@mikro-orm/core';
+import type { OnApplicationShutdown, OnModuleInit } from '@nestjs/common';
+import { Inject, Module } from '@nestjs/common';
+import { InjectLogger } from '@rsdk/core';
+import type {
+  DbClientMetrics,
+  Detach,
+  EntityOperationsRecorder,
+} from '@rsdk/db/dist/metrics/plugin-kit';
+import {
+  DB_CLIENT_METRICS_TOKEN,
+  DbMetricsModuleBase,
+  dbMetricsModuleProviders,
+  ENTITY_OPERATIONS_RECORDER_TOKEN,
+} from '@rsdk/db/dist/metrics/plugin-kit';
+import { ILogger } from '@rsdk/logging';
+
+import { EntityOperationsSubscriber } from '../metrics/entity-operations.subscriber';
+import { FlushMetricsSubscriber } from '../metrics/flush-metrics.subscriber';
+import {
+  IdentityMapRegistry,
+  identityMapSize,
+} from '../metrics/identity-map.registry';
+import { findKnexPool } from '../metrics/knex-pool';
+import {
+  MikroOrmFlushChangesets,
+  MikroOrmFlushDuration,
+  MikroOrmIdentityMapSize,
+} from '../metrics/mikro-orm.metrics';
+import { registerSubscriber } from '../metrics/subscribers';
+
+/**
+ * Подключает метрики БД к MikroORM: пул knex, flush, identity map и
+ * операции над сущностями. Выключатель `DB_METRICS_ENABLED`, внедрение
+ * метрик через DI (`DbClientMetrics` и `EntityOperationsRecorder` — по
+ * токенам из `plugin-kit`) и итог при остановке приложения описаны в
+ * {@link DbMetricsModuleBase}. Значение метки `pool` собирает ядро из
+ * `APP_NAME` и ресурса из {@link findKnexPool}.
+ *
+ * При остановке subscriber-ы выключаются. Удалить их из EventManager нельзя:
+ * публичного способа нет, поэтому они остаются зарегистрированными
+ * у закрытого ORM, но ничего не пишут
+ */
+@Module({
+  providers: dbMetricsModuleProviders([
+    MikroOrmFlushDuration,
+    MikroOrmFlushChangesets,
+    MikroOrmIdentityMapSize,
+  ]),
+})
+export class MikroOrmMetricsModule
+  extends DbMetricsModuleBase
+  implements OnModuleInit, OnApplicationShutdown
+{
+  /**
+   * @param flushDuration `null`, только когда метрики выключены, а тогда
+   * `attach` не вызывается; то же для `flushChangesets`
+   */
+  constructor(
+    private readonly orm: MikroORM,
+    @Inject(DB_CLIENT_METRICS_TOKEN) client: DbClientMetrics | null,
+    @Inject(ENTITY_OPERATIONS_RECORDER_TOKEN)
+    entityOperations: EntityOperationsRecorder | null,
+    @Inject(MikroOrmFlushDuration)
+    private readonly flushDuration: MikroOrmFlushDuration | null,
+    @Inject(MikroOrmFlushChangesets)
+    private readonly flushChangesets: MikroOrmFlushChangesets | null,
+    @InjectLogger(MikroOrmMetricsModule) private readonly logger: ILogger,
+  ) {
+    super(client, entityOperations);
+  }
+
+  protected attach(
+    add: (detach?: Detach) => void,
+    client: DbClientMetrics,
+  ): void {
+    this.instrumentPool(add, client);
+    this.subscribe(add);
+    add(IdentityMapRegistry.add(() => identityMapSize(this.orm)));
+  }
+
+  private instrumentPool(
+    add: (detach?: Detach) => void,
+    client: DbClientMetrics,
+  ): void {
+    const knexPool = findKnexPool(this.orm);
+    if (!knexPool) {
+      this.logger.info('Pool metrics are not supported for this driver');
+      return;
+    }
+
+    const { resource, pool, isPostgres } = knexPool;
+
+    // Обёртка `query` рассчитана на соединения `pg`, а они в пуле knex
+    // только у диалекта postgresql
+
+    add(
+      client.instrumentPool('tarn', pool, resource, this.logger, {
+        instrumentQueries: isPostgres,
+      }),
+    );
+  }
+
+  private subscribe(add: (detach?: Detach) => void): void {
+    const events = this.orm.em.getEventManager();
+
+    if (this.flushDuration && this.flushChangesets) {
+      add(
+        registerSubscriber(
+          events,
+          new FlushMetricsSubscriber({
+            duration: this.flushDuration,
+            changesets: this.flushChangesets,
+          }),
+        ),
+      );
+    }
+
+    if (this.entityOperations) {
+      add(
+        registerSubscriber(
+          events,
+          new EntityOperationsSubscriber(this.entityOperations),
+        ),
+      );
+    }
+  }
+}