adbkit-logcat

A Node.js interface for working with Android's logcat output.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
adbkit-logcat
4222.0.15 years ago9 years agoMinified + gzip package size for adbkit-logcat in KB

Readme

adbkit-logcat
adbkit-logcat provides a Node.jsnodejs interface for working with output produced by the Android logcat toollogcat-site. 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 MessagePackmsgpack, or just advanced filtering.

Requirements

  • Node.js 4.x or newer. Older versions are not supported.

Getting started

Install via NPM:
npm install --save adbkit-logcat

Examples

Output all log messages

JavaScript
const logcat = require('adbkit-logcat')
const {spawn} = require('child_process')

// Retrieve a binary log stream
const 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 Streamnode-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 to `true`.
  • 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 any Priority constant is accepted.
  • Returns: The priority as a Number, or undefined.

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 the Priority constants is accepted. If no match is found, falls back to Priority.fromLetter().
  • Returns: The priority as a Number, or undefined.

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. Any Priority constant value is accepted.
  • Returns: The priority as a String letter, or undefined.

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. Any Priority constant value is accepted.
  • Returns: The priority as a String, or undefined.

Reader

A reader instance, which is an EventEmitternode-events.

Events

The following events are available:
  • error (err) Emitted when an error occurs.
* **err** An `Error`.
  • 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.

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 as reader.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 as reader.includeAll(priority).
  • priority Optional. A lower bound for the priority. Any numeric Priority constant or any String value accepted by Priority.fromName() is accepted. Defaults to Priority.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 use logcat.Priority to convert the value into a String.
  • tag Event tag as a String.
  • message Message as a String.

entry.toBinary()

Converts the entry back to the binary log format.

More information

Contributing

See CONTRIBUTING.md.

License

See LICENSE.
Copyright © The OpenSTF Project. All Rights Reserved.