A `adb logcat` wrapper

Felix Obenhuber

Last update: Dec 31, 2022

Related tags

Plugin android debugging adb logging bridge logcat

Overview

rogcat

...is a adb logcat wrapper. The Android Debugging Bridge (adb) is the default way to interact with a Android device during development. The logcat subcommand of adb allows access to Androids internal log buffers. rogcat tries to give access to those logs in a convenient way including post processing capabilities. The main feature probably is a painted and reformatted view. rogcat can read logs from

running adb logcat (default)
a custom command (stdout, stderr)
one or multiple files
stdin
connect to TCP port
A SocketCAN CAN device (Linux only)

The processing steps within a rogcat run include parsing of the input stream and applying filters (if provided). rogcat comes with a set of implemented in and output formats:

csv: Comma separated values
raw: Record (line) as captured
html: A static single page html with a static table. This option cannot be used as input format. The page layout needs some love...
human: A human friendly colored column based format. See screenshot
json: Single line JSON

Except the human and html format the output of rogcat is parseable by rogcat.

Examples

The following examples show a subset of rogcat's features. Please read --help!

Live

Capture logs from a connected device and display unconditionally. Unless configurated otherwise, Rogcat runs adb logcat -b main -b events -b crash -b kernel:

rogcat

Write captured logs to testrun.log:

rogcat -o testrun.log

Write captured logs to file ./trace/testrun-XXX.log by starting a new file every 1000 lines. If ./trace is not present it is created:

rogcat -o ./trace/testrun.log -n 1000 or rogcat -o ./trace/testrun.log -n 1k

stdin

Process stdout and stderr of command:

rogcat command or command | rogcat -

Filter

Display logs from adb logcat and filter on records where the tag matches ^ABC.* along with not X and the message includes pattern:

rogcat -t "^ADB.*" -t \!X -m pattern

The Read all files matching trace* in alphanumerical order and dump lines matching hmmm to /tmp/filtered:

rogcat -i trace* -m hmmm -o /tmp/filtered

Check the --message and --highlight options in the helptext.

TCP

To connect via TCP to some host run something like:

rogcat tcp://traceserver:1234

SocketCAN

To open a SocketCAN device and read frames run:

rogcat can://can0

SocketCAN is a Linux only thing.

Bugreport

Capture a Android bugreport. This only works for Android version prior 7:

rogcat bugreport

Capture a Android bugreport and write (zipped) to bugreport.zip:

rogcat bugreport -z bugreport.zip

Log

Write message "some text" into the device log buffer (e.g annotations during manual testing):

rogcat log "some text"

Set level and tag or read from stdin:

rogcat-log
Add log message(s) log buffer

USAGE:
    rogcat log [OPTIONS] [MESSAGE]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -l, --level <LEVEL>    Log on level [values: trace, debug, info, warn, error, fatal, assert, T, D, I, W, E, F, A]
    -t, --tag <TAG>        Log tag

ARGS:
    <MESSAGE>    Log message. Pass "-" to capture from stdin'

Profiles

List available profiles (see Profiles chapter):

rogcat profiles --list

Live trace with profile app:

rogcat -p app

Installation

Building rogcat requires Rust 2018 edition:

cargo install --path .

or use Homebrew by running

brew install flxo/tap/rogcat

or grab one of the binary releases on the GitHub page.

Configuration

When rogcat runs without any command supplied it defaults to running adb logcat -b all. The following options can be overwritten in the rogcat config file config.toml. The location of the config file is platform specific:

MacOS: $HOME/Library/Preferences/rogcat/config.toml
Linux: $HOME/.config/rogcat/config.toml
Windows: %HOME%/AppData/Roaming/rogcat/config.toml

Restart

By default rogcat restarts adb logcat when that one exits. This is intentional behavior to make rogcat reconnect on device power cycles or disconnect/reconnects. A Windows 7 bug prevents rogcat from restarting adb. Place restart = false in the configuration file mentioned above to make rogcat exit when adb exits.

Buffer

The default behavior of rogcat is to dump all logcat buffers. This can be overwritten by selecting specific buffers in the rogcat configuration file. e.g:

buffer = ["main", "events"]

Terminal settings

Some parameters of the human format are adjustable via the config file:

terminal_tag_width = 20
terminal_show_date = false
terminal_hide_timestamp = true
terminal_color = never
terminal_no_dimm = true

Profiles

Optionally rogcat reads a (toml formated) configuration file if present. This configuration may include tracing profiles ('-p') and settings. The possible options in the configuration file are a subset of the command line options. The configuration file is read from the location set in the environment variable ROGCAT_PROFILES or a fixed pathes depending on your OS:

