Skip to content

Commit 78b745d

Browse files
indexzeroindexzero
authored
✅✨👍 [PRE-RELEASE] winston@3.2.0 (#1576)
* Initial changelog for 3.2.0 * [doc] CHANGELOG.md through November 2018. * [doc] Entire CHANGELOG.md * [doc] Update Roadmap. * [dist] Regenerate package-lock.json with latest. * [doc] Add examples/quick-start.js and document it in `README.md` * [doc] Update README.md * [tiny doc] Correct order in TOC. * [doc] Tighten up CHANGELOG.md * [doc] Add note about 3.2.0 board.
1 parent a910c28 commit 78b745d

5 files changed

Lines changed: 558 additions & 173 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,118 @@
11
# CHANGELOG
22

3+
## v3.2.0 / 2018-01-26
4+
### SORRY IT TOO SO LONG EDITION
5+
6+
> **NOTE:** this was our first release using Github Projects. See the
7+
> [3.2.0 Release Project](https://github.com/orgs/winstonjs/projects/3).
8+
9+
### New Features!
10+
11+
- [#1471], (@kibertoad) Implement child loggers.
12+
- [#1462], (@drazisil) Add handleRejection support.
13+
- [#1555], (@DABH) Add fixes from [#1355] to unhandled rejection handler.
14+
- [#1418], (@mfrisbey) Precompile ES6 syntax before publishing to npm.
15+
- [#1533], (@kibertoad) Update to Babel 7.
16+
- [#1562], (@indexzero) [fix] Better handling of `new Error(string)`
17+
throughout the pipeline(s). (Fixes [#1338], [#1486]).
18+
19+
### Bug Fixes
20+
21+
- [#1355], (@DABH) Fix issues with ExceptionHandler (Fixes [#1289]).
22+
- [#1463], (@SerayaEryn) Bubble transport `warn` events up to logger in
23+
addition to `error`s.
24+
- [#1480], [#1503], (@SerayaEryn) File tailrolling fix.
25+
- [#1483], (@soldair) Assign log levels to un-bound functions.
26+
- [#1513], (@TilaTheHun0) Set maxListeners for Console transport.
27+
- [#1521], (@jamesbechet) Fix Transform from `readable-stream` using CRA.
28+
- [#1434], (@Kouzukii) Fixes logger.query function (regression from `3.0.0`)
29+
- [#1526], (@pixtron) Log file without .gz for tailable (Fixes [#1525]).
30+
- [#1559], (@eubnara) Fix typo related to `exitOnError`.
31+
- [#1556], (@adoyle-h) Support to create log directory if it doesn't exist
32+
for FileTransport.
33+
34+
#### New `splat` behavior
35+
36+
- [#1552], (@indexzero) Consistent handling of meta with (and without)
37+
interpolation in `winston` and `logform`.
38+
- [#1499], (@DABH) Provide all of `SPLAT` to formats (Fixes [#1485]).
39+
- [#1485], (@mpabst) Fixing off-by-one when using both meta and splat.
40+
41+
Previously `splat` would have added a `meta` property for any additional
42+
`info[SPLAT]` beyond the expected number of tokens.
43+
44+
**As of `logform@2.0.0`,** `format.splat` assumes additional splat paramters
45+
(aka "metas") are objects and merges enumerable properties into the `info`.
46+
e.g. **BE ADVISED** previous "metas" that _were not objects_ will very likely
47+
lead to odd behavior. e.g.
48+
49+
``` js
50+
const { createLogger, format, transports } = require('winston');
51+
const { splat } = format;
52+
const { MESSAGE, LEVEL, SPLAT } = require('triple-beam');
53+
54+
const logger = createLogger({
55+
format: format.combine(
56+
format.splat(),
57+
format.json()
58+
),
59+
transports: [new transports.Console()]
60+
});
61+
62+
// Expects two tokens, but four splat parameters provided.
63+
logger.info(
64+
'Let us %s for %j', // message
65+
'objects', // used for %s
66+
{ label: 'sure' }, // used for %j
67+
'lol', ['ok', 'why'] // Multiple additional meta values
68+
);
69+
70+
// winston < 3.2.0 && logform@1.x behavior:
71+
// Added "meta" property.
72+
//
73+
// { level: 'info',
74+
// message: 'Let us objects for {"label":"sure"}',
75+
// meta: ['lol', ['ok', 'why']],
76+
// [Symbol(level)]: 'info',
77+
// [Symbol(message)]: 'Let us %s for %j',
78+
// [Symbol(splat)]: [ 'objects', { label: 'sure' } ] }
79+
80+
// winston >= 3.2.0 && logform@2.x behavior: Enumerable properties
81+
// assigned into `info`. Since **strings and Arrays only have NUMERIC
82+
// enumerable properties we get this behavior!**
83+
//
84+
// { '0': 'ok',
85+
// '1': 'why',
86+
// '2': 'l',
87+
// level: 'info',
88+
// message: 'Let us objects for {"label":"sure"}',
89+
// [Symbol(level)]: 'info',
90+
// [Symbol(message)]: 'Let us %s for %j',
91+
// [Symbol(splat)]: [ 'objects', { label: 'sure' } ] }
92+
```
93+
94+
## Maintenance & Documentation
95+
96+
- Documentation Updates
97+
- [#1410], (@hakanostrom) Add docs reference to transport for Cloudant.
98+
- [#1467], (@SeryaEryn) Add fast-file-rotate transport to transport.md.
99+
- [#1488], (@adamcohen) Fix multi logger documentation.
100+
- [#1531], (@mapleeit) Add links to transports.
101+
- [#1548], (@ejmartin504) Fix `README.md` for awaiting logs.
102+
- [#1554], (@indexzero) Document the solution to [#1486] as by design.
103+
- Other small improvements: [#1509].
104+
- Improved TypeScript support
105+
- [#1470], (@jd-carroll) Export all transport options (Fixes [#1469]).
106+
- [#1474], (@jd-carroll) Correct import to avoid conflict (Fixed [#1472]).
107+
- [#1546], (@alewiahmed) Add consoleWarnLevels field to the
108+
`ConsoleTransportOptions` interface type definition.
109+
- [#1557], (@negezor) Add missing `child()` method.
110+
- Dependency management
111+
- [#1560], (@kibertoad) Update dependencies.
112+
- [#1512], (@SerayaEryn) Add node@11 and disallow failures on node@10.
113+
- [#1516], (@SerayaEryn) Update `readable-stream` to `v3.0.6`.
114+
- [#1534], (@kibertoad) Update `@types/node`, `nyc`, and `through2`.
115+
3116
## v3.1.0 / 2018-08-22
4117
### RELEASES ON A PLANE EDITION
5118

‎CONTRIBUTING.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Looking for somewhere to help? Checkout the [Roadmap](#roadmap) & help triage op
1313

1414
## What makes up `winston`?
1515

16-
As of `winston@3.0.0` the project has been broken out into a few modules:
16+
As of `winston@3` the project has been broken out into a few modules:
1717

1818
- [winston-transport]: `Transport` stream implementation & legacy `Transport` wrapper.
1919
- [logform]: All formats exports through `winston.format`
@@ -35,8 +35,8 @@ const logger = createLogger({
3535
format: combine(
3636
label({ label: 'right meow!' }),
3737
timestamp(),
38-
printf(nfo => {
39-
return `${nfo.timestamp} [${nfo.label}] ${nfo.level}: ${nfo.message}`;
38+
printf(({ level, message, lable, timestamp }) => {
39+
return `${timestamp} [${label}] ${level}: ${message}`;
4040
})
4141
),
4242
transports: [new transports.Console()]
@@ -69,22 +69,24 @@ This can be accomplished with using [custom formats](https://github.com/winstonj
6969

7070
Below is the list of items that make up the roadmap through `3.4.0`. We are actively triaging the open issues, so it is likely a few more critical path items will be added to this list before the next release goes out.
7171

72-
- [Version 3.2.0](#version-320)
73-
- [Version 3.3.0](#version-330)
74-
- [Version 3.4.0](#version-340)
72+
- [Version 3.3.0](#version-320)
73+
- [Version 3.4.0](#version-330)
74+
- [Version 3.5.0](#version-340)
7575

7676
## Legend
7777

7878
- [ ] Unstarted work.
7979
- [x] Finished work.
8080
- [-] Partially finished or in-progress work.
8181

82-
## Version `3.2.0`
82+
## Version `3.3.0`
8383

8484
### High priority issues (non-blocking)
85+
- [ ] Move `File` transport into `winston-file`.
8586
- [Browser support](https://github.com/winstonjs/winston/issues/287)
8687
- [ ] Unit tests for `webpack` & `rollup`
8788
- [ ] Replicate browser-only transpilation for `winston`, `winston-transport`, `triple-beam`.
89+
- [-] Full JSDoc coverage
8890
- Benchmarking for `File` and `Stream` transports:
8991
- [x] Benchmarking integration in `pino`.
9092
- [x] Upgrade `pino` to latest `winston`.
@@ -95,23 +97,23 @@ Below is the list of items that make up the roadmap through `3.4.0`. We are acti
9597
### Increased code & scenario coverage
9698
- [-] Replace all `vows`-based tests.
9799
- [-] `test/transports/*-test.js`
98-
- [ ] Code coverage tests above 80% for `winston` _(currently `~72%`)_.
100+
- [ ] Code coverage tests above 80% for `winston` _(currently `~70%`)_.
99101
- [-] Core scenarios covered in `abstract-winston-transport`.
102+
- [-] Full integration tests for all `logform` transports
100103

101104
### Communications / Compatibility
102105
- [ ] `README.md` for `winston-compat`.
103-
- [ ] All formats documented in `logform`.
104-
- [ ] All existing transports documented in `docs/transports.md`.
106+
- [ ] Update all transports documented in `docs/transports.md` for `winston@3`.
105107

106-
## Version `3.3.0`
108+
## Version `3.4.0`
107109

108110
### Querying, Streaming, Uncaught Exceptions
109111
- [-] Streaming
110112

111113
### Communications / Compatibility
112114
- [ ] `winstonjs.org` documentation site.
113115

114-
## Version `3.4.0`
116+
## Version `3.5.0`
115117

116118
### Querying, Streaming, Uncaught Exceptions
117119
- [-] Querying

‎README.md‎

Lines changed: 75 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ A logger for just about everything.
88

99
[![Join the chat at https://gitter.im/winstonjs/winston](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/winstonjs/winston?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
1010

11-
## winston@3.0.0
11+
## winston@3.2.0
1212

1313
See the [Upgrade Guide](UPGRADE-3.0.md) for more information. Bug reports and
1414
PRs welcome!
@@ -34,6 +34,13 @@ ensuring those APIs decoupled from the implementation of transport logging
3434
(i.e. how the logs are stored / indexed, see: [Adding Custom Transports]) to
3535
the API that they exposed to the programmer.
3636

37+
## Quick Start
38+
39+
TL;DR? Check out the [quick start example][quick-example] in `./examples/`.
40+
There are a number of other examples in [`./examples/*.js`][examples].
41+
Don't see an example you think should be there? Submit a pull request
42+
to add it!
43+
3744
## Usage
3845

3946
The recommended way to use `winston` is to create your own logger. The
@@ -43,7 +50,7 @@ simplest way to do this is using `winston.createLogger`:
4350
const logger = winston.createLogger({
4451
level: 'info',
4552
format: winston.format.json(),
46-
defaultMeta: {service: 'user-service'},
53+
defaultMeta: { service: 'user-service' },
4754
transports: [
4855
//
4956
// - Write to all logs with level `info` and below to `combined.log`
@@ -71,6 +78,10 @@ logger to use throughout your application if you so choose.
7178

7279
## Table of contents
7380

81+
* [Motivation](#motivation)
82+
* [Quick Start](#quick-start)
83+
* [Usage](#usage)
84+
* [Table of Contents](#table-of-contents)
7485
* [Logging](#logging)
7586
* [Creating your logger](#creating-your-own-logger)
7687
* [Streams, `objectMode`, and `info` objects](#streams-objectmode-and-info-objects)
@@ -129,14 +140,14 @@ const logger = winston.createLogger({
129140

130141
A logger accepts the following parameters:
131142

132-
| Name | Default | Description |
133-
| ------------- | ---------------------- | --------------- |
134-
| `level` | `'info'` | Log only if [`info.level`](#streams-objectmode-and-info-objects) less than or equal to this level |
135-
| `levels` | `winston.config.npm.levels` | Levels (and colors) representing log priorities |
136-
| `format` | `winston.format.json` | Formatting for `info` messages (see: [Formats]) |
137-
| `transports` | `[]` _(No transports)_ | Set of logging targets for `info` messages |
138-
| `exitOnError` | `true` | If false, handled exceptions will not cause `process.exit` |
139-
| `silent` | `false` | If true, all logs are suppressed |
143+
| Name | Default | Description |
144+
| ------------- | --------------------------- | --------------- |
145+
| `level` | `'info'` | Log only if [`info.level`](#streams-objectmode-and-info-objects) less than or equal to this level |
146+
| `levels` | `winston.config.npm.levels` | Levels (and colors) representing log priorities |
147+
| `format` | `winston.format.json` | Formatting for `info` messages (see: [Formats]) |
148+
| `transports` | `[]` _(No transports)_ | Set of logging targets for `info` messages |
149+
| `exitOnError` | `true` | If false, handled exceptions will not cause `process.exit` |
150+
| `silent` | `false` | If true, all logs are suppressed |
140151

141152
The levels provided to `createLogger` will be defined as convenience methods
142153
on the `logger` returned.
@@ -210,30 +221,63 @@ const childLogger = logger.child({ requestId: '451' });
210221

211222
In `winston`, both `Logger` and `Transport` instances are treated as
212223
[`objectMode`](https://nodejs.org/api/stream.html#stream_object_mode)
213-
streams that accept an `info` object. The `info` object represents a
214-
single log message. The object itself is mutable. Every `info` must
215-
have at least the `level` and `message` properties:
224+
streams that accept an `info` object.
225+
226+
The `info` parameter provided to a given format represents a single log
227+
message. The object itself is mutable. Every `info` must have at least the
228+
`level` and `message` properties:
216229

217230
``` js
218-
{
231+
const info = {
219232
level: 'info', // Level of the logging message
220233
message: 'Hey! Log something?' // Descriptive message being logged.
221-
}
234+
};
235+
```
236+
237+
Properties **besides level and message** are considered as "`meta`". i.e.:
238+
239+
``` js
240+
const { level, message, ...meta } = info;
222241
```
223242

224-
`winston.format` itself exposes several additional properties:
243+
Several of the formats in `logform` itself add additional properties:
225244

226-
- `splat`: string interpolation splat for `%d %s`-style messages.
227-
- `timestamp`: timestamp the message was received.
228-
- `label`: custom label associated with each message.
245+
| Property | Format added by | Description |
246+
| ----------- | --------------- | ----------- |
247+
| `splat` | `splat()` | String interpolation splat for `%d %s`-style messages. |
248+
| `timestamp` | `timestamp()` | timestamp the message was received. |
249+
| `label` | `label()` | Custom label associated with each message. |
250+
| `ms` | `ms()` | Number of milliseconds since the previous log message. |
229251

230252
As a consumer you may add whatever properties you wish – _internal state is
231253
maintained by `Symbol` properties:_
232254

233-
- `Symbol.for('level')` _**(READ-ONLY)**:_ equal to `level` property. Is
234-
treated as immutable by all code.
235-
- `Symbol.for('message'):` complete string message set by "finalizing
236-
formats": `json`, `logstash`, `printf`, `prettyPrint`, and `simple`.
255+
- `Symbol.for('level')` _**(READ-ONLY)**:_ equal to `level` property.
256+
**Is treated as immutable by all code.**
257+
- `Symbol.for('message'):` complete string message set by "finalizing formats":
258+
- `json`
259+
- `logstash`
260+
- `printf`
261+
- `prettyPrint`
262+
- `simple`
263+
- `Symbol.for('splat')`: additional string interpolation arguments. _Used
264+
exclusively by `splat()` format._
265+
266+
These Symbols are stored in another package: `triple-beam` so that all
267+
consumers of `logform` can have the same Symbol reference. i.e.:
268+
269+
``` js
270+
const { LEVEL, MESSAGE, SPLAT } = require('triple-beam');
271+
272+
console.log(LEVEL === Symbol.for('level'));
273+
// true
274+
275+
console.log(MESSAGE === Symbol.for('message'));
276+
// true
277+
278+
console.log(SPLAT === Symbol.for('splat'));
279+
// true
280+
```
237281

238282
> **NOTE:** any `{ message }` property in a `meta` object provided will
239283
> automatically be concatenated to any `msg` already provided: For
@@ -259,8 +303,8 @@ format your logs, `winston.format.printf` is for you:
259303
const { createLogger, format, transports } = require('winston');
260304
const { combine, timestamp, label, printf } = format;
261305
262-
const myFormat = printf(info => {
263-
return `${info.timestamp} [${info.label}] ${info.level}: ${info.message}`;
306+
const myFormat = printf(({ level, message, label, timestamp }) => {
307+
return `${timestamp} [${label}] ${level}: ${message}`;
264308
});
265309
266310
const logger = createLogger({
@@ -274,8 +318,7 @@ const logger = createLogger({
274318
```
275319
276320
To see what built-in formats are available and learn more about creating your
277-
own custom logging formats, see
278-
[`logform`](https://github.com/winstonjs/logform).
321+
own custom logging formats, see [`logform`][logform].
279322

280323
### Combining formats
281324

@@ -310,7 +353,7 @@ logger.log({
310353
### String interpolation
311354

312355
The `log` method provides the string interpolation using [util.format]. **It
313-
must be enabled using `format.splat`.**
356+
must be enabled using `format.splat()`.**
314357

315358
Below is an example that defines a format with string interpolation of
316359
messages using `format.splat` and then serializes the entire `info` message
@@ -1088,9 +1131,13 @@ npm test
10881131
[mocha]: https://mochajs.org
10891132
[nyc]: https://github.com/istanbuljs/nyc
10901133
[assume]: https://github.com/bigpipe/assume
1134+
[logform]: https://github.com/winstonjs/logform#readme
10911135

10921136
[Read the `winston@2.x` documentation]: https://github.com/winstonjs/winston/tree/2.x
10931137

1138+
[quick-example]: https://github.com/winstonjs/winston/blob/master/examples/quick-start.js
1139+
[examples]: https://github.com/winstonjs/winston/tree/master/examples
1140+
10941141
[Charlie Robbins]: http://github.com/indexzero
10951142
[Jarrett Cruger]: https://github.com/jcrugzz
10961143
[David Hyde]: https://github.com/dabh

0 commit comments

Comments
 (0)