adbkit-logcat-fb
v1.1.0
Published
A Node.js interface for working with Android's logcat output.
Downloads
7
Readme
adbkit-logcat
adbkit-logcat provides a Node.js interface for working with output produced by the Android logcat
tool. It takes a log stream (that you must create separately), parses it, and emits log entries in real-time as they occur. Possible use cases include storing logs in a database, forwarding logs via MessagePack, or just advanced filtering.
Getting started
Install via NPM:
npm install --save adbkit-logcat
Note that while adbkit-logcat is written in CoffeeScript, it is compiled to JavaScript before publishing to NPM, which means that you are not required to use CoffeeScript.
Examples
Output all log messages
JavaScript
var logcat = require('adbkit-logcat');
var spawn = require('child_process').spawn;
// Retrieve a binary log stream
var proc = spawn('adb', ['logcat', '-B']);
// Connect logcat to the stream
reader = logcat.readStream(proc.stdout);
reader.on('entry', function(entry) {
console.log(entry.message);
});
// Make sure we don't leave anything hanging
process.on('exit', function() {
proc.kill();
});
CoffeeScript
Logcat = require 'adbkit-logcat'
{spawn} = require 'child_process'
# Retrieve a binary log stream
proc = spawn 'adb', ['logcat', '-B']
# Connect logcat to the stream
reader = Logcat.readStream proc.stdout
reader.on 'entry', (entry) ->
console.log entry.message
# Make sure we don't leave anything hanging
process.on 'exit', ->
proc.kill()
API
Logcat
logcat.Priority
Exposes Priority
. See below for details.
logcat.Reader
Exposes Reader
. See below for details.
logcat.readStream(stream[, options])
Creates a logcat reader instance from the provided logcat event Stream
. Note that you must create the stream separately.
- stream The event stream to read.
- options Optional. The following options are supported:
- format The format of the stream. Currently, the only supported value is
'binary'
, which (for example)adb logcat -B
produces. Defaults to'binary'
. - fixLineFeeds All programs run via the ADB shell transform any
'\n'
in the output to'\r\n'
, which breaks binary content. If set, this option reverses the transformation before parsing the stream. Defaults totrue
.
- format The format of the stream. Currently, the only supported value is
- Returns: The
Reader
instance.
Priority
Constants
The following static properties are available:
- Priority.UNKNOWN i.e.
0
. - Priority.DEFAULT i.e.
1
. Not available when reading a stream. - Priority.VERBOSE i.e.
2
. - Priority.DEBUG i.e.
3
. - Priority.INFO i.e.
4
. - Priority.WARN i.e.
5
. - Priority.ERROR i.e.
6
. - Priority.FATAL i.e.
7
. - Priority.SILENT i.e.
8
. Not available when reading a stream.
Priority.fromLetter(letter)
Static method to convert the given letter
into a numeric priority. For example, Priority.fromName('d')
would return Priority.DEBUG
.
- letter The priority as a
String
. Any single, case-insensitive character matching the first character of anyPriority
constant is accepted. - Returns: The priority as a
Number
, orundefined
.
Priority.fromName(name)
Static method to convert the given name
into a numeric priority. For example, Priority.fromName('debug')
(or Priority.fromName('d')
) would return Priority.DEBUG
.
- name The priority as a
String
. Any full, case-insensitive match of thePriority
constants is accepted. If no match is found, falls back toPriority.fromLetter()
. - Returns: The priority as a
Number
, orundefined
.
Priority.toLetter(priority)
Static method to convert the numeric priority into its letter representation. For example, Priority.toLetter(Priority.DEBUG)
would return 'D'
.
- priority The priority as a
Number
. AnyPriority
constant value is accepted. - Returns: The priority as a
String
letter, orundefined
.
Priority.toName(priority)
Static method to convert the numeric priority into its full string representation. For example, Priority.toLetter(Priority.DEBUG)
would return 'DEBUG'
.
- priority The priority as a
Number
. AnyPriority
constant value is accepted. - Returns: The priority as a
String
, orundefined
.
Reader
A reader instance, which is an EventEmitter
.
Events
The following events are available:
- error (err) Emitted when an error occurs.
- err An
Error
.
- err An
- end Emitted when the stream ends.
- finish Emitted when the stream finishes.
- entry (entry) Emitted when the stream finishes.
- entry A log
Entry
. See below for details.
- entry A log
constructor([options])
For advanced users. Manually constructs a Reader
instance. Useful for testing and/or playing around. Normally you would use logcat.readStream()
to create the instance.
- options See
logcat.readStream()
for details. - Returns: N/A
reader.connect(stream)
For advanced users. When instantiated manually (not via logcat.readStream()
), connects the Reader
instance to the given stream.
- stream See
logcat.readStream()
for details. - Returns: The
Reader
instance.
reader.end()
Convenience method for ending the stream.
- Returns: The
Reader
instance.
reader.exclude(tag)
Skip entries with the provided tag. Alias for reader.include(tag, Priority.SILENT)
. Note that even skipped events have to be parsed so that they can be ignored.
- tag The tag string to exclude. If
'*'
, works the same asreader.excludeAll()
. - Returns: The
Reader
instance.
reader.excludeAll()
Skip ALL entries. Alias for reader.includeAll(Priority.SILENT)
. Any entries you wish to see must be included via include()
/includeAll()
.
- Returns: The
Reader
instance.
reader.include(tag[, priority])
Include all entries with the given tag and a priority higher or equal to the given priority
.
- tag The tag string to include. If
'*'
, works the same asreader.includeAll(priority)
. - priority Optional. A lower bound for the priority. Any numeric
Priority
constant or anyString
value accepted byPriority.fromName()
is accepted. Defaults toPriority.DEBUG
. - Returns: The
Reader
instance.
reader.includeAll([priority])
Include all entries with a priority higher or equal to the given priority
.
- tag The tag string to exclude.
- priority Optional. See
reader.include()
for details. - Returns: The
Reader
instance.
reader.resetFilters()
Resets all inclusions/exclusions.
- Returns: The
Reader
instance.
Entry
A log entry.
Properties
The following properties are available:
- date Event time as a
Date
. - pid Process ID as a
Number
. - tid Thread ID as a
Number
. - priority Event priority as a
Number
. You can uselogcat.Priority
to convert the value into aString
. - tag Event tag as a
String
. - message Message as a
String
.
entry.toBinary()
Converts the entry back to the binary log format.
- Returns: The binary event as a
Buffer
.
More information
Contributing
See CONTRIBUTING.md.
License
See LICENSE.
Copyright © The OpenSTF Project. All Rights Reserved.