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
```