README

Trace4D

Trace4D is a diagnostic mechanism for Delphi, with an initial focus on FMX Android applications.

It combines a structured tracing API, a UI heartbeat that makes main-thread stalls visible, and a Windows Viewer that captures and interprets adb logcat.

🇧🇷 Documentação em português: README.pt-BR.md

Requirements

• Delphi 11 or newer (developed and tested on Delphi 12/13 with FMX).
• Instrumentation API (Trace4D.Core, Trace4D.Heartbeat): FMX Android applications; a Windows backend (OutputDebugString) lets demos and tests run without a device.
• Logcat Viewer: Windows VCL application; requires adb.exe (Android SDK platform-tools — the copy installed with Delphi works).
• Tests: DUnitX console runner, no device or ADB required.
• No external runtime dependencies; everything is plain Delphi source.

Quick start

Add src/ to your project search path, then instrument your FMX application:

uses
  Trace4D.Core,
  Trace4D.Heartbeat;

procedure TFormMain.FormCreate(Sender: TObject);
begin
  TTrace4D.Info('MyApp', 'Application started');

  // Makes main-thread stalls visible in logcat before Android declares an ANR.
  TTrace4DUIHeartbeat.Start('MyApp');
end;

procedure TFormMain.ButtonProcessClick(Sender: TObject);
var
  LScope: ITrace4DScope;
begin
  LScope := TTrace4D.Scope('MyApp', 'FormMain', 'ButtonProcessClick');
  // ... work ...
end; // LEAVE is emitted automatically with the elapsed time

Deploy to Android, open the Logcat Viewer (tools/LogcatViewer/project/Trace4D.Logcat.Viewer.Demo.dproj), point it at your adb.exe, select the device and press Start. The Viewer classifies crash/ANR evidence, tracks the UI heartbeat and can export the session as TSV or a diagnostic report.

Project structure

Trace4D/
├─ src/                     # Core: emitter API (Core, Heartbeat, backends)
│                           #   + logcat parsing and analysis (Logcat.*)
├─ tools/
│  └─ LogcatViewer/         # Windows Viewer — the observer
│     ├─ project/           #   .dpr / .dproj
│     └─ src/               #   Main form + tested helper units
├─ examples/
│  └─ BasicTraceDemo/       # FMX Android usage example
│     ├─ project/
│     └─ src/
├─ tests/
│  ├─ project/              # DUnitX runner
│  ├─ samples/              # Real and representative logcat/metrics snapshots
│  └─ src/                  # 18 test units (166 tests)
├─ docs/
│  ├─ en/                   # This book (chapters 01–14)
│  └─ pt-BR/                # Portuguese edition
├─ assets/                  # Banner and screenshots
├─ CHANGELOG.md
├─ LICENSE
├─ README.md
└─ README.pt-BR.md

Recommended reading order

1. Read the overview to understand the purpose of the mechanism.
2. Read ADB/logcat and the Viewer guide to understand the tool.
3. Read Core, Heartbeat, and ANR Timeline to understand how the application emits evidence and which API calls are available.
4. Read the Android interpretation, SurfaceFlinger, and crash chapters to separate operational messages from relevant evidence.
5. Read the examples and tests before reviewing or evolving the code.

Contents

• 01 — Overview and philosophy
• 02 — ADB and logcat
• 03 — Logcat Viewer guide
• 04 — Trace4D.Core, API reference and structured events
• 05 — UI Heartbeat and ANR
• 06 — ANR Timeline and evidence
• 07 — Interpreting Android messages
• 08 — SurfaceFlinger and graphics messages
• 09 — Crash diagnostics
• 10 — ADB troubleshooting
• 11 — Examples
• 12 — Tests
• 13 — License
• 14 — Known limitations

Known limitations

Trace4D 1.0.0 focuses on diagnostics for Delphi FMX Android applications. Some limits are intentional in this first version, such as the Windows-only Viewer, the dependency on ADB and variations in logcat output between Android versions and device manufacturers.

See the full list in chapter 14 — Known limitations.

Versioning

The project follows Semantic Versioning. Release history lives in CHANGELOG.md.

License

Trace4D is distributed under the MIT license.

The project's units use the SPDX identifier MIT. The official legal text must be kept in the repository's LICENSE file. See chapter 13 — License for a short summary.