MacOS: $HOME/Library/Preferences/rogcat/profiles.toml
Linux: $HOME/.config/rogcat/profiles.toml
Windows: %HOME%/AppData/Roaming/rogcat/profiles.toml

The environment variable overrules the default path. See rogcat profiles --help or rogcat profiles --examples.

Example:

[profile.a]
comment = "Messages starting with A or a"
message_ignore_case = ["^A.*"]

[profile.B]
comment = "Messages starting with B"
message = ["^B.*"]

[profile.ABC]
extends = ["A", "B"]
comment = "Profiles A, B plus the following filter (^C.*)"
message = ["^C.*"]

[profile."Comments are optional"]
tag = ["rogcat"]

[profile.complex]
comment = "Profiles can be complex. This one is probably very useless."
highlight = ["blah"]
message = ["^R.*", "!^A.*", "!^A.*"]
tag = ["b*", "!adb"]

[profile."W hitespace"]
comment = "Profile names can contain whitespaces. Quote on command line..."

[profile.rogcat]
comment = "Only tag \"rogcat\""
tag = ["^rogcat$"]

[profile.default]
comment = "Default profile"

To check your setup, run rogcat profiles --list and select a profile for a run by passing the -p/--profile option.

You can create a special profile named default which will be used when no other profile is selected on the command line.

Usage

rogcat 0.4.0-alpha.0
Felix Obenhuber <[email protected]>
A 'adb logcat' wrapper and log processor. Your config directory is "/Users/felix/Library/Preferences/rogcat".

USAGE:
    rogcat [FLAGS] [OPTIONS] [COMMAND] [SUBCOMMAND]

