1 | /**
|
2 | * The logger only has two severities:
|
3 | * - info
|
4 | * - error
|
5 | *
|
6 | * Either a log line is innocent enough and only provides debug information if needed, or
|
7 | * someone should be paged because something goes wrong. For example handled 500 errors
|
8 | * don't need any ones attention, but unhandled 500 errors do.
|
9 | *
|
10 | * The log functions {@ee Logger#info} only accepts a single parameter. This prevents magic
|
11 | * outputs like automatic concatenating strings in to a single message, or always having a top
|
12 | * level array as a message.
|
13 | */
|
14 | export interface Logger {
|
15 | /**
|
16 | * Check if this logger is using the pretty
|
17 | * printer or NDJSON printer
|
18 | */
|
19 | isProduction(): boolean;
|
20 |
|
21 | info(arg: any): void;
|
22 |
|
23 | error(arg: any): void;
|
24 | }
|
25 |
|
26 | /**
|
27 | * Context that should be logged in all log lines. e.g
|
28 | * a common request id.
|
29 | */
|
30 | interface LoggerContext {
|
31 | type?: string;
|
32 | }
|
33 |
|
34 | export interface LoggerOptions<T extends LoggerContext> {
|
35 | /**
|
36 | * Use the pretty formatter instead of the NDJSON formatter
|
37 | */
|
38 | pretty?: boolean;
|
39 |
|
40 | /**
|
41 | * The stream to write the logs to
|
42 | */
|
43 | stream?: NodeJS.WriteStream;
|
44 |
|
45 | /**
|
46 | * Context that should be logged in all log lines. e.g
|
47 | * a common request id.
|
48 | */
|
49 | ctx?: T;
|
50 | }
|
51 |
|
52 | /**
|
53 | * Create a new logger
|
54 | *
|
55 | */
|
56 | export function newLogger<T extends LoggerContext>(
|
57 | options?: LoggerOptions<T>,
|
58 | ): Logger;
|
59 |
|
60 | /**
|
61 | * Format bytes, with up to 2 digits after the decimal point, in a more human readable way
|
62 | * Support up to a pebibyte
|
63 | */
|
64 | export function bytesToHumanReadable(bytes?: number): string;
|
65 |
|
66 | /**
|
67 | * Prints the memory usage of the current process to the provided logger
|
68 | * For more info on the printed properties see:
|
69 | * https://nodejs.org/dist/latest-v13.x/docs/api/process.html#process_process_memoryusage
|
70 | */
|
71 | export function printProcessMemoryUsage(logger: Logger): void;
|
72 |
|
73 | /**
|
74 | * Basic timing and call information
|
75 | */
|
76 | export type InsightEventCall =
|
77 | | {
|
78 | type: "start" | "stop";
|
79 | name: string;
|
80 |
|
81 | /**
|
82 | * Time in milliseconds since some kind of epoch, this may be unix epoch or process start
|
83 | */
|
84 | time: number;
|
85 | }
|
86 | | InsightEventCall[];
|
87 |
|
88 | /**
|
89 | * Encapsulate the base information needed to dispatch events
|
90 | */
|
91 | export interface InsightEvent {
|
92 | log: Logger;
|
93 |
|
94 | signal?: AbortSignal;
|
95 |
|
96 | /**
|
97 | * If event is first event dispatched in chain
|
98 | */
|
99 | root: boolean;
|
100 |
|
101 | name?: string;
|
102 |
|
103 | callStack: InsightEventCall[];
|
104 | }
|
105 |
|
106 | /**
|
107 | * Create a new event from a single logger
|
108 | */
|
109 | export function newEvent(logger: Logger, signal?: AbortSignal): InsightEvent;
|
110 |
|
111 | /**
|
112 | * Create a 'child' event, reuses the logger, adds callstack to the passed event
|
113 | */
|
114 | export function newEventFromEvent(event: InsightEvent): InsightEvent;
|
115 |
|
116 | /**
|
117 | * Track event start times and set a name
|
118 | */
|
119 | export function eventStart(event: InsightEvent, name: string): void;
|
120 |
|
121 | /**
|
122 | * Rename event, can only be done if `eventStop` is not called yet.
|
123 | */
|
124 | export function eventRename(event: InsightEvent, name: string): void;
|
125 |
|
126 | /**
|
127 | * Track event stop, and log callStack if event#root === true
|
128 | */
|
129 | export function eventStop(event: InsightEvent): void;
|
130 |
|
131 | /**
|
132 | * Get the disk size (in bytes) and estimated row count for all tables and views.
|
133 | * To improve accuracy, run sql`ANALYZE` before this query, however make sure to read the
|
134 | * Postgres documentation for implications.
|
135 | *
|
136 | * Accepts the @compas/store based sql instance, but not strongly typed so we don't have the
|
137 | * dependency
|
138 | */
|
139 | export function postgresTableSizes(
|
140 | sql: any,
|
141 | ): Promise<Record<string, { diskSize: number; rowCount: number }>>;
|