https://github.com/jclem/logfmt-dart
Dart package for working with logfmt-style log lines
https://github.com/jclem/logfmt-dart
Last synced: about 1 year ago
JSON representation
Dart package for working with logfmt-style log lines
- Host: GitHub
- URL: https://github.com/jclem/logfmt-dart
- Owner: jclem
- License: mit
- Created: 2014-09-03T15:54:34.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2014-09-04T17:14:07.000Z (almost 12 years ago)
- Last Synced: 2025-03-24T10:52:52.268Z (about 1 year ago)
- Language: Dart
- Homepage: https://pub.dartlang.org/packages/logfmt
- Size: 285 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# logfmt-dart [](https://travis-ci.org/jclem/logfmt-dart)
"logfmt" is the name of a key-value logging convention, where log lines are
formatted as "key=value" pairs.
This package decodes individual log lines or streams of log lines. Individual
log lines are decoded as `Map` objects, and streams passing
through the `streamDecoder` transform will emit `Map` objects, as well.
## Usage
### Logger
A class which can log `Map`, and optionally include elapsed
time since the logger was created.
```dart
import 'package:logfmt/logfmt.dart' as logfmt;
void main() {
logfmt.Logger logger = new logfmt.Logger();
logger.log({ 'key': 'value' }); // Logs "key=value" to stdout.
logger.logWithElapsed({ 'key': 'value' }); // Logs "key=value elapsed=1ms" to stdout.
}
```
### #decode
Given a logfmt-style log line, decode it into a `Map` using `#decode`:
```dart
import 'package:logfmt/logfmt.dart' as logfmt;
import 'package:unittest/unittest.dart';
void main() {
test('key=value pairs of non-null and non-boolean strings decode into [Map].', () {
expect(logfmt.decode('key=value'), equals({ 'key': 'value' }));
});
test('"flag"s are decoded into [Map] where `bool` is `true`.', () {
expect(logfmt.decode('flag'), equals({ 'flag': true }));
});
test('Pairs with "true" or "false" as values are decoded into [Map], as appropriate.', () {
expect(logfmt.decode('key=false'), equals({ 'key': false }));
});
test('Pairs with "null" values are decoded into [Map].', () {
expect(logfmt.decode('key=null'), equals({ 'key': null }));
});
test('Quoted keys and values are preserved.', () {
expect(logfmt.decode('"quoted key"="quoted value"'), equals({ 'quoted key': 'quoted value' }));
});
}
```
### #encode
Given a `Map`, encode it into a logfmt-style string using `#encode`:
```dart
import 'package:logfmt/logfmt.dart' as logfmt;
import 'package:unittest/unittest.dart';
void main() {
test('encodes Map into plain key=value.', () {
expect(logfmt.encode({ 'key': 'value' }), equals('key=value'));
});
test('encodes Map into key=${bool.toString}', () {
expect(logfmt.encode({ 'key': true }), equals('key=true'));
});
test('encodes Map into key=${null.toString}', () {
expect(logfmt.encode({ 'key': null }), equals('key=null'));
});
test('encodes long doubles as truncated', () {
expect(logfmt.encode({ 'longDouble': 0.44444444444444444444 }),
equals('longDouble=0.4444444444444444'));
});
test('encodes dates as UTC ISO 8601', () {
DateTime date = new DateTime.now();
expect(logfmt.encode({ 'date': date }),
equals('date=${date.toUtc().toIso8601String()}'));
});
test('encodes multi-word strings as quoted', () {
expect(logfmt.encode({ 'key': 'quoted value' }),
equals('key="quoted value"'));
});
test('encodes quotes as escaped quotes', () {
expect(logfmt.encode({ 'key': '"value' }), equals(r'key=\"value'));
});
test('encodes new lines with literal \\n characters', () {
expect(logfmt.encode({ 'key': '\nvalue' }), equals(r'key=\nvalue'));
});
}
```
### #log
Logs a `Map` to either standard out or a given `StringSink`.
```dart
import 'package:logfmt/logfmt.dart' as logfmt;
logfmt.log({ 'key': 'value' }); // "key=value" is logged to standard out.
logfmt.log({ 'key': 'value' }, sink: sink); // The log is written to `sink`.
```
### streamDecoder
A stream of lines can be sent to the `streamDecoder` transformer, which will return a stream emitting `Map` objects.
```dart
import 'dart:convert';
import 'dart:io';
import 'package:logfmt/logfmt.dart' as logfmt;
void main() {
new File('test/log.txt').openRead()
.transform(new Utf8Decoder())
.transform(new LineSplitter())
.transform(logfmt.streamDecoder())
.listen((Map map) {
print(map);
});
}
```
### streamEncoder
A stream of `Map` can be sent to the `streamEncoder`
transformer, which will return a stream emitting logfmt-style strings.
```dart
import 'dart:async';
import 'package:logfmt/logfmt.dart' as logfmt;
void main() {
new Stream.fromIterable(maps)
.transform(logfmt.streamEncoder())
.listen((String line) {
print(line);
});
}
```
## Todo
- Implement an example request logger.