https://github.com/Gracker/Android-App-Memory-Analysis

Last synced: 2 days ago
JSON representation
Host: GitHub
URL: https://github.com/Gracker/Android-App-Memory-Analysis
Owner: Gracker
Created: 2020-03-27T10:47:16.000Z (about 6 years ago)
Default Branch: master
Last Pushed: 2026-02-10T07:30:18.000Z (4 months ago)
Last Synced: 2026-02-10T13:35:00.467Z (4 months ago)
Language: Python
Size: 26.5 MB
Stars: 149
Watchers: 3
Forks: 36
Open Issues: 2
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

awesome-android-ai-dev-sources - 🐙
README

          # Android App Memory Analysis

[中文版本](./README_zh.md) | English Version

A comprehensive toolkit for Android application memory analysis, featuring **one-click live dump** from connected devices and **multi-source correlation analysis** for deep memory insights.

## Features

### Core Capabilities

| Feature | Description | Root Required |

|---------|-------------|---------------|

| **Live Dump** | One-click dump all memory data from connected device | Partial (see below) |

| **Panorama Analysis** | Multi-source correlation (meminfo + gfxinfo + hprof + smaps) | No |

| **HPROF Analysis** | Java heap analysis, leak detection, large object tracking | No |

| **SMAPS Analysis** | Native memory mapping, detailed memory classification | Yes |

| **Meminfo Analysis** | Parse `dumpsys meminfo` including Native Allocations | No |

| **Gfxinfo Analysis** | Parse `dumpsys gfxinfo` for GPU/Graphics stats | No |

### Root Permission Requirements

| Data Source | Without Root | With Root |

|-------------|--------------|-----------|

| dumpsys meminfo | ✅ Full data | ✅ Full data |

| dumpsys gfxinfo | ✅ Full data | ✅ Full data |

| hprof dump | ⚠️ Debuggable apps only | ✅ All apps |

| smaps | ❌ Permission denied | ✅ Full data |

## Quick Start

### Prerequisites

- Python 3.8+

- ADB (Android Debug Bridge) in your PATH or in `tools/` folder

- Connected Android device with USB debugging enabled

### Android 17 / API 37 Compatibility Notes

- The Demo APK now uses `compileSdk = 37`, `targetSdk = 37`, and demo version `1.1.0`, while keeping Android 16 edge-to-edge handling and 16 KB page-size alignment for native `.so` output.

- The toolkit supports Android 4.0 through Android 17+ input formats; parsing logic includes newer allocator and mapping names such as Scudo, GWP-ASan, DMA-BUF, stack/TLS, and JIT caches.

- Panorama analysis now treats `smaps` as a first-class process-mapping source. It can run with smaps-only input and reports smaps PSS/SwapPSS, native allocator, graphics, DMA-BUF, code, stack, and top mapping evidence without overwriting `dumpsys meminfo` metrics.

- Android 17 app memory limits are an Android 17 all-app runtime behavior on supported devices. Live dump now archives `exit_info.txt`, `memory_limiter_status.txt`, package UID, process lists, Android release/sdk, build fingerprint, and page size before requiring PID-dependent artifacts.

- For `smaps` collection, use fallback order for better device compatibility:

  1) `adb shell cat /proc//smaps`

  2) `adb shell su -c "cat /proc//smaps"`

  3) `adb shell su 0 cat /proc//smaps`

- `pidof` is preferred for PID lookup, and `ps -A` parsing is used as fallback.

- See [Android 17 / API 37 Adaptation Review](./docs/en/android_17_adaptation_review.md) for the Android 17 build, memory-limiter, runtime, and evidence checklist.

- See [Android 16 / API 36 Adaptation Review](./docs/en/android_16_adaptation_review.md) for the Android 16 and 16 KB page-size baseline.

### Installation

```bash

git clone https://github.com/Gracker/Android-App-Memory-Analysis.git

cd Android-App-Memory-Analysis

```

### Usage

#### One-Click Live Dump & Analysis (Recommended)

```bash

# List running apps on connected device

python3 analyze.py live --list

# Dump and analyze a specific app

python3 analyze.py live --package com.example.app

# Quick mode (skip hprof for faster results)

python3 analyze.py live --package com.example.app --skip-hprof

# Dump only (no analysis)

python3 analyze.py live --package com.example.app --dump-only -o ./dumps

```

#### Panorama Analysis (Multi-Source Correlation)

```bash

# Analyze existing dump directory

python3 analyze.py panorama -d ./dumps/com.example.app_20231225_120000

# Analyze individual files

python3 analyze.py panorama -m meminfo.txt -g gfxinfo.txt -H app.hprof -S smaps.txt

# Analyze privileged process mappings only

python3 analyze.py panorama -S smaps.txt --json -o smaps_panorama.json

```

#### Individual File Analysis

```bash

# Analyze Java heap (HPROF)

python3 analyze.py hprof demo/hprof_sample/heapdump_latest.hprof.gz

# Analyze native memory (smaps)

python3 analyze.py smaps demo/smaps_sample/smaps

# Analyze meminfo

python3 analyze.py meminfo dump/meminfo.txt

# Analyze gfxinfo

python3 analyze.py gfxinfo dump/gfxinfo.txt

# Traditional combined analysis (HPROF + smaps)

python3 analyze.py combined -H demo/hprof_sample/heapdump_latest.hprof.gz -S demo/smaps_sample/smaps

# Enhanced combined analysis (meminfo-aware, mtrack included)

python3 analyze.py combined --modern --hprof demo/hprof_sample/heapdump_latest.hprof.gz --smaps demo/smaps_sample/smaps --meminfo demo/smaps_sample/meminfo.txt --json-output report.json

# One-command demo shortcut (built-in hprof+smaps+meminfo)

python3 analyze.py combined --demo --json-output demo_report.json

```

