UNPKG

3.6 kBTypeScriptView Raw
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 */
14export 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 */
30interface LoggerContext {
31 type?: string;
32}
33
34export 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.WritableStream;
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 */
56export 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 */
64export 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 */
71export function printProcessMemoryUsage(logger: Logger): void;
72
73/**
74 * Basic timing and call information
75 */
76export type EventCall =
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 | EventCall[];
87
88/**
89 * Encapsulate the base information needed to dispatch events
90 */
91export interface Event {
92 log: Logger;
93
94 /**
95 * If event is first event dispatched in chain
96 */
97 root: boolean;
98
99 name?: string;
100
101 callStack: EventCall[];
102}
103
104/**
105 * Create a new event from a single logger
106 */
107export function newEvent(logger: Logger): Event;
108
109/**
110 * Create a 'child' event, reuses the logger, adds callstack to the passed event
111 */
112export function newEventFromEvent(event: Event): Event;
113
114/**
115 * Track event start times and set a name
116 */
117export function eventStart(event: Event, name: string): void;
118
119/**
120 * Rename event, can only be done if `eventStop` is not called yet.
121 */
122export function eventRename(event: Event, name: string): void;
123
124/**
125 * Track event stop, and log callStack if event#root === true
126 */
127export function eventStop(event: Event): void;
128
129/**
130 * Create a test event.
131 * event.log.info is a noop by default, but can be enabled via the passed in options.
132 */
133export function newTestEvent(options?: { enabledLogs?: boolean }): Event;
134
135/**
136 * Get the disk size (in bytes) and estimated row count for all tables and views.
137 * To improve accuracy, run sql`ANALYZE` before this query, however make sure to read the
138 * Postgres documentation for implications.
139 *
140 * Accepts the @lbu/store based sql instance, but not strongly typed so we don't have the
141 * dependency
142 */
143export function postgresTableSizes(
144 sql: any,
145): Promise<Record<string, { diskSize: number; rowCount: number }>>;