smart-logging 1.0.0 → 1.0.2
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/README.md +109 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,2 +1,110 @@
|
|
|
1
1
|
# smart-logging
|
|
2
|
-
|
|
2
|
+
|
|
3
|
+
**Import it once. All your `console.*` logs become async-aware, pretty Pino logs with timestamps and file names—no other changes needed.**
|
|
4
|
+
|
|
5
|
+
Ideal when you just want to install a logger and let it handle every `console.log` in the project automatically.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install smart-logging
|
|
11
|
+
# or
|
|
12
|
+
yarn add smart-logging
|
|
13
|
+
# or
|
|
14
|
+
pnpm add smart-logging
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Why smart-logging?
|
|
18
|
+
|
|
19
|
+
| Before (plain `console.log`) | After (`smart-logging`) |
|
|
20
|
+
|---------------------------------------------------------------|----------------------------------------------------------------------------------------|
|
|
21
|
+
| Synchronous console writes can block during heavy logging | Console calls are deferred, keeping the event loop responsive |
|
|
22
|
+
| No timestamp, file, or line information | Every message includes ISO timestamp plus the originating file and line |
|
|
23
|
+
| Hard to trace errors—stack traces get lost in noisy output | Pretty Pino formatting preserves stacks and structures them cleanly |
|
|
24
|
+
| Integrating a logger means rewriting every `console.*` call | Import once; all existing `console.*` calls are patched automatically |
|
|
25
|
+
| Adding request/user metadata requires manual plumbing | `addTag` lets you annotate logs with any key/value scope (requestId, userId, etc.) |
|
|
26
|
+
| Existing projects without logging need major refactors | Drop in the package, import it in the root file, and you’re done |
|
|
27
|
+
|
|
28
|
+
## 1. Enable automatic logging
|
|
29
|
+
|
|
30
|
+
Do this **once** in the entry file of your app (the place where everything starts). After this, every file can keep using plain `console.log`, `console.error`, etc.—they are all patched automatically.
|
|
31
|
+
|
|
32
|
+
### ESM entry (e.g. `index.mjs`, `app.js` in `"type": "module"`)
|
|
33
|
+
|
|
34
|
+
```javascript
|
|
35
|
+
import 'smart-logging';
|
|
36
|
+
|
|
37
|
+
console.log('Server booting'); // timestamp + file:line
|
|
38
|
+
console.error(new Error('Oops')); // pretty stack trace
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Output:
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
2025-11-08 19:03:12.345 src/server.js:4 - Server booting
|
|
45
|
+
2025-11-08 19:03:12.352 src/server.js:5 - Oops
|
|
46
|
+
Error: Oops
|
|
47
|
+
at ...
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### CommonJS entry (e.g. `index.js` without `"type": "module"`)
|
|
51
|
+
|
|
52
|
+
```javascript
|
|
53
|
+
require('smart-logging');
|
|
54
|
+
|
|
55
|
+
console.info('Ready to roll');
|
|
56
|
+
console.warn('Using CommonJS');
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Output:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
2025-11-08 19:05:01.410 src/index.js:4 - Ready to roll
|
|
63
|
+
2025-11-08 19:05:01.411 src/index.js:5 - Using CommonJS
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
> Format: `[time] file:line - message`
|
|
67
|
+
|
|
68
|
+
That’s it. No manual logger instances, no extra function calls. Any module that uses `console` automatically inherits the new behaviour.
|
|
69
|
+
|
|
70
|
+
## 2. Optional tags (request IDs, users, feature flags…)
|
|
71
|
+
|
|
72
|
+
If you want to attach metadata to every log within a request, call `addTag`. You can use any key name (`requestId`, `userId`, `featureFlag`, `ip`, etc.). Values must be strings, numbers, booleans, or `null`—functions, objects, or arrays are rejected to keep logs safe and predictable.
|
|
73
|
+
|
|
74
|
+
```javascript
|
|
75
|
+
import 'smart-logging';
|
|
76
|
+
import { addTag, clearTags } from 'smart-logging';
|
|
77
|
+
|
|
78
|
+
addTag({ requestId: 'req-123', userId: 'user-99' });
|
|
79
|
+
console.log('Started processing');
|
|
80
|
+
|
|
81
|
+
addTag({ featureFlag: 'beta-payments' }); // merges with existing tags
|
|
82
|
+
console.warn('Customer in beta flow');
|
|
83
|
+
|
|
84
|
+
clearTags(); // reset when the request finishes
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Logs emitted inside that async call chain will include `requestId`, `userId`, and `featureFlag` automatically:
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
2025-11-08 19:03:45.112 requestId: req-123 userId: user-99 featureFlag: beta-payments api/orders.js:27 - Customer in beta flow
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## What smart-logging does for you
|
|
94
|
+
|
|
95
|
+
- 🪄 Monkey-patches `console.log`, `info`, `warn`, `error`, and `debug`
|
|
96
|
+
- 🕒 Adds ISO timestamps and prettified output via `pino-pretty`
|
|
97
|
+
- 📁 Prints the relative file name and line number that produced the log
|
|
98
|
+
- 🧵 Uses `AsyncLocalStorage` to carry tags across async boundaries
|
|
99
|
+
- 🚨 Hooks `uncaughtException`, `unhandledRejection`, `SIGINT`, and process exit to log cleanly
|
|
100
|
+
- 🧰 Works in both ESM and CommonJS projects out of the box
|
|
101
|
+
|
|
102
|
+
## Troubleshooting
|
|
103
|
+
|
|
104
|
+
- **Publishing:** bump the version before each `npm publish`.
|
|
105
|
+
- **Tags not showing:** ensure `addTag` runs before the first log in the async path.
|
|
106
|
+
- **Want custom formatting?** Fork and tweak `support/core/logger-core.cjs`.
|
|
107
|
+
|
|
108
|
+
## License
|
|
109
|
+
|
|
110
|
+
[ISC](./LICENSE)
|