Notes:

- `combined` defaults to legacy mode (`combined_analyzer.py`) unless `--modern`, `--meminfo`, `--pid`, `--json-output`, or `--demo` is provided.

- In modern mode with `-p/--pid`, the tool auto-collects `smaps` and tries to collect `dumpsys meminfo -d`.

- The bundled demo HPROF is committed as `heapdump_latest.hprof.gz` to avoid large-file push limits. The unified `analyze.py` entry point reads `.hprof.gz` directly. If an old sample path ending in `.hprof` is missing but a sibling `.hprof.gz` exists, it automatically falls back to the packaged sample.

## What Gets Analyzed?

### Panorama Analysis Output

The panorama analysis provides a comprehensive view of memory usage:

```

================================================================================

                     Android 内存全景分析报告

================================================================================

📊 Memory Overview:

------------------------------

  Total PSS:        245.67 MB

  Java Heap:        89.34 MB

  Native Heap:      34.21 MB

  Graphics:         45.67 MB

  Code:             23.78 MB

  Stack:            1.23 MB

🖼️ Bitmap Deep Analysis:

------------------------------

  Bitmap (malloced):     27 objects    6.78 MB

  Bitmap (nonmalloced):   8 objects   11.59 MB

  GPU Cache:             15.34 MB

  GraphicBuffer:         12.45 MB

📈 Native Memory Tracking:

------------------------------

  Tracked Native:        28.45 MB (83.2%)

  Untracked Native:       5.76 MB (16.8%)

  ⚠️ Warning: Significant untracked Native memory detected

🎨 UI Resources:

------------------------------

  Views: 1,234

  ViewRootImpl: 3

  Activities: 5

  WebViews: 0

```

### Key Analysis Features

1. **Bitmap Correlation**: Links Java Bitmap objects to Native pixel memory

2. **Native Memory Tracking**: Identifies tracked vs untracked Native allocations

3. **GPU Memory Analysis**: GraphicBuffer and GPU cache usage

4. **UI Resource Counting**: View hierarchy and Activity leak detection

5. **Anomaly Detection**: Automatic warnings for potential issues

## Project Structure

```

Android-App-Memory-Analysis/

├── analyze.py              # Main entry point

├── tools/

│   ├── hprof_parser.py     # HPROF file parser

│   ├── smaps_parser.py     # smaps file parser

│   ├── meminfo_parser.py   # dumpsys meminfo parser

│   ├── gfxinfo_parser.py   # dumpsys gfxinfo parser

│   ├── panorama_analyzer.py # Multi-source correlation analyzer

│   ├── combined_analyzer.py # HPROF + smaps combined analyzer

│   ├── memory_analyzer.py  # Enhanced combined analyzer with meminfo/mtrack correlation

│   ├── live_dumper.py      # Live dump from device

│   ├── hprof_dumper.py     # HPROF dump utility

│   └── adb                 # ADB binary (optional)

├── demo/

│   ├── hprof_sample/       # Latest sample HPROF + analysis output

│   ├── smaps_sample/       # Latest sample smaps/meminfo/showmap/gfxinfo + reports

│   └── memory-lab/         # Demo APK project used to regenerate sample datasets

├── docs/

│   ├── en/                 # English documentation

│   └── zh/                 # Chinese documentation

└── pic/                    # Images for documentation

```

## Documentation

For detailed guides on interpreting analysis results:

- [English Learning Path](./docs/en/README.md)

  - [Analysis Results Guide](./docs/en/analysis_results_interpretation_guide.md)

  - [Meminfo Interpretation](./docs/en/meminfo_interpretation_guide.md)

  - [SMAPS Interpretation](./docs/en/smaps_interpretation_guide.md)

  - [Android 17 / API 37 Adaptation Review](./docs/en/android_17_adaptation_review.md)

  - [Android 16 / API 36 Adaptation Review](./docs/en/android_16_adaptation_review.md)

  - [Teaching Playbook](./docs/en/teaching_playbook.md)

- [Chinese Learning Path](./docs/zh/README.md)

  - [分析结果解读指南](./docs/zh/analysis_results_interpretation_guide.md)

  - [meminfo 解读](./docs/zh/meminfo_interpretation_guide.md)

  - [smaps 解读](./docs/zh/smaps_interpretation_guide.md)

  - [Android 17 / API 37 适配 Review](./docs/zh/android_17_adaptation_review.md)

  - [教学实践手册](./docs/zh/teaching_playbook.md)

  - [Demo APK case study (Chinese)](./docs/zh/memory_lab_demo_case_study.md)

## Data Sources

| Data Source | Command | Information Provided |

|-------------|---------|---------------------|

| smaps | `cat /proc//smaps` | Detailed memory mapping |

| hprof | `am dumpheap  ` | Java heap objects and references |

| meminfo | `dumpsys meminfo ` | Summary + Native Allocations (Bitmap stats) |

| gfxinfo | `dumpsys gfxinfo ` | GPU cache, GraphicBuffer, frame stats |

## Related Tools

This toolkit complements these Android memory analysis tools:

- **Android Studio Profiler**: Real-time memory monitoring

- **LeakCanary**: Automatic memory leak detection

- **MAT (Memory Analyzer Tool)**: Deep HPROF analysis

- **Perfetto**: System-wide tracing

## Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

## License

This project is open source. See LICENSE file for details.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/Gracker/Android-App-Memory-Analysis

Awesome Lists containing this project

README
