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

@@ -0,0 +1,218 @@
import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import {
buildEndpointReportFromLocalEvents,
buildNewRelicCustomEventNrql,
buildNewRelicTransactionNrql,
discoverApiRoutes,
formatMarkdownReport,
mergeRowsWithManifest,
} from './api-performance-report';
import type { ApiPerformanceEvent } from '../modules/global/observability/performance-observer';
describe('api performance route discovery', () => {
let rootDir: string;
beforeEach(async () => {
rootDir = await mkdtemp(path.join(os.tmpdir(), 'api-performance-routes-'));
await mkdir(path.join(rootDir, 'modules', 'match'), { recursive: true });
});
afterEach(async () => {
await rm(rootDir, { recursive: true, force: true });
});
it('discovers controller routes including multiline decorators', async () => {
await writeFile(
path.join(rootDir, 'modules', 'match', 'match.controller.ts'),
`
import { Controller, Get, Post } from '@nestjs/common';
@Controller('communities/:communityId/matches')
export class MatchController {
@Get()
list() {}
@Post(
':matchId/participants'
)
join() {}
}
`,
);
await writeFile(
path.join(rootDir, 'app.controller.ts'),
`
import { Controller, Get } from '@nestjs/common';
@Controller()
export class AppController {
@Get()
root() {}
}
`,
);
await expect(discoverApiRoutes(rootDir)).resolves.toEqual([
{
method: 'GET',
route: '/',
controllerFile: 'app.controller.ts',
},
{
method: 'GET',
route: '/communities/:communityId/matches',
controllerFile: 'modules/match/match.controller.ts',
},
{
method: 'POST',
route: '/communities/:communityId/matches/:matchId/participants',
controllerFile: 'modules/match/match.controller.ts',
},
]);
});
});
describe('api performance report generation', () => {
it('reports every manifest route, including routes with no samples', () => {
const routes = [
{
method: 'GET',
route: '/communities/:communityId/matches',
controllerFile: 'match.controller.ts',
},
{
method: 'POST',
route: '/communities/:communityId/matches',
controllerFile: 'match.controller.ts',
},
{
method: 'GET',
route: '/communities/:communityId/internal-stats/matches',
controllerFile: 'community-stats.controller.ts',
},
];
const events: ApiPerformanceEvent[] = [
{
type: 'api-request',
timestamp: '2026-06-28T00:00:00.000Z',
requestId: 'request-1',
method: 'GET',
route: '/communities/:communityId/matches',
path: '/communities/abc/matches',
statusCode: 200,
durationMs: 100,
isError: false,
queryCount: 2,
mongooseDurationMs: 40,
docsReturned: 50,
hydratedDocsReturned: 50,
leanQueryCount: 0,
},
];
const rows = buildEndpointReportFromLocalEvents({
routes,
events,
p95BudgetMs: 300,
docsReturnedP95Budget: 500,
hydratedDocsReturnedP95Budget: 0,
});
expect(rows).toHaveLength(3);
expect(
rows.find(
(row) => row.route === '/communities/:communityId/matches',
)?.status,
).toBe('document-heavy');
expect(rows.filter((row) => row.status === 'no-samples')).toHaveLength(2);
});
it('keeps observed-only New Relic rows while adding no-sample manifest routes', () => {
const rows = mergeRowsWithManifest({
routes: [
{
method: 'GET',
route: '/known',
controllerFile: 'known.controller.ts',
},
],
measuredRows: [
{
method: 'GET',
route: '/observed-only',
source: 'newrelic-transaction',
samples: 10,
avgMs: 40,
p50Ms: 35,
p95Ms: 80,
p99Ms: 120,
maxMs: 130,
errorRatePercentage: 0,
queryCountP95: null,
mongooseDurationP95Ms: null,
docsReturnedP95: null,
hydratedDocsReturnedP95: null,
status: 'ok',
},
],
fallbackSource: 'newrelic-transaction',
p95BudgetMs: 300,
docsReturnedP95Budget: 500,
hydratedDocsReturnedP95Budget: 0,
});
expect(rows.map((row) => `${row.method} ${row.route}`)).toEqual([
'GET /known',
'GET /observed-only',
]);
expect(rows[0].status).toBe('no-samples');
expect(rows[1].samples).toBe(10);
});
it('formats all rows instead of truncating to a top list', () => {
const rows = Array.from({ length: 12 }, (_, index) => ({
method: 'GET',
route: `/route-${index}`,
source: 'local' as const,
samples: 1,
avgMs: 10,
p50Ms: 10,
p95Ms: 10,
p99Ms: 10,
maxMs: 10,
errorRatePercentage: 0,
queryCountP95: 1,
mongooseDurationP95Ms: 1,
docsReturnedP95: 1,
hydratedDocsReturnedP95: 0,
status: 'ok' as const,
}));
const report = formatMarkdownReport({
rows,
source: 'local',
since: 'fixture',
});
expect(report).toContain('/route-0');
expect(report).toContain('/route-11');
});
it('builds New Relic queries for custom events and transaction duration data', () => {
expect(buildNewRelicCustomEventNrql('lolympus-api', '1 day ago')).toContain(
'FROM ApiRequestPerformance',
);
expect(buildNewRelicCustomEventNrql('lolympus-api', '1 day ago')).toContain(
'FACET method, route',
);
expect(
buildNewRelicTransactionNrql('lolympus-api', '1 day ago'),
).toContain('FROM Transaction');
expect(
buildNewRelicTransactionNrql('lolympus-api', '1 day ago'),
).toContain('FACET name');
});
});
@@ -0,0 +1,808 @@
import { existsSync } from 'node:fs';
import { readdir, readFile, writeFile } from 'node:fs/promises';
import path from 'node:path';
import process from 'node:process';
import type {
ApiPerformanceEvent,
ApiRequestPerformanceEvent,
} from '../modules/global/observability/performance-observer';
export type ReportSource =
| 'local'
| 'newrelic-custom'
| 'newrelic-transaction';
export interface ApiRoute {
method: string;
route: string;
controllerFile: string;
}
export interface EndpointReportRow {
method: string;
route: string;
controllerFile?: string;
source: ReportSource | 'none';
samples: number;
avgMs: number | null;
p50Ms: number | null;
p95Ms: number | null;
p99Ms: number | null;
maxMs: number | null;
errorRatePercentage: number | null;
queryCountP95: number | null;
mongooseDurationP95Ms: number | null;
docsReturnedP95: number | null;
hydratedDocsReturnedP95: number | null;
status: 'ok' | 'slow' | 'document-heavy' | 'no-samples';
}
interface ReportOptions {
source: ReportSource;
rootDir: string;
inputFile: string;
outputFile?: string;
format: 'markdown' | 'json';
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
since: string;
newRelicAccountId?: string;
newRelicApiKey?: string;
newRelicAppName: string;
routesOnly: boolean;
}
interface NewRelicNrqlResponse {
data?: {
actor?: {
account?: {
nrql?: {
results?: Record<string, unknown>[];
};
};
};
};
errors?: Array<{ message?: string }>;
}
const HTTP_DECORATOR_TO_METHOD: Record<string, string> = {
All: 'ALL',
Delete: 'DELETE',
Get: 'GET',
Head: 'HEAD',
Options: 'OPTIONS',
Patch: 'PATCH',
Post: 'POST',
Put: 'PUT',
};
export async function discoverApiRoutes(rootDir: string): Promise<ApiRoute[]> {
const files = await listControllerFiles(rootDir);
const routes = new Map<string, ApiRoute>();
for (const file of files) {
const source = await readFile(file, 'utf8');
const basePath = extractDecoratorStringArgument(source, 'Controller');
if (basePath === undefined) continue;
const methodDecoratorRegex =
/@(Get|Post|Patch|Put|Delete|Head|Options|All)\s*\(([\s\S]*?)\)/g;
for (const match of source.matchAll(methodDecoratorRegex)) {
const method = HTTP_DECORATOR_TO_METHOD[match[1]];
const route = normalizeRoute(
joinRouteParts(basePath, extractFirstStringLiteral(match[2]) ?? ''),
);
const key = routeKey(method, route);
routes.set(key, {
method,
route,
controllerFile: path.relative(rootDir, file),
});
}
}
return [...routes.values()].sort(
(left, right) =>
left.route.localeCompare(right.route) ||
left.method.localeCompare(right.method),
);
}
export async function readLocalPerformanceEvents(
inputFile: string,
): Promise<ApiPerformanceEvent[]> {
if (!existsSync(inputFile)) return [];
const content = await readFile(inputFile, 'utf8');
return content
.split(/\r?\n/)
.filter(Boolean)
.flatMap((line) => {
try {
return [JSON.parse(line) as ApiPerformanceEvent];
} catch {
return [];
}
});
}
export function buildEndpointReportFromLocalEvents(params: {
routes: ApiRoute[];
events: ApiPerformanceEvent[];
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
}): EndpointReportRow[] {
const requestsByRoute = new Map<string, ApiRequestPerformanceEvent[]>();
for (const event of params.events) {
if (event.type !== 'api-request') continue;
const key = routeKey(event.method, event.route);
requestsByRoute.set(key, [...(requestsByRoute.get(key) ?? []), event]);
}
const rowsByKey = new Map<string, EndpointReportRow>();
for (const route of params.routes) {
const events = requestsByRoute.get(routeKey(route.method, route.route)) ?? [];
rowsByKey.set(
routeKey(route.method, route.route),
summarizeRequestEvents(route, events, {
source: 'local',
p95BudgetMs: params.p95BudgetMs,
docsReturnedP95Budget: params.docsReturnedP95Budget,
hydratedDocsReturnedP95Budget: params.hydratedDocsReturnedP95Budget,
}),
);
}
for (const [key, events] of requestsByRoute.entries()) {
if (rowsByKey.has(key)) continue;
const first = events[0];
rowsByKey.set(
key,
summarizeRequestEvents(
{
method: first.method,
route: first.route,
controllerFile: 'observed-only',
},
events,
{
source: 'local',
p95BudgetMs: params.p95BudgetMs,
docsReturnedP95Budget: params.docsReturnedP95Budget,
hydratedDocsReturnedP95Budget: params.hydratedDocsReturnedP95Budget,
},
),
);
}
return [...rowsByKey.values()].sort(compareReportRows);
}
export async function fetchNewRelicEndpointRows(params: {
source: Exclude<ReportSource, 'local'>;
accountId: string;
apiKey: string;
appName: string;
since: string;
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
}): Promise<EndpointReportRow[]> {
const nrql =
params.source === 'newrelic-custom'
? buildNewRelicCustomEventNrql(params.appName, params.since)
: buildNewRelicTransactionNrql(params.appName, params.since);
const response = await fetch('https://api.newrelic.com/graphql', {
method: 'POST',
headers: {
'Api-Key': params.apiKey,
'Content-Type': 'application/json',
},
body: JSON.stringify({
query: `{
actor {
account(id: ${Number(params.accountId)}) {
nrql(query: ${JSON.stringify(nrql)}) {
results
}
}
}
}`,
}),
});
if (!response.ok) {
throw new Error(
`New Relic query failed: ${response.status} ${response.statusText}`,
);
}
const json = (await response.json()) as NewRelicNrqlResponse;
if (json.errors?.length) {
throw new Error(
`New Relic query failed: ${json.errors
.map((error) => error.message ?? 'unknown error')
.join('; ')}`,
);
}
const results = json.data?.actor?.account?.nrql?.results ?? [];
return results
.map((result) =>
params.source === 'newrelic-custom'
? newRelicCustomResultToRow(result, params)
: newRelicTransactionResultToRow(result, params),
)
.filter((row): row is EndpointReportRow => row !== null)
.sort(compareReportRows);
}
export function mergeRowsWithManifest(params: {
routes: ApiRoute[];
measuredRows: EndpointReportRow[];
fallbackSource: ReportSource;
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
}): EndpointReportRow[] {
const rowsByKey = new Map(
params.measuredRows.map((row) => [routeKey(row.method, row.route), row]),
);
for (const route of params.routes) {
const key = routeKey(route.method, route.route);
if (rowsByKey.has(key)) {
rowsByKey.set(key, {
...rowsByKey.get(key)!,
controllerFile: route.controllerFile,
});
continue;
}
rowsByKey.set(key, {
method: route.method,
route: route.route,
controllerFile: route.controllerFile,
source: 'none',
samples: 0,
avgMs: null,
p50Ms: null,
p95Ms: null,
p99Ms: null,
maxMs: null,
errorRatePercentage: null,
queryCountP95: null,
mongooseDurationP95Ms: null,
docsReturnedP95: null,
hydratedDocsReturnedP95: null,
status: 'no-samples',
});
}
return [...rowsByKey.values()].sort(compareReportRows);
}
export function formatMarkdownReport(params: {
rows: EndpointReportRow[];
source: ReportSource;
since: string;
notes?: string[];
}): string {
const sampled = params.rows.filter((row) => row.samples > 0);
const noSamples = params.rows.length - sampled.length;
const slow = sampled.filter((row) => row.status === 'slow').length;
const documentHeavy = sampled.filter(
(row) => row.status === 'document-heavy',
).length;
const lines = [
'# API Performance Report',
'',
`- Source: ${params.source}`,
`- Window: ${params.since}`,
`- Routes: ${params.rows.length}`,
`- Sampled routes: ${sampled.length}`,
`- No-sample routes: ${noSamples}`,
`- Slow routes: ${slow}`,
`- Document-heavy routes: ${documentHeavy}`,
];
if (params.notes?.length) {
lines.push('', '## Notes', '');
for (const note of params.notes) lines.push(`- ${note}`);
}
lines.push(
'',
'| Method | Route | Samples | p95 ms | p99 ms | Avg ms | Error % | Query p95 | Docs p95 | Hydrated p95 | Status |',
'|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---|',
);
for (const row of params.rows) {
lines.push(
[
`| ${row.method}`,
markdownCell(row.route),
String(row.samples),
formatNumber(row.p95Ms),
formatNumber(row.p99Ms),
formatNumber(row.avgMs),
formatNumber(row.errorRatePercentage),
formatNumber(row.queryCountP95),
formatNumber(row.docsReturnedP95),
formatNumber(row.hydratedDocsReturnedP95),
`${row.status} |`,
].join(' | '),
);
}
return `${lines.join('\n')}\n`;
}
export function buildNewRelicCustomEventNrql(
appName: string,
since: string,
): string {
return [
'FROM ApiRequestPerformance',
'SELECT count(*) AS samples,',
'average(durationMs) AS avgDurationMs,',
'percentile(durationMs, 50, 95, 99) AS durationPercentilesMs,',
'max(durationMs) AS maxDurationMs,',
'percentage(count(*), WHERE isError IS true) AS errorRatePercentage,',
'percentile(queryCount, 95) AS queryCountPercentiles,',
'percentile(docsReturned, 95) AS docsReturnedPercentiles,',
'percentile(hydratedDocsReturned, 95) AS hydratedDocsReturnedPercentiles,',
'percentile(mongooseDurationMs, 95) AS mongooseDurationPercentiles',
`WHERE appName = '${escapeNrqlString(appName)}'`,
'FACET method, route',
`SINCE ${since}`,
'LIMIT MAX',
].join(' ');
}
export function buildNewRelicTransactionNrql(
appName: string,
since: string,
): string {
return [
'FROM Transaction',
'SELECT count(*) AS samples,',
'average(duration) AS avgDurationSec,',
'percentile(duration, 50, 95, 99) AS durationPercentilesSec,',
'max(duration) AS maxDurationSec,',
'percentage(count(*), WHERE error IS true) AS errorRatePercentage',
`WHERE appName = '${escapeNrqlString(appName)}'`,
'FACET name',
`SINCE ${since}`,
'LIMIT MAX',
].join(' ');
}
function summarizeRequestEvents(
route: ApiRoute,
events: ApiRequestPerformanceEvent[],
options: {
source: ReportSource;
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
},
): EndpointReportRow {
const row: EndpointReportRow = {
method: route.method,
route: route.route,
controllerFile: route.controllerFile,
source: events.length > 0 ? options.source : 'none',
samples: events.length,
avgMs: average(events.map((event) => event.durationMs)),
p50Ms: percentile(
events.map((event) => event.durationMs),
50,
),
p95Ms: percentile(
events.map((event) => event.durationMs),
95,
),
p99Ms: percentile(
events.map((event) => event.durationMs),
99,
),
maxMs: max(events.map((event) => event.durationMs)),
errorRatePercentage:
events.length > 0
? (events.filter((event) => event.isError).length / events.length) * 100
: null,
queryCountP95: percentile(
events.map((event) => event.queryCount),
95,
),
mongooseDurationP95Ms: percentile(
events.map((event) => event.mongooseDurationMs),
95,
),
docsReturnedP95: percentile(
events.map((event) => event.docsReturned),
95,
),
hydratedDocsReturnedP95: percentile(
events.map((event) => event.hydratedDocsReturned),
95,
),
status: 'ok',
};
row.status = classifyRow(row, options);
return row;
}
function newRelicCustomResultToRow(
result: Record<string, unknown>,
options: {
source: ReportSource;
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
},
): EndpointReportRow | null {
const facet = result.facet;
const method = Array.isArray(facet) ? String(facet[0] ?? '') : undefined;
const route = Array.isArray(facet) ? String(facet[1] ?? '') : undefined;
if (!method || !route) return null;
const row: EndpointReportRow = {
method,
route: normalizeRoute(route),
source: 'newrelic-custom',
samples: numberField(result.samples),
avgMs: numberOrNull(result.avgDurationMs),
p50Ms: percentileField(result.durationPercentilesMs, 50),
p95Ms: percentileField(result.durationPercentilesMs, 95),
p99Ms: percentileField(result.durationPercentilesMs, 99),
maxMs: numberOrNull(result.maxDurationMs),
errorRatePercentage: numberOrNull(result.errorRatePercentage),
queryCountP95: percentileField(result.queryCountPercentiles, 95),
mongooseDurationP95Ms: percentileField(
result.mongooseDurationPercentiles,
95,
),
docsReturnedP95: percentileField(result.docsReturnedPercentiles, 95),
hydratedDocsReturnedP95: percentileField(
result.hydratedDocsReturnedPercentiles,
95,
),
status: 'ok',
};
row.status = classifyRow(row, options);
return row;
}
function newRelicTransactionResultToRow(
result: Record<string, unknown>,
options: {
source: ReportSource;
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
},
): EndpointReportRow | null {
const parsed = parseTransactionName(String(result.facet ?? ''));
if (!parsed) return null;
const row: EndpointReportRow = {
method: parsed.method,
route: parsed.route,
source: 'newrelic-transaction',
samples: numberField(result.samples),
avgMs: secondsToMs(result.avgDurationSec),
p50Ms: secondsToMs(percentileField(result.durationPercentilesSec, 50)),
p95Ms: secondsToMs(percentileField(result.durationPercentilesSec, 95)),
p99Ms: secondsToMs(percentileField(result.durationPercentilesSec, 99)),
maxMs: secondsToMs(result.maxDurationSec),
errorRatePercentage: numberOrNull(result.errorRatePercentage),
queryCountP95: null,
mongooseDurationP95Ms: null,
docsReturnedP95: null,
hydratedDocsReturnedP95: null,
status: 'ok',
};
row.status = classifyRow(row, options);
return row;
}
function parseTransactionName(
name: string,
): { method: string; route: string } | null {
const match = name.match(
/\b(GET|POST|PATCH|PUT|DELETE|HEAD|OPTIONS|ALL)[\s/]+(\/.*)$/i,
);
if (!match) return null;
return {
method: match[1].toUpperCase(),
route: normalizeRoute(match[2]),
};
}
function classifyRow(
row: EndpointReportRow,
options: {
p95BudgetMs: number;
docsReturnedP95Budget: number;
hydratedDocsReturnedP95Budget: number;
},
): EndpointReportRow['status'] {
if (row.samples === 0) return 'no-samples';
if (row.p95Ms !== null && row.p95Ms > options.p95BudgetMs) return 'slow';
if (
(row.docsReturnedP95 !== null &&
row.docsReturnedP95 > options.docsReturnedP95Budget) ||
(row.hydratedDocsReturnedP95 !== null &&
row.hydratedDocsReturnedP95 >
options.hydratedDocsReturnedP95Budget)
) {
return 'document-heavy';
}
return 'ok';
}
async function listControllerFiles(rootDir: string): Promise<string[]> {
const entries = await readdir(rootDir, { withFileTypes: true });
const files = await Promise.all(
entries.map(async (entry) => {
const fullPath = path.join(rootDir, entry.name);
if (entry.isDirectory()) return listControllerFiles(fullPath);
return entry.isFile() && entry.name.endsWith('.controller.ts')
? [fullPath]
: [];
}),
);
return files.flat();
}
function extractDecoratorStringArgument(
source: string,
decoratorName: string,
): string | undefined {
const regex = new RegExp(`@${decoratorName}\\s*\\(([\\s\\S]*?)\\)`);
const match = source.match(regex);
if (!match) return undefined;
return extractFirstStringLiteral(match[1]) ?? '';
}
function extractFirstStringLiteral(input: string): string | undefined {
const match = input.match(/['"`]([^'"`]*)['"`]/);
return match?.[1];
}
function joinRouteParts(basePath: string, routePath: string): string {
return [basePath, routePath]
.filter((part) => part !== '')
.join('/')
.replace(/\/+/g, '/');
}
function normalizeRoute(route: string): string {
const normalized = route.startsWith('/') ? route : `/${route}`;
return normalized.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
}
function routeKey(method: string, route: string): string {
return `${method.toUpperCase()} ${normalizeRoute(route)}`;
}
function compareReportRows(left: EndpointReportRow, right: EndpointReportRow) {
return (
left.route.localeCompare(right.route) ||
left.method.localeCompare(right.method)
);
}
function percentile(values: number[], percentileValue: number): number | null {
if (values.length === 0) return null;
const sorted = [...values].sort((left, right) => left - right);
const index = Math.ceil((percentileValue / 100) * sorted.length) - 1;
return sorted[Math.max(0, Math.min(sorted.length - 1, index))];
}
function average(values: number[]): number | null {
if (values.length === 0) return null;
return values.reduce((acc, value) => acc + value, 0) / values.length;
}
function max(values: number[]): number | null {
if (values.length === 0) return null;
return Math.max(...values);
}
function percentileField(value: unknown, percentileValue: number): number | null {
if (!value || typeof value !== 'object') return null;
const map = value as Record<string, unknown>;
return numberOrNull(map[String(percentileValue)] ?? map[percentileValue]);
}
function numberField(value: unknown): number {
return numberOrNull(value) ?? 0;
}
function numberOrNull(value: unknown): number | null {
return typeof value === 'number' && Number.isFinite(value) ? value : null;
}
function secondsToMs(value: unknown): number | null {
const seconds = numberOrNull(value);
return seconds === null ? null : seconds * 1000;
}
function formatNumber(value: number | null): string {
return value === null ? '-' : value.toFixed(value >= 100 ? 0 : 1);
}
function markdownCell(value: string): string {
return value.replace(/\|/g, '\\|');
}
function escapeNrqlString(value: string): string {
return value.replace(/'/g, "\\'");
}
function parseArgs(argv: string[]): ReportOptions {
const args = new Map<string, string | boolean>();
for (const arg of argv) {
if (!arg.startsWith('--')) continue;
const [key, rawValue] = arg.slice(2).split('=', 2);
args.set(key, rawValue ?? true);
}
const source = stringArg(args, 'source', defaultReportSource()) as ReportSource;
return {
source,
rootDir: path.resolve(
stringArg(args, 'root-dir', path.join(process.cwd(), 'src')),
),
inputFile: path.resolve(
stringArg(
args,
'input',
process.env.API_PERF_LOCAL_EVENT_FILE ??
'/tmp/lolympus-api-performance.ndjson',
),
),
outputFile: optionalStringArg(args, 'output'),
format: stringArg(args, 'format', 'markdown') as 'markdown' | 'json',
p95BudgetMs: numberArg(args, 'p95-budget-ms', 300),
docsReturnedP95Budget: numberArg(args, 'docs-returned-p95-budget', 500),
hydratedDocsReturnedP95Budget: numberArg(
args,
'hydrated-docs-returned-p95-budget',
0,
),
since: stringArg(args, 'since', '1 day ago'),
newRelicAccountId:
optionalStringArg(args, 'new-relic-account-id') ??
process.env.NEW_RELIC_ACCOUNT_ID,
newRelicApiKey:
optionalStringArg(args, 'new-relic-api-key') ??
process.env.NEW_RELIC_USER_API_KEY ??
process.env.NEW_RELIC_API_KEY,
newRelicAppName:
optionalStringArg(args, 'new-relic-app-name') ??
process.env.NEW_RELIC_APP_NAME ??
'lolympus',
routesOnly: args.has('routes-only'),
};
}
function defaultReportSource(): ReportSource {
return process.env.NEW_RELIC_ACCOUNT_ID &&
(process.env.NEW_RELIC_USER_API_KEY || process.env.NEW_RELIC_API_KEY)
? 'newrelic-custom'
: 'local';
}
function stringArg(
args: Map<string, string | boolean>,
name: string,
defaultValue: string,
): string {
const value = args.get(name);
return typeof value === 'string' && value !== '' ? value : defaultValue;
}
function optionalStringArg(
args: Map<string, string | boolean>,
name: string,
): string | undefined {
const value = args.get(name);
return typeof value === 'string' && value !== '' ? value : undefined;
}
function numberArg(
args: Map<string, string | boolean>,
name: string,
defaultValue: number,
): number {
const value = Number(stringArg(args, name, String(defaultValue)));
return Number.isFinite(value) ? value : defaultValue;
}
async function buildReport(options: ReportOptions): Promise<string> {
const routes = await discoverApiRoutes(options.rootDir);
if (options.routesOnly) {
return `${JSON.stringify(routes, null, 2)}\n`;
}
const measuredRows =
options.source === 'local'
? buildEndpointReportFromLocalEvents({
routes,
events: await readLocalPerformanceEvents(options.inputFile),
p95BudgetMs: options.p95BudgetMs,
docsReturnedP95Budget: options.docsReturnedP95Budget,
hydratedDocsReturnedP95Budget:
options.hydratedDocsReturnedP95Budget,
})
: await fetchNewRelicEndpointRows({
source: options.source,
accountId: requireOption(
options.newRelicAccountId,
'NEW_RELIC_ACCOUNT_ID',
),
apiKey: requireOption(options.newRelicApiKey, 'NEW_RELIC_API_KEY'),
appName: options.newRelicAppName,
since: options.since,
p95BudgetMs: options.p95BudgetMs,
docsReturnedP95Budget: options.docsReturnedP95Budget,
hydratedDocsReturnedP95Budget:
options.hydratedDocsReturnedP95Budget,
});
const notes =
options.source === 'newrelic-custom' && measuredRows.length === 0
? [
'No ApiRequestPerformance custom events were found for this window and appName.',
'Custom events are created only after the API runs with API_PERF_OBSERVABILITY_ENABLED=true and API_PERF_NEW_RELIC_REQUEST_EVENTS_ENABLED=true.',
'Use --source=newrelic-transaction for historical latency before custom instrumentation was enabled.',
]
: [];
const rows = mergeRowsWithManifest({
routes,
measuredRows,
fallbackSource: options.source,
p95BudgetMs: options.p95BudgetMs,
docsReturnedP95Budget: options.docsReturnedP95Budget,
hydratedDocsReturnedP95Budget: options.hydratedDocsReturnedP95Budget,
});
return options.format === 'json'
? `${JSON.stringify(rows, null, 2)}\n`
: formatMarkdownReport({
rows,
source: options.source,
since: options.since,
notes,
});
}
function requireOption(value: string | undefined, name: string): string {
if (value) return value;
throw new Error(`${name} is required for New Relic report sources.`);
}
async function main() {
const options = parseArgs(process.argv.slice(2));
const report = await buildReport(options);
if (options.outputFile) {
await writeFile(path.resolve(options.outputFile), report);
return;
}
process.stdout.write(report);
}
if (require.main === module) {
void main().catch((error: unknown) => {
process.stderr.write(
`${error instanceof Error ? error.message : String(error)}\n`,
);
process.exitCode = 1;
});
}