Logging System and Maintenance

Logging System and Maintenance

中文 · Troubleshooting Method

LogManager unifies Android logcat, in-app live logs, and private file logs. Logs are evidence projections of state and events, never the source of business state.

Outputs and switches

• enableActivityLog controls file logs under private app storage at files/logs.
• enableDebugMode requests live logs; LiveLogStore is enabled only when debug mode is on and runtime logging is not suppressed.
• Detail categories are AUDIO_STREAM, VIDEO_STREAM, CONTROL_STREAM, EVENT_STREAM, SHELL_STREAM, and MANAGEMENT.
• dControl, dShell, and dManagement construct and emit detailed messages only when their category is enabled.
• Ordinary debug/info tags are also filtered through tag-to-category mapping. Warn/error still obey game runtime suppression.
• A connected game session may call setRuntimeLoggingSuppressed(true) to pause the in-app log paths and restore user settings afterward.

File names include app version and date. A file over 10 MiB rolls to a new file. Users can list, read, delete, clear all, or clear old files. The writer runs on an IO scope and flushes each write, so every new high-frequency log must account for this cost.

Telemetry diagnostics

• TelemetryPreferences stores an independent enabled flag, installation UUID, and last uploaded local date. The current default is enabled; the About page can disable it, and re-enabling requires the confirmation dialog.
• After onboarding is hidden, app startup uploads the previous local day's matching activity logs plus files/telemetry/Telemetry_<date>.log to the build-configured HTTPS endpoint. Input is capped at 20 MiB before gzip and carries a SHA-256 header. If no log exists, or that date was already uploaded, the client sends a ping instead.
• The server receives the request IP. Ordinary activity logs may contain endpoints and other diagnostics. The dedicated telemetry journal keeps only normalized session, connection, candidate, management, and pairing outcomes and removes session ids, endpoint identity, and free-form verbose messages.
• Telemetry does not upload screenshots or remote video. Network failure is logged and does not block startup.

Main tags

Stage	Tags	Purpose
App/Session	SAPP, MAIN, SVM, SCLI	Entry, session, and client orchestration
ADB	ADBC, ADBP, USBC, SSVC	Connection, pairing, USB, foreground protection
Server/Protocol	SSVR, SKPK, SEVT	Server shell, packets, event projections
Media	VDEC, ADEC, VCSL, ACSL	Decoders and selectors
Remote/Control	RDSP, TOCH, CTRL, FCTL	Surface, touch, control, floating menu
Management	MGMT	Management commands and page actions

LogTags.kt is authoritative for the full values. A new tag also needs a detail category, default behavior, frequency decision, and troubleshooting entry. Do not create a tag for one class without a domain reason.

Levels and content

• Runtime diagnostic messages are written in English regardless of the selected UI language so tags, search terms, device reports, and cross-device troubleshooting remain stable. When a log reuses a TextPair, it selects .english; .get() remains for user-visible localized copy, not diagnostic language selection.
• VERBOSE/DEBUG: optional diagnostics and high-frequency details.
• INFO: sparse important lifecycle conclusions.
• WARN: recoverable anomalies, fallback, retries, or unexpected state.
• ERROR: operation failure, protocol corruption, or terminal state requiring attention.

Main-path logs should include session or transport identity, phase, resource identity such as SCID/port/socket type, and result. Never log pairing codes, keys, clipboard text, tokens, or complete private-file content; redact commands and paths when required.

Closure signals such as EOF, socket closed/reset, and broken pipe receive a concise reason and unified classification so stream, decoder, and monitor do not print the same stack repeatedly. Protocol errors, invalid lengths, MediaCodec failures, and unknown exceptions retain the complete throwable.

Event-log sampling

ScrcpyEventLogger uses each event's level and category. Types marked for sampling log every 100th event; lifecycle and failure are not sampled. Finer media and packet logs also obey their detail category. String sampling must not replace source counters or performance counters.

Maintenance checklist

• A new tag exists in LogTags.kt and is mapped to a category when needed.
• A high-frequency success path does not log every packet or frame by default.
• One primary error represents a failure; other records provide correlated context without duplicate stacks.
• Logs identify whether failure stopped at ADB, server, socket, metadata, decoder, Surface, or control.
• Tests and review cover sensitive-data exposure.
• TelemetryJournalTest protects normalization and identity stripping; changes to uploaded sources, retention, endpoint headers, or default enablement must update the user-facing Settings page and this contract together.
• Business code never parses log text as state; policy uses structured issues and events.
• New or changed diagnostics remain English and do not accidentally switch with the UI locale.