feat: add API performance observability reporting

This commit is contained in:
dahyeon committed 2026-06-28 00:40:05 -07:00
1 parent 871a5fe78a
commit 88de2148ae
14 files changed
+2082 -1

No files matched your search

@@ -1,5 +1,6 @@
import { Injectable, Logger, Scope, OnModuleInit } from '@nestjs/common';
import mongoose from 'mongoose';
import { applyMongoosePerformancePlugin } from '../observability/mongoose-performance.plugin';
import { SecretService } from '../secret/secret.service';
import { tournamentModelDefinitions, TournamentModelTypes } from './schema';
@@ -81,6 +82,7 @@ export class ConnectionService implements OnModuleInit {
const connection = await this.getConnection();
tournamentModelDefinitions.forEach((modelDefinition) => {
applyMongoosePerformancePlugin(modelDefinition.schema);
// 이미 생성된 경우 컴파일 스킵.
if (
Object.prototype.hasOwnProperty.call(
@@ -0,0 +1,95 @@
import {
CallHandler,
ExecutionContext,
Injectable,
NestInterceptor,
} from '@nestjs/common';
import { Observable, catchError, finalize, throwError } from 'rxjs';
import { setNewRelicTransactionName } from './new-relic';
import {
buildApiRequestPerformanceEvent,
createApiPerformanceRequestContext,
isApiPerformanceObservabilityEnabled,
recordApiRequestPerformance,
runWithApiPerformanceContext,
} from './performance-observer';
interface RequestLike {
method?: string;
originalUrl?: string;
url?: string;
path?: string;
route?: {
path?: string | RegExp | Array<string | RegExp>;
};
}
interface ResponseLike {
statusCode?: number;
}
@Injectable()
export class ApiPerformanceInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
if (!isApiPerformanceObservabilityEnabled()) {
return next.handle();
}
const http = context.switchToHttp();
const request = http.getRequest<RequestLike>();
const response = http.getResponse<ResponseLike>();
const method = request.method ?? 'UNKNOWN';
const route = resolveRouteTemplate(request);
const path = resolveRequestPath(request);
const requestContext = createApiPerformanceRequestContext({
method,
route,
path,
});
const startedAt = process.hrtime.bigint();
let thrownError: unknown;
setNewRelicTransactionName(`${method} ${route}`);
return runWithApiPerformanceContext(requestContext, () =>
next.handle().pipe(
catchError((error: unknown) => {
thrownError = error;
return throwError(() => error);
}),
finalize(() => {
const statusCode = response.statusCode ?? (thrownError ? 500 : 200);
const durationMs =
Number(process.hrtime.bigint() - startedAt) / 1_000_000;
recordApiRequestPerformance(
buildApiRequestPerformanceEvent({
context: requestContext,
statusCode,
durationMs,
isError: Boolean(thrownError) || statusCode >= 400,
}),
);
}),
),
);
}
}
export function resolveRouteTemplate(request: RequestLike): string {
const routePath = request.route?.path;
if (Array.isArray(routePath)) {
return normalizeRoute(routePath.map(String).join('|'));
}
if (routePath) return normalizeRoute(String(routePath));
return normalizeRoute(resolveRequestPath(request));
}
export function resolveRequestPath(request: RequestLike): string {
const rawPath = request.originalUrl ?? request.path ?? request.url ?? '/';
return rawPath.split('?')[0] || '/';
}
function normalizeRoute(route: string): string {
const normalized = route.startsWith('/') ? route : `/${route}`;
return normalized.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
}
@@ -0,0 +1,22 @@
import {
countHydratedDocuments,
countReturnedDocuments,
} from './mongoose-performance.plugin';
describe('Mongoose performance helpers', () => {
it('counts returned documents for common query result shapes', () => {
expect(countReturnedDocuments([{ id: 1 }, { id: 2 }])).toBe(2);
expect(countReturnedDocuments({ id: 1 })).toBe(1);
expect(countReturnedDocuments(null)).toBe(0);
expect(countReturnedDocuments(7)).toBe(7);
});
it('counts hydrated documents separately from lean documents', () => {
const hydrated = { $__: {} };
const lean = { id: 1 };
expect(countHydratedDocuments([hydrated, lean, hydrated])).toBe(2);
expect(countHydratedDocuments(lean)).toBe(0);
expect(countHydratedDocuments(hydrated)).toBe(1);
});
});
@@ -0,0 +1,188 @@
import mongoose from 'mongoose';
import { recordMongooseQueryPerformance } from './performance-observer';
const QUERY_PERFORMANCE_START = Symbol('queryPerformanceStart');
const QUERY_PERFORMANCE_RECORDED = Symbol('queryPerformanceRecorded');
const PERFORMANCE_PLUGIN_APPLIED = Symbol('performancePluginApplied');
const QUERY_OPERATIONS = [
'countDocuments',
'deleteMany',
'deleteOne',
'find',
'findOne',
'findOneAndDelete',
'findOneAndReplace',
'findOneAndUpdate',
'replaceOne',
'updateMany',
'updateOne',
] as const;
const QUERY_OPERATION_REGEX = new RegExp(`^(${QUERY_OPERATIONS.join('|')})$`);
type QueryWithPerformanceState = mongoose.Query<unknown, unknown> & {
[QUERY_PERFORMANCE_START]?: bigint;
[QUERY_PERFORMANCE_RECORDED]?: boolean;
};
type AggregateWithPerformanceState = mongoose.Aggregate<unknown[]> & {
[QUERY_PERFORMANCE_START]?: bigint;
[QUERY_PERFORMANCE_RECORDED]?: boolean;
};
type SchemaWithPerformanceMarker = mongoose.Schema & {
[PERFORMANCE_PLUGIN_APPLIED]?: boolean;
};
export function applyMongoosePerformancePlugin(schema: mongoose.Schema): void {
const markedSchema = schema as SchemaWithPerformanceMarker;
if (markedSchema[PERFORMANCE_PLUGIN_APPLIED]) return;
markedSchema[PERFORMANCE_PLUGIN_APPLIED] = true;
const hookableSchema = schema as any;
hookableSchema.pre(QUERY_OPERATION_REGEX, function () {
const query = this as QueryWithPerformanceState;
query[QUERY_PERFORMANCE_START] = process.hrtime.bigint();
query[QUERY_PERFORMANCE_RECORDED] = false;
});
hookableSchema.post(
QUERY_OPERATION_REGEX,
function (result: unknown) {
recordQueryPerformance(
this as unknown as QueryWithPerformanceState,
result,
);
},
);
hookableSchema.post(
QUERY_OPERATION_REGEX,
function (error: unknown, _result: unknown, next: (error: unknown) => void) {
recordQueryPerformance(
this as unknown as QueryWithPerformanceState,
undefined,
error,
);
next(error);
},
);
hookableSchema.pre('aggregate', function () {
const aggregate = this as AggregateWithPerformanceState;
aggregate[QUERY_PERFORMANCE_START] = process.hrtime.bigint();
aggregate[QUERY_PERFORMANCE_RECORDED] = false;
});
hookableSchema.post('aggregate', function (result: unknown) {
recordAggregatePerformance(this as AggregateWithPerformanceState, result);
});
hookableSchema.post(
'aggregate',
function (error: unknown, _result: unknown, next: (error: unknown) => void) {
recordAggregatePerformance(
this as AggregateWithPerformanceState,
undefined,
error,
);
next(error);
},
);
}
function recordQueryPerformance(
query: QueryWithPerformanceState,
result: unknown,
error?: unknown,
): void {
if (query[QUERY_PERFORMANCE_RECORDED]) return;
query[QUERY_PERFORMANCE_RECORDED] = true;
const startedAt = query[QUERY_PERFORMANCE_START];
if (!startedAt) return;
const hydratedDocsReturned = countHydratedDocuments(result);
const model = query.model as mongoose.Model<unknown> | undefined;
const options = query.getOptions();
recordMongooseQueryPerformance({
operation: (query as unknown as { op?: string }).op ?? 'query',
modelName: model?.modelName ?? 'unknown',
collectionName: model?.collection?.name,
durationMs: toDurationMs(startedAt),
docsReturned: countReturnedDocuments(result),
hydratedDocsReturned,
lean: Boolean(query.mongooseOptions().lean),
limit: numberOption(options.limit),
skip: numberOption(options.skip),
filterKeys: joinObjectKeys(query.getFilter()),
projectionKeys: joinObjectKeys(query.projection()),
sortKeys: joinObjectKeys(options.sort),
errorName: errorName(error),
});
}
function recordAggregatePerformance(
aggregate: AggregateWithPerformanceState,
result: unknown,
error?: unknown,
): void {
if (aggregate[QUERY_PERFORMANCE_RECORDED]) return;
aggregate[QUERY_PERFORMANCE_RECORDED] = true;
const startedAt = aggregate[QUERY_PERFORMANCE_START];
if (!startedAt) return;
const model = aggregate.model();
recordMongooseQueryPerformance({
operation: 'aggregate',
modelName: model?.modelName ?? 'unknown',
collectionName: model?.collection?.name,
durationMs: toDurationMs(startedAt),
docsReturned: countReturnedDocuments(result),
hydratedDocsReturned: countHydratedDocuments(result),
lean: true,
errorName: errorName(error),
});
}
export function countReturnedDocuments(result: unknown): number {
if (Array.isArray(result)) return result.length;
if (result == null) return 0;
if (typeof result === 'number') return result;
return 1;
}
export function countHydratedDocuments(result: unknown): number {
if (Array.isArray(result)) {
return result.filter((item) => isHydratedDocument(item)).length;
}
return isHydratedDocument(result) ? 1 : 0;
}
function isHydratedDocument(value: unknown): boolean {
return Boolean(
value &&
typeof value === 'object' &&
'$__' in (value as Record<string, unknown>),
);
}
function toDurationMs(startedAt: bigint): number {
return Number(process.hrtime.bigint() - startedAt) / 1_000_000;
}
function numberOption(value: unknown): number | undefined {
return typeof value === 'number' ? value : undefined;
}
function joinObjectKeys(value: unknown): string | undefined {
if (!value || typeof value !== 'object') return undefined;
const keys = Object.keys(value as Record<string, unknown>).sort();
return keys.length > 0 ? keys.join(',') : undefined;
}
function errorName(error: unknown): string | undefined {
return error instanceof Error ? error.name : undefined;
}
@@ -11,6 +11,10 @@ interface NewRelicCustomEventApi {
eventType: string,
attributes: Record<string, NewRelicAttributeValue>,
): void;
addCustomAttributes(
attributes: Record<string, NewRelicAttributeValue>,
): void;
setTransactionName(name: string): void;
}
const agent = newrelicAgent as unknown as NewRelicCustomEventApi;
@@ -37,3 +41,25 @@ export function recordNewRelicCustomEvent(
// 관측성 실패가 비즈니스 로직을 막아선 안 된다.
}
}
export function addNewRelicCustomAttributes(
attributes: Record<string, NewRelicAttributeValue | undefined>,
): void {
try {
const flat: Record<string, NewRelicAttributeValue> = {};
for (const [key, value] of Object.entries(attributes)) {
if (value !== undefined) flat[key] = value;
}
agent.addCustomAttributes(flat);
} catch {
// 관측성 실패가 비즈니스 로직을 막아선 안 된다.
}
}
export function setNewRelicTransactionName(name: string): void {
try {
agent.setTransactionName(name);
} catch {
// 관측성 실패가 비즈니스 로직을 막아선 안 된다.
}
}
@@ -0,0 +1,80 @@
import {
buildApiRequestPerformanceEvent,
createApiPerformanceRequestContext,
readBoolean,
recordMongooseQueryPerformance,
resolveApiPerformanceConfig,
runWithApiPerformanceContext,
} from './performance-observer';
describe('performance observer config', () => {
it('keeps observability disabled by default', () => {
expect(resolveApiPerformanceConfig({}).enabled).toBe(false);
expect(resolveApiPerformanceConfig({}).localEventsEnabled).toBe(false);
});
it('reads common boolean values', () => {
expect(readBoolean(undefined, true)).toBe(true);
expect(readBoolean('false', true)).toBe(false);
expect(readBoolean('enabled', false)).toBe(true);
});
});
describe('API performance request context', () => {
const originalEnv = process.env;
beforeEach(() => {
process.env = {
...originalEnv,
API_PERF_OBSERVABILITY_ENABLED: 'true',
API_PERF_LOCAL_EVENTS_ENABLED: 'false',
API_PERF_NEW_RELIC_QUERY_EVENTS_ENABLED: 'false',
};
});
afterEach(() => {
process.env = originalEnv;
});
it('aggregates Mongoose document-return metrics into the request event', () => {
const context = createApiPerformanceRequestContext({
method: 'GET',
route: '/communities/:communityId/internal-stats/matches',
path: '/communities/abc/internal-stats/matches',
});
const event = runWithApiPerformanceContext(context, () => {
recordMongooseQueryPerformance({
operation: 'find',
modelName: 'matchStats',
collectionName: 'match_stats',
durationMs: 12,
docsReturned: 300,
hydratedDocsReturned: 300,
lean: false,
});
recordMongooseQueryPerformance({
operation: 'find',
modelName: 'matchStats',
collectionName: 'match_stats',
durationMs: 3,
docsReturned: 20,
hydratedDocsReturned: 0,
lean: true,
});
return buildApiRequestPerformanceEvent({
context,
statusCode: 200,
durationMs: 50,
isError: false,
});
});
expect(event.queryCount).toBe(2);
expect(event.mongooseDurationMs).toBe(15);
expect(event.docsReturned).toBe(320);
expect(event.hydratedDocsReturned).toBe(300);
expect(event.leanQueryCount).toBe(1);
});
});
@@ -0,0 +1,285 @@
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
import { appendFile } from 'node:fs/promises';
import {
addNewRelicCustomAttributes,
NewRelicAttributeValue,
recordNewRelicCustomEvent,
} from './new-relic';
export type PerformanceEventType = 'api-request' | 'mongoose-query';
export interface ApiPerformanceConfig {
enabled: boolean;
localEventsEnabled: boolean;
localEventFile: string;
newRelicRequestEventsEnabled: boolean;
newRelicQueryEventsEnabled: boolean;
appName: string;
nodeEnv: string;
}
export interface MongooseQueryPerformance {
operation: string;
modelName: string;
collectionName?: string;
durationMs: number;
docsReturned: number;
hydratedDocsReturned: number;
lean: boolean;
limit?: number;
skip?: number;
filterKeys?: string;
projectionKeys?: string;
sortKeys?: string;
errorName?: string;
}
export interface ApiRequestPerformanceEvent {
type: 'api-request';
timestamp: string;
requestId: string;
method: string;
route: string;
path: string;
statusCode: number;
durationMs: number;
isError: boolean;
queryCount: number;
mongooseDurationMs: number;
docsReturned: number;
hydratedDocsReturned: number;
leanQueryCount: number;
}
export interface MongooseQueryPerformanceEvent
extends MongooseQueryPerformance {
type: 'mongoose-query';
timestamp: string;
requestId?: string;
method?: string;
route?: string;
path?: string;
}
export type ApiPerformanceEvent =
| ApiRequestPerformanceEvent
| MongooseQueryPerformanceEvent;
export interface ApiPerformanceContext {
requestId: string;
method: string;
route: string;
path: string;
queries: MongooseQueryPerformance[];
}
const storage = new AsyncLocalStorage<ApiPerformanceContext>();
export function readBoolean(
value: string | undefined,
defaultValue: boolean,
): boolean {
if (value == null || value.trim() === '') return defaultValue;
return !['0', 'false', 'f', 'no', 'n', 'disabled', 'off'].includes(
value.trim().toLowerCase(),
);
}
export function resolveApiPerformanceConfig(
env: NodeJS.ProcessEnv = process.env,
): ApiPerformanceConfig {
const enabled = readBoolean(env.API_PERF_OBSERVABILITY_ENABLED, false);
return {
enabled,
localEventsEnabled: readBoolean(
env.API_PERF_LOCAL_EVENTS_ENABLED,
enabled,
),
localEventFile:
env.API_PERF_LOCAL_EVENT_FILE || '/tmp/lolympus-api-performance.ndjson',
newRelicRequestEventsEnabled: readBoolean(
env.API_PERF_NEW_RELIC_REQUEST_EVENTS_ENABLED,
enabled,
),
newRelicQueryEventsEnabled: readBoolean(
env.API_PERF_NEW_RELIC_QUERY_EVENTS_ENABLED,
false,
),
appName: env.NEW_RELIC_APP_NAME || 'lolympus',
nodeEnv: env.NODE_ENV || 'dev',
};
}
export function isApiPerformanceObservabilityEnabled(): boolean {
return resolveApiPerformanceConfig().enabled;
}
export function createApiPerformanceRequestContext(params: {
method: string;
route: string;
path: string;
}): ApiPerformanceContext {
return {
requestId: randomUUID(),
method: params.method,
route: params.route,
path: params.path,
queries: [],
};
}
export function runWithApiPerformanceContext<T>(
context: ApiPerformanceContext,
callback: () => T,
): T {
return storage.run(context, callback);
}
export function getCurrentApiPerformanceContext():
| ApiPerformanceContext
| undefined {
return storage.getStore();
}
export function recordMongooseQueryPerformance(
query: MongooseQueryPerformance,
): void {
if (!isApiPerformanceObservabilityEnabled()) return;
const config = resolveApiPerformanceConfig();
const context = storage.getStore();
context?.queries.push(query);
const event: MongooseQueryPerformanceEvent = {
...query,
type: 'mongoose-query',
timestamp: new Date().toISOString(),
requestId: context?.requestId,
method: context?.method,
route: context?.route,
path: context?.path,
};
if (config.localEventsEnabled) appendLocalPerformanceEvent(event, config);
if (config.newRelicQueryEventsEnabled) {
recordNewRelicCustomEvent('MongooseQueryPerformance', {
appName: config.appName,
nodeEnv: config.nodeEnv,
requestId: event.requestId,
method: event.method,
route: event.route,
operation: event.operation,
modelName: event.modelName,
collectionName: event.collectionName,
durationMs: event.durationMs,
docsReturned: event.docsReturned,
hydratedDocsReturned: event.hydratedDocsReturned,
lean: event.lean,
limit: event.limit,
skip: event.skip,
errorName: event.errorName,
});
}
}
export function buildApiRequestPerformanceEvent(params: {
context: ApiPerformanceContext;
statusCode: number;
durationMs: number;
isError: boolean;
}): ApiRequestPerformanceEvent {
const queries = params.context.queries;
return {
type: 'api-request',
timestamp: new Date().toISOString(),
requestId: params.context.requestId,
method: params.context.method,
route: params.context.route,
path: params.context.path,
statusCode: params.statusCode,
durationMs: params.durationMs,
isError: params.isError,
queryCount: queries.length,
mongooseDurationMs: sum(queries.map((query) => query.durationMs)),
docsReturned: sum(queries.map((query) => query.docsReturned)),
hydratedDocsReturned: sum(
queries.map((query) => query.hydratedDocsReturned),
),
leanQueryCount: queries.filter((query) => query.lean).length,
};
}
export function recordApiRequestPerformance(
event: ApiRequestPerformanceEvent,
): void {
if (!isApiPerformanceObservabilityEnabled()) return;
const config = resolveApiPerformanceConfig();
if (config.localEventsEnabled) appendLocalPerformanceEvent(event, config);
if (config.newRelicRequestEventsEnabled) {
recordNewRelicCustomEvent('ApiRequestPerformance', {
appName: config.appName,
nodeEnv: config.nodeEnv,
requestId: event.requestId,
method: event.method,
route: event.route,
statusCode: event.statusCode,
durationMs: event.durationMs,
isError: event.isError,
queryCount: event.queryCount,
mongooseDurationMs: event.mongooseDurationMs,
docsReturned: event.docsReturned,
hydratedDocsReturned: event.hydratedDocsReturned,
leanQueryCount: event.leanQueryCount,
});
}
addNewRelicCustomAttributes({
appName: config.appName,
nodeEnv: config.nodeEnv,
'api.request_id': event.requestId,
'api.method': event.method,
'api.route': event.route,
'api.status_code': event.statusCode,
'api.duration_ms': event.durationMs,
'api.is_error': event.isError,
'mongoose.query_count': event.queryCount,
'mongoose.duration_ms': event.mongooseDurationMs,
'mongoose.docs_returned': event.docsReturned,
'mongoose.hydrated_docs_returned': event.hydratedDocsReturned,
'mongoose.lean_query_count': event.leanQueryCount,
});
}
export function appendLocalPerformanceEvent(
event: ApiPerformanceEvent,
config: ApiPerformanceConfig = resolveApiPerformanceConfig(),
): void {
void appendFile(config.localEventFile, `${JSON.stringify(event)}\n`).catch(
() => {
// 관측성 실패가 API 응답을 막아선 안 된다.
},
);
}
export function toNewRelicAttributes(
event: ApiRequestPerformanceEvent,
): Record<string, NewRelicAttributeValue> {
return {
requestId: event.requestId,
method: event.method,
route: event.route,
statusCode: event.statusCode,
durationMs: event.durationMs,
isError: event.isError,
queryCount: event.queryCount,
mongooseDurationMs: event.mongooseDurationMs,
docsReturned: event.docsReturned,
hydratedDocsReturned: event.hydratedDocsReturned,
leanQueryCount: event.leanQueryCount,
};
}
function sum(values: number[]): number {
return values.reduce((acc, value) => acc + value, 0);
}