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 | * Replaces log.info with a 'noop'.Defaults to 'false'.
|
37 | */
|
38 | disableInfoLogger?: true | undefined;
|
39 |
|
40 | /**
|
41 | * Replaces log.error with a 'noop'.Defaults to 'false'.
|
42 | */
|
43 | disableErrorLogger?: true | undefined;
|
44 |
|
45 | /**
|
46 | * Set the printer to be used. Defaults to "pretty" when 'NODE_ENV===development',
|
47 | * "github-actions" when 'GITHUB_ACTIONS===true' and "ndjson" by default.
|
48 | */
|
49 | printer?: "pretty" | "ndjson" | "github-actions" | undefined;
|
50 |
|
51 | /**
|
52 | * The stream to write the logs to
|
53 | */
|
54 | stream?: NodeJS.WriteStream;
|
55 |
|
56 | /**
|
57 | * Context that should be logged in all log lines. e.g
|
58 | * a common request id.
|
59 | */
|
60 | ctx?: T;
|
61 | }
|
62 |
|
63 | /**
|
64 | * Create a new logger
|
65 | *
|
66 | */
|
67 | export function newLogger<T extends LoggerContext>(
|
68 | options?: LoggerOptions<T>,
|
69 | ): Logger;
|
70 |
|
71 | /**
|
72 | * Format bytes, with up to 2 digits after the decimal point, in a more human readable way
|
73 | * Support up to a pebibyte
|
74 | */
|
75 | export function bytesToHumanReadable(bytes?: number): string;
|
76 |
|
77 | /**
|
78 | * Prints the memory usage of the current process to the provided logger
|
79 | * For more info on the printed properties see:
|
80 | * https://nodejs.org/dist/latest-v13.x/docs/api/process.html#process_process_memoryusage
|
81 | */
|
82 | export function printProcessMemoryUsage(logger: Logger): void;
|
83 |
|
84 | /**
|
85 | * Basic timing and call information
|
86 | */
|
87 | export type InsightEventCall =
|
88 | | {
|
89 | type: "start" | "stop";
|
90 | name: string;
|
91 |
|
92 | /**
|
93 | * Time in milliseconds since some kind of epoch, this may be unix epoch or process start
|
94 | */
|
95 | time: number;
|
96 | }
|
97 | | InsightEventCall[];
|
98 |
|
99 | /**
|
100 | * Encapsulate the base information needed to dispatch events
|
101 | */
|
102 | export interface InsightEvent {
|
103 | log: Logger;
|
104 |
|
105 | signal?: AbortSignal;
|
106 |
|
107 | /**
|
108 | * If event is first event dispatched in chain
|
109 | */
|
110 | root: boolean;
|
111 |
|
112 | name?: string;
|
113 |
|
114 | callStack: InsightEventCall[];
|
115 | }
|
116 |
|
117 | /**
|
118 | * Create a new event from a single logger
|
119 | */
|
120 | export function newEvent(logger: Logger, signal?: AbortSignal): InsightEvent;
|
121 |
|
122 | /**
|
123 | * Create a 'child' event, reuses the logger, adds callstack to the passed event
|
124 | */
|
125 | export function newEventFromEvent(event: InsightEvent): InsightEvent;
|
126 |
|
127 | /**
|
128 | * Track event start times and set a name
|
129 | */
|
130 | export function eventStart(event: InsightEvent, name: string): void;
|
131 |
|
132 | /**
|
133 | * Rename event, can only be done if `eventStop` is not called yet.
|
134 | */
|
135 | export function eventRename(event: InsightEvent, name: string): void;
|
136 |
|
137 | /**
|
138 | * Track event stop, and log callStack if event#root === true
|
139 | */
|
140 | export function eventStop(event: InsightEvent): void;
|
141 |
|
142 | /**
|
143 | * Get the disk size (in bytes) and estimated row count for all tables and views.
|
144 | * To improve accuracy, run sql`ANALYZE` before this query, however make sure to read the
|
145 | * Postgres documentation for implications.
|
146 | *
|
147 | * Accepts the @compas/store based sql instance, but not strongly typed so we don't have the
|
148 | * dependency
|
149 | */
|
150 | export function postgresTableSizes(
|
151 | sql: any,
|
152 | ): Promise<Record<string, { diskSize: number; rowCount: number }>>;
|