@eserstack/logging 0.0.0-stage → 5.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +13 -0
- package/README.md +585 -2
- package/dist/category.d.ts +151 -0
- package/dist/category.js +244 -0
- package/dist/config.d.ts +95 -0
- package/dist/config.js +259 -0
- package/dist/context.d.ts +131 -0
- package/dist/context.js +213 -0
- package/dist/ffi-client.d.ts +19 -0
- package/dist/ffi-client.js +20 -0
- package/dist/filters.d.ts +185 -0
- package/dist/filters.js +263 -0
- package/dist/formatters.d.ts +40 -0
- package/dist/formatters.js +215 -0
- package/dist/go-logger.d.ts +38 -0
- package/dist/go-logger.js +55 -0
- package/dist/logger.d.ts +253 -0
- package/dist/logger.js +532 -0
- package/dist/mod.d.ts +60 -0
- package/dist/mod.js +63 -0
- package/dist/resolve-config.d.ts +38 -0
- package/dist/resolve-config.js +97 -0
- package/dist/serialize.d.ts +38 -0
- package/dist/serialize.js +82 -0
- package/dist/sinks.d.ts +117 -0
- package/dist/sinks.js +193 -0
- package/dist/tracer.d.ts +114 -0
- package/dist/tracer.js +198 -0
- package/dist/types.d.ts +133 -0
- package/dist/types.js +35 -0
- package/package.json +42 -3
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/** A level the Go logger accepts. */
|
|
2
|
+
export type GoLogLevel = "debug" | "info" | "warn" | "error";
|
|
3
|
+
/** Options for `createGoLogger()`, passed to the Go library as they are. */
|
|
4
|
+
export type GoLoggerOptions = {
|
|
5
|
+
/** The scope name written with each entry */
|
|
6
|
+
readonly scopeName?: string;
|
|
7
|
+
/** The lowest level the logger writes */
|
|
8
|
+
readonly level?: GoLogLevel;
|
|
9
|
+
/** The output format of each entry */
|
|
10
|
+
readonly format?: "json" | "text";
|
|
11
|
+
/** Whether each entry carries the source location */
|
|
12
|
+
readonly addSource?: boolean;
|
|
13
|
+
};
|
|
14
|
+
/** A handle to a logger in the Go library. */
|
|
15
|
+
export type GoLogger = {
|
|
16
|
+
/** Write a log entry. */
|
|
17
|
+
write(level: GoLogLevel, message: string, attrs?: Record<string, unknown>): void;
|
|
18
|
+
/** Release the Go handle. */
|
|
19
|
+
close(): void;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* Creates a Go-backed structured logger writing to stderr.
|
|
23
|
+
*
|
|
24
|
+
* If the native library is unavailable, returns a no-op logger.
|
|
25
|
+
*
|
|
26
|
+
* @param options - Logger configuration
|
|
27
|
+
* @returns A GoLogger handle
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* ```typescript
|
|
31
|
+
* import * as goLogger from "@eserstack/logging/go-logger";
|
|
32
|
+
*
|
|
33
|
+
* const log = await goLogger.createGoLogger({ scopeName: "myapp", level: "info" });
|
|
34
|
+
* log.write("info", "Server started", { port: 8080 });
|
|
35
|
+
* log.close();
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
export declare const createGoLogger: (options?: GoLoggerOptions) => Promise<GoLogger>;
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
import * as ffiClient from "./ffi-client.js";
|
|
3
|
+
import * as serialize from "./serialize.js";
|
|
4
|
+
/**
|
|
5
|
+
* Creates a Go-backed structured logger writing to stderr.
|
|
6
|
+
*
|
|
7
|
+
* If the native library is unavailable, returns a no-op logger.
|
|
8
|
+
*
|
|
9
|
+
* @param options - Logger configuration
|
|
10
|
+
* @returns A GoLogger handle
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```typescript
|
|
14
|
+
* import * as goLogger from "@eserstack/logging/go-logger";
|
|
15
|
+
*
|
|
16
|
+
* const log = await goLogger.createGoLogger({ scopeName: "myapp", level: "info" });
|
|
17
|
+
* log.write("info", "Server started", { port: 8080 });
|
|
18
|
+
* log.close();
|
|
19
|
+
* ```
|
|
20
|
+
*/
|
|
21
|
+
export const createGoLogger = async (options = {}) => {
|
|
22
|
+
await ffiClient.ensureLib();
|
|
23
|
+
const lib = ffiClient.getLib();
|
|
24
|
+
if (lib === null) {
|
|
25
|
+
// No-op fallback
|
|
26
|
+
return {
|
|
27
|
+
write: () => { },
|
|
28
|
+
close: () => { },
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
const result = lib.call("logCreate", { ...options });
|
|
32
|
+
if ((result.error !== undefined && result.error !== "") ||
|
|
33
|
+
result.handle === undefined) {
|
|
34
|
+
return { write: () => { }, close: () => { } };
|
|
35
|
+
}
|
|
36
|
+
const handle = result.handle;
|
|
37
|
+
return {
|
|
38
|
+
write(level, message, attrs) {
|
|
39
|
+
const lib2 = ffiClient.getLib();
|
|
40
|
+
if (lib2 === null)
|
|
41
|
+
return;
|
|
42
|
+
// Encoded here for the attribute replacer; the library sends a string
|
|
43
|
+
// request as it is.
|
|
44
|
+
const request = JSON.stringify({ handle, level, message, attrs }, serialize.jsonReplacer);
|
|
45
|
+
lib2.call("logWrite", request);
|
|
46
|
+
},
|
|
47
|
+
close() {
|
|
48
|
+
const lib2 = ffiClient.getLib();
|
|
49
|
+
if (lib2 === null)
|
|
50
|
+
return;
|
|
51
|
+
// logClose takes the bare handle.
|
|
52
|
+
lib2.call("logClose", handle);
|
|
53
|
+
},
|
|
54
|
+
};
|
|
55
|
+
};
|
package/dist/logger.d.ts
ADDED
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
import * as logging from "@eserstack/standards/logging";
|
|
2
|
+
import type { Category } from "./types.ts";
|
|
3
|
+
/** The lowest severity a logger writes when no configuration sets one. */
|
|
4
|
+
export declare const DEFAULT_LEVEL: logging.Severity;
|
|
5
|
+
/**
|
|
6
|
+
* Logger class with hierarchical category support.
|
|
7
|
+
*/
|
|
8
|
+
export declare class Logger implements logging.Logger {
|
|
9
|
+
#private;
|
|
10
|
+
/** Hierarchical category of this logger */
|
|
11
|
+
readonly category: Category;
|
|
12
|
+
/** Parent logger (null for root loggers) */
|
|
13
|
+
readonly parent: Logger | null;
|
|
14
|
+
/**
|
|
15
|
+
* Creates a logger. Most code calls `getLogger()` instead, which returns the
|
|
16
|
+
* cached logger for a category.
|
|
17
|
+
*
|
|
18
|
+
* @param loggerCategory - Category as an array or a dot-separated string
|
|
19
|
+
* @param parent - The logger this one was derived from, if any
|
|
20
|
+
* @param properties - Properties added to every record this logger writes
|
|
21
|
+
*/
|
|
22
|
+
constructor(loggerCategory: Category | string, parent?: Logger | null, properties?: Record<string, unknown>);
|
|
23
|
+
/**
|
|
24
|
+
* Creates a child logger with an extended category.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```typescript
|
|
28
|
+
* import * as logging from "@eserstack/logging";
|
|
29
|
+
*
|
|
30
|
+
* const logger = logging.logger.getLogger(["myapp"]);
|
|
31
|
+
* const http = logger.getChild("http"); // ["myapp", "http"]
|
|
32
|
+
*
|
|
33
|
+
* // ["myapp", "http", "request", "handler"]
|
|
34
|
+
* const handler = http.getChild(["request", "handler"]);
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
getChild(subcategory: string | Category): Logger;
|
|
38
|
+
/**
|
|
39
|
+
* Returns a new logger with preset properties.
|
|
40
|
+
* Properties are merged with existing ones.
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* ```typescript
|
|
44
|
+
* import * as logging from "@eserstack/logging";
|
|
45
|
+
*
|
|
46
|
+
* const logger = logging.logger.getLogger(["myapp"]);
|
|
47
|
+
* const requestLogger = logger.with({ requestId: "abc-123" });
|
|
48
|
+
* await requestLogger.info("Processing"); // includes requestId
|
|
49
|
+
* ```
|
|
50
|
+
*/
|
|
51
|
+
with(properties: Record<string, unknown>): Logger;
|
|
52
|
+
/**
|
|
53
|
+
* Gets the logger name as a dot-separated string.
|
|
54
|
+
* For backward compatibility with old code.
|
|
55
|
+
*/
|
|
56
|
+
get loggerName(): string;
|
|
57
|
+
/**
|
|
58
|
+
* Converts a value to a string for logging.
|
|
59
|
+
*/
|
|
60
|
+
asString(data: unknown, isProperty?: boolean): string;
|
|
61
|
+
/**
|
|
62
|
+
* Logs a message at the given severity level. When sinks are configured for
|
|
63
|
+
* this logger's category, the record goes to them only, after the
|
|
64
|
+
* configured filters. Otherwise it goes to Go, degrading to a local console
|
|
65
|
+
* sink when the backend is unavailable or rejects the record. Never throws:
|
|
66
|
+
* a logging fault, a failing sink or filter included, must not crash the
|
|
67
|
+
* caller.
|
|
68
|
+
*
|
|
69
|
+
* The record is written synchronously, before `log()` returns, and a sink
|
|
70
|
+
* that returns a promise is not awaited; `log()` stays async so a message
|
|
71
|
+
* function that throws still rejects the promise.
|
|
72
|
+
*/
|
|
73
|
+
log<T>(severity: logging.Severity, message: (T extends (...args: ReadonlyArray<any>) => any ? never : T) | (() => T), ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
74
|
+
/**
|
|
75
|
+
* Logs a debug message built by a function. The function runs only when the
|
|
76
|
+
* Debug level is enabled for this logger.
|
|
77
|
+
*
|
|
78
|
+
* @param message - Builds the message; its result is logged
|
|
79
|
+
* @param args - Extra values written with the record
|
|
80
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
81
|
+
*/
|
|
82
|
+
debug<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
83
|
+
/**
|
|
84
|
+
* Logs a debug message.
|
|
85
|
+
*
|
|
86
|
+
* @param message - The message; a string, or a value converted to one
|
|
87
|
+
* @param args - Extra values written with the record
|
|
88
|
+
* @returns The message it was given
|
|
89
|
+
*/
|
|
90
|
+
debug<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
91
|
+
/**
|
|
92
|
+
* Logs an info message built by a function. The function runs only when the
|
|
93
|
+
* Info level is enabled for this logger.
|
|
94
|
+
*
|
|
95
|
+
* @param message - Builds the message; its result is logged
|
|
96
|
+
* @param args - Extra values written with the record
|
|
97
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
98
|
+
*/
|
|
99
|
+
info<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
100
|
+
/**
|
|
101
|
+
* Logs an info message.
|
|
102
|
+
*
|
|
103
|
+
* @param message - The message; a string, or a value converted to one
|
|
104
|
+
* @param args - Extra values written with the record
|
|
105
|
+
* @returns The message it was given
|
|
106
|
+
*/
|
|
107
|
+
info<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
108
|
+
/**
|
|
109
|
+
* Logs a warning message built by a function. The function runs only when the
|
|
110
|
+
* Warning level is enabled for this logger.
|
|
111
|
+
*
|
|
112
|
+
* @param message - Builds the message; its result is logged
|
|
113
|
+
* @param args - Extra values written with the record
|
|
114
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
115
|
+
*/
|
|
116
|
+
warn<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
117
|
+
/**
|
|
118
|
+
* Logs a warning message.
|
|
119
|
+
*
|
|
120
|
+
* @param message - The message; a string, or a value converted to one
|
|
121
|
+
* @param args - Extra values written with the record
|
|
122
|
+
* @returns The message it was given
|
|
123
|
+
*/
|
|
124
|
+
warn<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
125
|
+
/**
|
|
126
|
+
* Logs an error message built by a function. The function runs only when the
|
|
127
|
+
* Error level is enabled for this logger.
|
|
128
|
+
*
|
|
129
|
+
* @param message - Builds the message; its result is logged
|
|
130
|
+
* @param args - Extra values written with the record
|
|
131
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
132
|
+
*/
|
|
133
|
+
error<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
134
|
+
/**
|
|
135
|
+
* Logs an error message.
|
|
136
|
+
*
|
|
137
|
+
* @param message - The message; a string, or a value converted to one
|
|
138
|
+
* @param args - Extra values written with the record
|
|
139
|
+
* @returns The message it was given
|
|
140
|
+
*/
|
|
141
|
+
error<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
142
|
+
/**
|
|
143
|
+
* Logs a critical message built by a function. The function runs only when the
|
|
144
|
+
* Critical level is enabled for this logger.
|
|
145
|
+
*
|
|
146
|
+
* @param message - Builds the message; its result is logged
|
|
147
|
+
* @param args - Extra values written with the record
|
|
148
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
149
|
+
*/
|
|
150
|
+
critical<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
151
|
+
/**
|
|
152
|
+
* Logs a critical message.
|
|
153
|
+
*
|
|
154
|
+
* @param message - The message; a string, or a value converted to one
|
|
155
|
+
* @param args - Extra values written with the record
|
|
156
|
+
* @returns The message it was given
|
|
157
|
+
*/
|
|
158
|
+
critical<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
159
|
+
/**
|
|
160
|
+
* Logs an emergency message built by a function. The function runs only when the
|
|
161
|
+
* Emergency level is enabled for this logger.
|
|
162
|
+
*
|
|
163
|
+
* @param message - Builds the message; its result is logged
|
|
164
|
+
* @param args - Extra values written with the record
|
|
165
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
166
|
+
*/
|
|
167
|
+
emergency<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
168
|
+
/**
|
|
169
|
+
* Logs an emergency message.
|
|
170
|
+
*
|
|
171
|
+
* @param message - The message; a string, or a value converted to one
|
|
172
|
+
* @param args - Extra values written with the record
|
|
173
|
+
* @returns The message it was given
|
|
174
|
+
*/
|
|
175
|
+
emergency<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
176
|
+
/**
|
|
177
|
+
* Logs an alert message built by a function. The function runs only when the
|
|
178
|
+
* Alert level is enabled for this logger.
|
|
179
|
+
*
|
|
180
|
+
* @param message - Builds the message; its result is logged
|
|
181
|
+
* @param args - Extra values written with the record
|
|
182
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
183
|
+
*/
|
|
184
|
+
alert<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
185
|
+
/**
|
|
186
|
+
* Logs an alert message.
|
|
187
|
+
*
|
|
188
|
+
* @param message - The message; a string, or a value converted to one
|
|
189
|
+
* @param args - Extra values written with the record
|
|
190
|
+
* @returns The message it was given
|
|
191
|
+
*/
|
|
192
|
+
alert<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
193
|
+
/**
|
|
194
|
+
* Logs a notice message built by a function. The function runs only when the
|
|
195
|
+
* Notice level is enabled for this logger.
|
|
196
|
+
*
|
|
197
|
+
* @param message - Builds the message; its result is logged
|
|
198
|
+
* @param args - Extra values written with the record
|
|
199
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
200
|
+
*/
|
|
201
|
+
notice<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
202
|
+
/**
|
|
203
|
+
* Logs a notice message.
|
|
204
|
+
*
|
|
205
|
+
* @param message - The message; a string, or a value converted to one
|
|
206
|
+
* @param args - Extra values written with the record
|
|
207
|
+
* @returns The message it was given
|
|
208
|
+
*/
|
|
209
|
+
notice<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
210
|
+
/**
|
|
211
|
+
* Logs a trace message (most verbose level) built by a function. The function runs only when the
|
|
212
|
+
* Trace level is enabled for this logger.
|
|
213
|
+
*
|
|
214
|
+
* @param message - Builds the message; its result is logged
|
|
215
|
+
* @param args - Extra values written with the record
|
|
216
|
+
* @returns The function's result, or `undefined` when the level is off
|
|
217
|
+
*/
|
|
218
|
+
trace<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
|
|
219
|
+
/**
|
|
220
|
+
* Logs a trace message (most verbose level).
|
|
221
|
+
*
|
|
222
|
+
* @param message - The message; a string, or a value converted to one
|
|
223
|
+
* @param args - Extra values written with the record
|
|
224
|
+
* @returns The message it was given
|
|
225
|
+
*/
|
|
226
|
+
trace<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* Gets or creates a logger for the given category.
|
|
230
|
+
*
|
|
231
|
+
* @example
|
|
232
|
+
* ```typescript
|
|
233
|
+
* import * as logging from "@eserstack/logging";
|
|
234
|
+
*
|
|
235
|
+
* const logger = logging.logger.getLogger(["myapp", "http"]);
|
|
236
|
+
* await logger.info("Request received");
|
|
237
|
+
*
|
|
238
|
+
* // The same logger, from a dot-separated string
|
|
239
|
+
* const sameLogger = logging.logger.getLogger("myapp.http");
|
|
240
|
+
* ```
|
|
241
|
+
*/
|
|
242
|
+
export declare const getLogger: (loggerCategory: Category | string) => Logger;
|
|
243
|
+
/**
|
|
244
|
+
* Clears the logger instance cache.
|
|
245
|
+
* Useful for testing.
|
|
246
|
+
*/
|
|
247
|
+
export declare const clearLoggerCache: () => void;
|
|
248
|
+
/**
|
|
249
|
+
* Default logger instance (for backward compatibility).
|
|
250
|
+
* Uses the "default" category and console output.
|
|
251
|
+
*/
|
|
252
|
+
export declare const current: Logger;
|
|
253
|
+
export type { Category, LogRecord } from "./types.ts";
|