0
# Pino
1
2
Pino is a very low overhead Node.js JSON logger that provides exceptional performance for structured logging applications. It offers comprehensive logging features including child loggers, custom serializers, redaction capabilities, and transport systems for processing logs in separate processes or threads. Designed with minimal resource consumption in mind, Pino delivers over 5x better performance than many alternatives while maintaining rich functionality for production logging needs.
3
4
## Package Information
5
6
- **Package Name**: pino
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install pino`
10
11
## Core Imports
12
13
```javascript
14
const pino = require('pino');
15
```
16
17
For ES modules:
18
19
```javascript
20
import pino from 'pino';
21
```
22
23
TypeScript imports:
24
25
```typescript
26
import pino, { Logger, LoggerOptions } from 'pino';
27
```
28
29
## Basic Usage
30
31
```javascript
32
const logger = pino();
33
34
// Basic logging
35
logger.info('hello world');
36
logger.error('this is at error level');
37
logger.info('the answer is %d', 42);
38
logger.info({ obj: 42 }, 'hello world');
39
40
// Child loggers
41
const child = logger.child({ a: 'property' });
42
child.info('hello child!');
43
44
// Level control
45
logger.level = 'debug';
46
logger.debug('this is a debug statement');
47
```
48
49
## Architecture
50
51
Pino is built around several key components:
52
53
- **Core Logger**: Main logging interface with configurable levels and output formatting
54
- **Child Loggers**: Inherit settings from parent while adding specific bindings
55
- **Transport System**: Worker thread-based log processing for high performance
56
- **Stream Management**: Optimized destination streams with sonic-boom for throughput
57
- **Serialization**: Custom object serializers and automatic redaction capabilities
58
- **Browser Support**: Compatible logging interface for browser environments
59
60
## Capabilities
61
62
### Core Logging Methods
63
64
Essential logging functionality with standard severity levels and structured output formatting.
65
66
```typescript { .api }
67
interface Logger {
68
fatal(obj?: object, msg?: string, ...args: any[]): void;
69
error(obj?: object, msg?: string, ...args: any[]): void;
70
warn(obj?: object, msg?: string, ...args: any[]): void;
71
info(obj?: object, msg?: string, ...args: any[]): void;
72
debug(obj?: object, msg?: string, ...args: any[]): void;
73
trace(obj?: object, msg?: string, ...args: any[]): void;
74
silent(obj?: object, msg?: string, ...args: any[]): void;
75
}
76
```
77
78
[Logger Methods](./logger-methods.md)
79
80
### Logger Configuration
81
82
Comprehensive configuration system for customizing logger behavior, output format, and performance characteristics.
83
84
```typescript { .api }
85
function pino(options?: LoggerOptions): Logger;
86
function pino(options: LoggerOptions, stream?: DestinationStream): Logger;
87
88
interface LoggerOptions {
89
level?: string;
90
name?: string;
91
timestamp?: boolean | TimeFn;
92
serializers?: { [key: string]: SerializerFn };
93
redact?: string[] | RedactOptions;
94
transport?: TransportOptions;
95
formatters?: FormattersOptions;
96
// ... additional options
97
}
98
```
99
100
[Logger Configuration](./logger-configuration.md)
101
102
### Child Loggers
103
104
Create specialized logger instances that inherit parent settings while adding contextual bindings.
105
106
```typescript { .api }
107
interface Logger {
108
child(bindings: Bindings, options?: ChildLoggerOptions): Logger;
109
bindings(): Bindings;
110
setBindings(bindings: Bindings): void;
111
}
112
113
type Bindings = Record<string, any>;
114
```
115
116
[Child Loggers](./child-loggers.md)
117
118
### Transport System
119
120
High-performance log processing system using worker threads for handling log output without blocking the main thread.
121
122
```typescript { .api }
123
function transport(options: TransportSingleOptions | TransportMultiOptions | TransportPipelineOptions): ThreadStream;
124
125
interface TransportSingleOptions {
126
target: string;
127
options?: Record<string, any>;
128
worker?: WorkerOptions;
129
}
130
```
131
132
[Transports](./transports.md)
133
134
### Stream Management
135
136
Optimized destination streams and multistream functionality for directing logs to multiple outputs.
137
138
```typescript { .api }
139
function destination(dest?: number | string | object | DestinationStream): SonicBoom;
140
function multistream(streams: StreamEntry[], opts?: MultiStreamOptions): MultiStreamRes;
141
142
interface StreamEntry {
143
stream: DestinationStream;
144
level?: string;
145
}
146
```
147
148
[Streams](./streams.md)
149
150
### Serializers and Redaction
151
152
Custom object serialization and sensitive data redaction for secure and structured log output.
153
154
```typescript { .api }
155
interface LoggerOptions {
156
serializers?: { [key: string]: SerializerFn };
157
redact?: string[] | RedactOptions;
158
}
159
160
type SerializerFn = (value: any) => any;
161
162
interface RedactOptions {
163
paths: string[];
164
censor?: string | ((value: any, path: string[]) => any);
165
remove?: boolean;
166
}
167
```
168
169
[Serializers](./serializers.md)
170
171
### Browser Compatibility
172
173
Browser-compatible logging with console output and transmit functionality for client-side applications.
174
175
```typescript { .api }
176
// Browser-specific options
177
interface BrowserOptions {
178
asObject?: boolean;
179
write?: WriteFn | { [level: string]: WriteFn };
180
serialize?: boolean | string[];
181
transmit?: {
182
level?: string;
183
send: (level: string, logEvent: LogEvent) => void;
184
};
185
}
186
```
187
188
[Browser Support](./browser.md)
189
190
## Static Properties
191
192
### Standard Serializers
193
194
```typescript { .api }
195
const stdSerializers: {
196
req: SerializerFn; // HTTP request serializer
197
res: SerializerFn; // HTTP response serializer
198
err: SerializerFn; // Error object serializer
199
};
200
```
201
202
### Log Levels
203
204
```typescript { .api }
205
const levels: {
206
values: { [level: string]: number };
207
labels: { [level: number]: string };
208
};
209
```
210
211
### Time Functions
212
213
```typescript { .api }
214
const stdTimeFunctions: {
215
epochTime: TimeFn; // Default timestamp format
216
nullTime: TimeFn; // No timestamp
217
isoTime: TimeFn; // ISO 8601 format
218
unixTime: TimeFn; // Unix timestamp
219
};
220
```
221
222
### Internal Symbols
223
224
```typescript { .api }
225
const symbols: {
226
readonly setLevelSym: unique symbol;
227
readonly getLevelSym: unique symbol;
228
readonly levelValSym: unique symbol;
229
readonly useLevelLabelsSym: unique symbol;
230
readonly mixinSym: unique symbol;
231
readonly lsCacheSym: unique symbol;
232
readonly chindingsSym: unique symbol;
233
readonly parsedChindingsSym: unique symbol;
234
readonly asJsonSym: unique symbol;
235
readonly writeSym: unique symbol;
236
readonly serializersSym: unique symbol;
237
readonly redactFmtSym: unique symbol;
238
readonly timeSym: unique symbol;
239
readonly timeSliceIndexSym: unique symbol;
240
readonly streamSym: unique symbol;
241
readonly stringifySym: unique symbol;
242
readonly stringifySafeSym: unique symbol;
243
readonly stringifiersSym: unique symbol;
244
readonly endSym: unique symbol;
245
readonly formatOptsSym: unique symbol;
246
readonly messageKeySym: unique symbol;
247
readonly errorKeySym: unique symbol;
248
readonly nestedKeySym: unique symbol;
249
readonly wildcardFirstSym: unique symbol;
250
readonly needsMetadataGsym: unique symbol;
251
readonly useOnlyCustomLevelsSym: unique symbol;
252
readonly formattersSym: unique symbol;
253
readonly hooksSym: unique symbol;
254
};
255
```
256
257
### Version Information
258
259
```typescript { .api }
260
const version: string; // Package version
261
```
262
263
## Types
264
265
```typescript { .api }
266
type Level = "fatal" | "error" | "warn" | "info" | "debug" | "trace";
267
type LevelWithSilent = Level | "silent";
268
269
type TimeFn = () => string;
270
type SerializerFn = (value: any) => any;
271
type WriteFn = (obj: object) => void;
272
273
interface Bindings {
274
[key: string]: any;
275
}
276
277
interface DestinationStream {
278
write(msg: string): void;
279
}
280
281
// TypeScript Generic Support for Custom Levels
282
type Logger<CustomLevels extends string = never, UseOnlyCustomLevels extends boolean = boolean> = BaseLogger & LoggerExtras<CustomLevels> & CustomLevelLogger<CustomLevels, UseOnlyCustomLevels>;
283
```
284
285
## TypeScript Support
286
287
Pino provides comprehensive TypeScript support including generic types for custom logging levels:
288
289
```typescript
290
// Standard logger
291
const logger: Logger = pino();
292
293
// Logger with custom levels
294
const customLogger: Logger<'audit' | 'security'> = pino({
295
customLevels: { audit: 35, security: 45 }
296
});
297
298
// Type-safe custom level usage
299
customLogger.audit('Audit event'); // TypeScript knows this method exists
300
customLogger.security('Security alert');
301
```