From b8e0ce92b7cdf04075dc7ae5b511b9c806db7884 Mon Sep 17 00:00:00 2001 From: Simon Chan <1330321+yume-chan@users.noreply.github.com> Date: Mon, 6 Jan 2025 14:51:16 +0800 Subject: [PATCH] add some logcat docs --- docs/api/bin/_category_.yml | 2 +- docs/api/bin/logcat.mdx | 5 - docs/api/bin/logcat/binary.mdx | 170 +++++++++++++++++++++++++++++++++ docs/api/bin/logcat/clear.mdx | 43 +++++++++ docs/api/index.mdx | 2 + 5 files changed, 216 insertions(+), 6 deletions(-) delete mode 100644 docs/api/bin/logcat.mdx create mode 100644 docs/api/bin/logcat/binary.mdx create mode 100644 docs/api/bin/logcat/clear.mdx diff --git a/docs/api/bin/_category_.yml b/docs/api/bin/_category_.yml index 8ef80a7..0cb1cdc 100644 --- a/docs/api/bin/_category_.yml +++ b/docs/api/bin/_category_.yml @@ -1,3 +1,3 @@ position: 3 -label: 'android-bin' +label: 'Executable Wrappers' collapsed: false diff --git a/docs/api/bin/logcat.mdx b/docs/api/bin/logcat.mdx deleted file mode 100644 index 81d48a6..0000000 --- a/docs/api/bin/logcat.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 1 ---- - -# logcat diff --git a/docs/api/bin/logcat/binary.mdx b/docs/api/bin/logcat/binary.mdx new file mode 100644 index 0000000..7ed2cdc --- /dev/null +++ b/docs/api/bin/logcat/binary.mdx @@ -0,0 +1,170 @@ +# binary + +Read logcat entries in binary format. + +Only binary format is supported, because it's easier for machine to parse than text format. The output is deserialized into `AndroidLogEntry` objects, and can be converted back to text format. + +```ts showLineNumbers +export const LogId = { + All: -1, + Main: 0, + Radio: 1, + Events: 2, + System: 3, + Crash: 4, + Stats: 5, + Security: 6, + Kernel: 7, +} as const; + +export type LogId = (typeof LogId)[keyof typeof LogId]; + +export interface LogcatOptions { + dump?: boolean; + pid?: number; + ids?: LogId[]; +} + +export const AndroidLogPriority = { + Unknown: 0, + Default: 1, + Verbose: 2, + Debug: 3, + Info: 4, + Warn: 5, + Error: 6, + Fatal: 7, + Silent: 8, +} as const; + +export type AndroidLogPriority = + (typeof AndroidLogPriority)[keyof typeof AndroidLogPriority]; + +export interface LoggerEntry { + pid: number; + tid: number; + logId: number; + uid: number; + timestamp: bigint; +} + +export interface AndroidLogEntry extends LoggerEntry { + priority: AndroidLogPriority; + tag: string; + message: string; +} + +declare class Logcat { + binary(options?: LogcatOptions): ReadableStream; +} +``` + +## Options + +### `dump` + +If set to `true`, only existing entries will be returned. Otherwise, it will wait and return all future entries. + +:::info[Equivalent ADB Command] + +```sh +adb logcat -d +``` + +::: + +### `pid` + +Filter entries by process ID. If not specified, all entries will be returned. + +:::info[Equivalent ADB Command] + +```sh +adb logcat --pid +``` + +::: + +### `ids` + +Filter entries by log ID. If not specified, all entries will be returned. + +:::info[Equivalent ADB Command] + +```sh +adb logcat -b [,]* +``` + +::: + +## Usage + +```ts +import type { Adb } from "@yume-chan/adb"; +import { Logcat } from "@yume-chan/android-bin"; + +declare const adb: Adb; +const logcat = new Logcat(); + +for await (const entry of logcat.binary()) { + console.log(entry); +} +``` + +## `toString()` + +The `toString()` method converts the entry into a string with the specified format. + +```ts showLineNumbers +export const LogcatFormat = { + Brief: 0, + Process: 1, + Tag: 2, + Thread: 3, + Raw: 4, + Time: 5, + ThreadTime: 6, + Long: 7, +} as const; + +export type LogcatFormat = (typeof LogcatFormat)[keyof typeof LogcatFormat]; + +export interface LogcatFormatModifiers { + microseconds?: boolean; + nanoseconds?: boolean; + printable?: boolean; + year?: boolean; + timezone?: boolean; + epoch?: boolean; + monotonic?: boolean; + uid?: boolean; +} + +declare interface AndroidLogEntry { + toString(format?: LogcatFormat, modifiers?: LogcatFormatModifiers): string; +} +``` + +All built-in [formats](https://developer.android.com/tools/logcat#outputFormat) are supported: + +```ts transpile +import type { AndroidLogEntry } from "@yume-chan/android-bin"; +import { LogcatFormat } from "@yume-chan/android-bin"; + +declare const entry: AndroidLogEntry; + +console.log(entry.toString(LogcatFormat.Brief)); +console.log(entry.toString(LogcatFormat.Long)); +console.log(entry.toString()); // Defaults to `LogcatFormat.ThreadTime` +``` + +and all [format modifiers](https://developer.android.com/tools/logcat#formatmodify) except `color`, `printable` and `descriptive` are supported: + +```ts transpile +import type { AndroidLogEntry } from "@yume-chan/android-bin"; +import { LogcatFormat } from "@yume-chan/android-bin"; + +declare const entry: AndroidLogEntry; + +console.log(entry.toString(LogcatFormat.Brief, { year: true })); +``` diff --git a/docs/api/bin/logcat/clear.mdx b/docs/api/bin/logcat/clear.mdx new file mode 100644 index 0000000..f2d9a83 --- /dev/null +++ b/docs/api/bin/logcat/clear.mdx @@ -0,0 +1,43 @@ +# clear + +Delete all logcat entries in the buffer. + +```ts showLineNumbers +export const LogId = { + All: -1, + Main: 0, + Radio: 1, + Events: 2, + System: 3, + Crash: 4, + Stats: 5, + Security: 6, + Kernel: 7, +} as const; + +export type LogId = (typeof LogId)[keyof typeof LogId]; + +declare class Logcat { + clear(ids?: LogId[]): Promise; +} +``` + +## Usage + +```ts transpile +import type { Adb } from "@yume-chan/adb"; +import { Logcat } from "@yume-chan/android-bin"; + +declare const adb: Adb; +const logcat = new Logcat(adb); + +await logcat.clear(); +``` + +:::info[Equivalent ADB Command] + +```sh +adb logcat -c +``` + +::: diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 05ca410..7ac2702 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -59,6 +59,8 @@ npm i @yume-chan/android-bin * **Demo mode**: Control demo mode * `dumpsys`: Dump system service information * `logcat`: View device logs + * [`binary`](./bin/logcat/binary.mdx): Read logcat entries in binary format + * [`clear`](./bin/logcat/clear.mdx): Delete all logcat entries * **Overlay Display** Manages simulated secondary displays * `pm`: Manage apps * `settings`: Get/set Android system settings