FLAGS:
    -d, --dump              Dump the log and then exit (don't block)
        --help              Prints help information
        --hide-timestamp    Hide timestamp in terminal output
        --no-dimm           Use white as dimm color
        --overwrite         Overwrite output file if present
        --restart           Restart command on exit
        --show-date         Show month and day in terminal output
    -s, --skip              Skip records on a command restart until the last received last record is received again. Use
                            with caution!
    -V, --version           Prints version information

OPTIONS:
    -b, --buffer <buffer>...
            Select specific logd buffers. Defaults to main, events, kernel and crash

        --color <color>                          Terminal coloring option [possible values: auto, always, never]
    -a, --filename-format <filename_format>
            Select a format for output file names. By passing 'single' the filename provided with the '-o' option is
            used (default).'enumerate' appends a file sequence number after the filename passed with '-o' option
            whenever a new file is created (see 'records-per-file' option). 'date' will prefix the output filename with
            the current local date when a new file is created [possible values: single, enumerate, date]
    -f, --format <format>
            Output format. Defaults to human on stdout and raw on file output [possible values: csv, html, human, json,
            raw]
    -H, --head <head>                            Read n records and exit
    -h, --highlight <highlight>...
            Highlight messages that match this pattern in RE2. The prefix '!' inverts the match

    -i, --input <input>...
            Read from file instead of command. Use 'serial://COM0@115200,8N1 or similiar for reading a serial port

    -l, --level <level>
            Minimum level [possible values: trace, debug, info, warn, error, fatal, assert, T, D, I, W, E, F, A]

    -m, --message <message>...                   Message filters in RE2. The prefix '!' inverts the match
    -M, --Message <message-ignore-case>...       Same as -m/--message but case insensitive
    -o, --output <output>                        Write output to file
    -p, --profile <profile>                      Select profile
    -P, --profiles-path <profiles_path>          Manually specify profile file (overrules ROGCAT_PROFILES)
    -n, --records-per-file <records_per_file>    Write n records per file. Use k, M, G suffixes or a plain number
    -r, --regex <regex_filter>...                Regex filter on tag, pid, thread and message.
    -t, --tag <tag>...                           Tag filters in RE2. The prefix '!' inverts the match
    -T, --Tag <tag-ignore-case>...               Same as -t/--tag but case insensitive
        --tail <tail>                            Dump only the most recent <COUNT> lines (implies --dump)

ARGS:
    <COMMAND>    Optional command to run and capture stdout and stdderr from. Pass "-" to d capture stdin'. If
                 omitted, rogcat will run "adb logcat -b all" and restarts this commmand if 'adb' terminates

SUBCOMMANDS:
    bugreport      Capture bugreport. This is only works for Android versions < 7.
    clear          Clear logd buffers
    completions    Generates completion scripts
    devices        List available devices
    help           Prints this message or the help of the given subcommand(s)
    log            Add log message(s) log buffer

Licensing

See LICENSE for details.

Comments

(Feature Request) Allow running commands without the "adb" prefix
Hi! thanks for this, its amazing! I use this on my laptop but considering that logcat is built into Android phones and doesnt need adb it would be great if we could run the commands without adb prefixed to them. Reasons?

A PC isnt needed for a logcat, so it shouldnt be a requirement .

I use Termux on my tablet when I'm away from home (away from a PC), it would be great continue using this in those situations.

Rooted devices (like mine) and older devices (before android 7) actually have adb binaries, let us use them too!

I can build this but when issuing "rogcat" I get "cannot find binary path", as stated, I have adb & fastboot on my device, so my guess is that rogcat is looking for the binaries only /usr/bin but Android binaries are in /system/bin & /system/xbin. If you do not oppose to the idea, then my guess is that all it would take is a check (uname) to get device type and then rogcat would either prefix the commands with adb first or not, or which adb would locate the binary, or simply allow a variable in rogcats config.yml that would decide instead.

Again, thank you!
opened by nerd190 6
Failed to lock terminal
Hi,

After a recent Linux system upgrade I'm getting the following error (from src/terminal.rs:82) when I execute rogcat:

Failed to lock terminal

I'm getting the same error even uninstalling and re-installing rogcat using cargo.

adb logcat on the other hand works properly

Some extra info:

Linux x1 4.14.27-1-MANJARO #1 SMP PREEMPT Thu Mar 15 19:47:13 UTC 2018 x86_64 GNU/Linux cargo 1.26.0-nightly (5f83bb404 2018-03-09) rustc 1.26.0-nightly (55c984ee5 2018-03-16)
opened by francozappa 6
rogcat as a library

Hi. Is rogcat a wrapper over logcat binary or is it a port with more features? I want to write a log shipper for android. My service runs inside android and I need a way to read logs. Can rogcat be used for this purpose?

opened by tekjar 5
Question about features and support formats

Great Tool with some awesome features.

Can rogcat parse an existing adb logcat file? We get logcat files from the field and would like to parse them into an easily readable format.

So can it parse a file that is outputted from the command adb logcat -v threadtime > adblogs.txt

If this tool cannot do this, do you have any suggestions of other tools that can do this.

Thanks, Abid

opened by abidesmail 5
Missing Package Requirement for Ubuntu 20.04

Following error has been observed :

error: failed to run custom build command for libudev-sys v0.1.4 Caused by: process didn't exit successfully: rogcat/target/release/build/libudev-sys-081b531eee85ba8b/build-script-build (exit status: 101)

The reason is that package libudev-dev needs to be installed.

Command :

sudo apt-get install libudev-dev

opened by sameernegi17 4

Build failed: No such file or directory (os error 2), src/libcore/result.rs:997:5

I build the project on Ubuntu 18.04. I installed Rust by running

curl https://sh.rustup.rs -sSf | sh

then run

RUST_BACKTRACE=1 cargo install --path .

I get this error

  Installing rogcat v0.3.1-alpha.0 (/home/gqqnbig/Project/rogcat)
   Compiling libudev-sys v0.1.4
   Compiling tokio-current-thread v0.1.4
   Compiling idna v0.1.5
   Compiling parking_lot_core v0.3.1
   Compiling rand_chacha v0.1.0
   Compiling rand_pcg v0.1.1
   Compiling rand v0.6.1
   Compiling rand v0.5.5
error: failed to run custom build command for `libudev-sys v0.1.4`
process didn't exit successfully: `/home/gqqnbig/Project/rogcat/target/release/build/libudev-sys-364e8e627474c66d/build-script-build` (exit code: 101)
--- stderr
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: "Failed to run `\"pkg-config\" \"--libs\" \"--cflags\" \"libudev\"`: No such file or directory (os error 2)"', src/libcore/result.rs:997:5
stack backtrace:
   0: std::sys::unix::backtrace::tracing::imp::unwind_backtrace
             at src/libstd/sys/unix/backtrace/tracing/gcc_s.rs:39
   1: std::sys_common::backtrace::_print
             at src/libstd/sys_common/backtrace.rs:70
   2: std::panicking::default_hook::{{closure}}
             at src/libstd/sys_common/backtrace.rs:58
             at src/libstd/panicking.rs:200
   3: std::panicking::default_hook
             at src/libstd/panicking.rs:215
   4: std::panicking::rust_panic_with_hook
             at src/libstd/panicking.rs:478
   5: std::panicking::continue_panic_fmt
             at src/libstd/panicking.rs:385
   6: rust_begin_unwind
             at src/libstd/panicking.rs:312
   7: core::panicking::panic_fmt
             at src/libcore/panicking.rs:85
   8: core::result::unwrap_failed
   9: build_script_build::main
  10: std::rt::lang_start::{{closure}}
  11: std::panicking::try::do_call
             at src/libstd/rt.rs:49
             at src/libstd/panicking.rs:297
  12: __rust_maybe_catch_panic
             at src/libpanic_unwind/lib.rs:87
  13: std::rt::lang_start_internal
             at src/libstd/panicking.rs:276
             at src/libstd/panic.rs:388
             at src/libstd/rt.rs:48
  14: main
  15: __libc_start_main
  16: _start

warning: build failed, waiting for other jobs to finish...
error: failed to compile `rogcat v0.3.1-alpha.0 (/home/gqqnbig/Project/rogcat)`, intermediate artifacts can be found at `/home/gqqnbig/Project/rogcat/target`

Caused by:
  build failed

How do I build it properly?

opened by gqqnbig 4

cli: do not prevent file colored output

Since some tools (such as less) are able to cope with colored codes in files, we should not prevent the file writing to be colored.

Signed-off-by: Jimmy Durand Wesolowski [email protected]

opened by JimmyDurandWesolowski 3
Add command line switch to select adb device
I have a workstation where multiple android devices are connected via USB. When running rogcat it get...

() - - waiting for device - () - error: more than one device/emulator

so basically the same as I would get from adb logcat. Could you add a command line switch to select the device by the serial number? Similar to adb's -s switch?
enhancement
opened by elektronenhirn 3
Multiple devices

Sorry if this is by chance really obvious, I know there's rogcat devices to list the available devices. Is there an option to use the ANDROID_SERIAL to switch between devices, similar to adb -s option?

opened by goncalopalaio 3

`rogcat profiles --list` does not list profiles on rogcat 0.4.5

I'm running into trouble loading rogcat profiles (and subsequently using them via -p flag) on 0.4.5. I have not rolled back to see if this is a regression.

Details below:

$ rogcat --version
rogcat 0.4.5

# Contents of profiiles.toml.
$ cat $HOME/Library/Preferences/rogcat/profiles.toml
[profile.a]
comment = "Messages starting with A or a"
message_ignore_case = ["^A.*"]

[profile.B]
comment = "Messages starting with B"
message = ["^B.*"]

[profile.ABC]
extends = ["A", "B"]
comment = "Profiles A, B plus the following filter (^C.*)"
message = ["^C.*"]

[profile.default]
comment = "Default profile"

# Try to list profiles
$ rogcat profiles --list
error: Found argument '--list' which wasn't expected, or isn't valid in this context

USAGE:
    rogcat [FLAGS] [OPTIONS] [COMMAND] [SUBCOMMAND]

For more information try --help

# Try again without --
$ rogcat profiles list
error: Found argument 'list' which wasn't expected, or isn't valid in this context

USAGE:
    rogcat [FLAGS] [OPTIONS] [COMMAND] [SUBCOMMAND]

For more information try --help

# Check Env Var
$ echo $ROGCAT_PROFILES

# Set Env Var + Retry
$ ROGCAT_PROFILES=$HOME/Library/Preferences/rogcat/profiles.toml rogcat profiles --list
error: Found argument '--list' which wasn't expected, or isn't valid in this context

USAGE:
    rogcat [FLAGS] [OPTIONS] [COMMAND] [SUBCOMMAND]

For more information try --help

$ ROGCAT_PROFILES=$HOME/Library/Preferences/rogcat/profiles.toml rogcat profiles list
error: Found argument 'list' which wasn't expected, or isn't valid in this context

USAGE:
    rogcat [FLAGS] [OPTIONS] [COMMAND] [SUBCOMMAND]

For more information try --help

opened by imlzo 2

bug: Rogcat fails to start with stdin parameter

{code} ./target/debug/rogcat - thread 'thread 'tokio-runtime-worker-0tokio-runtime-worker-1' panicked at '' panicked at 'attempted to leave type internal::Local uninitialized, which is invalidattempted to leave type internal::Local uninitialized, which is invalid', ', /rustc/c8dfcfe046a7680554bf4eb612bad840e7631c4b/library/core/src/mem/mod.rs/rustc/c8dfcfe046a7680554bf4eb612bad840e7631c4b/library/core/src/mem/mod.rs::663663::99 {code}

This is a problem with Crossbeam 0.7.1. Update to 0.7.2 will help. It's discussed here: https://github.com/darakian/ddh/issues/27

opened by miklelappo 2
Add parser for boost logging

Allow projects using boost logging to use nice rogcat colours

The setup for boost logging should look like this: "%TimeStamp% %ProcessID% %ThreadID% %Process%: %Message%"

Closes #36

opened by miklelappo 3