(中文版本请参看这里)

Matrix for iOS/macOS 中文版
Matrix for android 中文版
Matrix for iOS/macOS
Matrix for android

Matrix is an APM (Application Performance Manage) used in Wechat to monitor, locate and analyse performance problems. It is a plugin style, non-invasive solution and is currently available on iOS, macOS and Android.

Matrix for iOS/macOS

The monitoring scope of the current tool includes: crash, lag, and memory, which includes the following three plugins:

• WCCrashBlockMonitorPlugin： Based on KSCrash framework, it features cutting-edge lag stack capture capabilities with crash capture.

• WCMemoryStatPlugin： A memory monitoring tool that captures memory allocation and the callstack of an application's memory event.

• WCFPSMonitorPlugin： A fps monitoring tool that captures main thread's callstack while user scrolling.

Features

WCCrashBlockMonitorPlugin

• Easy integration, no code intrusion.
• Determine whether the app is stuck by checking the running status of the Runloop, and support both the iOS and macOS platform.
• Add time-consuming stack fetching, attaching the most time-consuming main thread stack to the thread snapshot log.

WCMemoryStatPlugin

• Live recording every object's creating and the corresponding callstack of its creation, and report it when the application out-of-memory is detected.

Getting Started

Install

• Install with static framework
• Get source code of Matrix;
• Open terminal, execute make in the matrix/matrix-iOS directory to compile and generate static library. After compiling, the iOS platform library is in the matrix/matrix-iOS/build_ios directory, and the macOS platform library is in the matrix/matrix-iOS/build_macos directory.
• Link with static framework in the project:
  • iOS : Use Matrix.framework under the matrix/matrix-iOS/build_ios path, link Matrix.framework to the project as a static library;
  • macOS : Use Matrix.framework under the matrix/matrix-iOS/build_macos path, link Matrix.framework to the project as a static library.
• Add #import <Matrix/Matrix.h>, then you can use the performance probe tool of WeChat.

Start the plugins

In the following places:

• Program main function;
• application:didFinishLaunchingWithOptions: of AppDelegate;
• Or other places running as earlier as possible after application launching.

Add a code similar to the following to start the plugin:

#import <Matrix/Matrix.h>

Matrix *matrix = [Matrix sharedInstance];
MatrixBuilder *curBuilder = [[MatrixBuilder alloc] init];
curBuilder.pluginListener = self; // get the related event of plugin via the callback of the pluginListener

WCCrashBlockMonitorPlugin *crashBlockPlugin = [[WCCrashBlockMonitorPlugin alloc] init];    
[curBuilder addPlugin:crashBlockPlugin]; // add lag and crash monitor.

WCMemoryStatPlugin *memoryStatPlugin = [[WCMemoryStatPlugin alloc] init];
[curBuilder addPlugin:memoryStatPlugin]; // add memory monitor.

WCFPSMonitorPlugin *fpsMonitorPlugin = [[WCFPSMonitorPlugin alloc] init];
[curBuilder addPlugin:fpsMonitorPlugin]; // add fps monitor.

[matrix addMatrixBuilder:curBuilder];

[crashBlockPlugin start]; // start the lag and crash monitor.
[memoryStatPlugin start]; // start memory monitor
[fpsMonitorPlugin start]; // start fps monitor

Receive callbacks to obtain monitoring data

Set pluginListener of the MatrixBuilder object, implement the MatrixPluginListenerDelegate

// set delegate

MatrixBuilder *curBuilder = [[MatrixBuilder alloc] init];
curBuilder.pluginListener = <object conforms to MatrixPluginListenerDelegate>; 

// MatrixPluginListenerDelegate

- (void)onInit:(id<MatrixPluginProtocol>)plugin;
- (void)onStart:(id<MatrixPluginProtocol>)plugin;
- (void)onStop:(id<MatrixPluginProtocol>)plugin;
- (void)onDestroy:(id<MatrixPluginProtocol>)plugin;
- (void)onReportIssue:(MatrixIssue *)issue;

Each plugin added to MatrixBuilder will call back the corresponding event via pluginListener.

Important: Get the monitoring data of the Matrix via onReportIssue:, the data format info reference to Matrix for iOS/macOS Data Format Description

Tutorials

At this point, Matrix has been integrated into the app and is beginning to collect crash, lag, and memory data. If you still have questions, check out the example: samples/sample-iOS/MatrixDemo.

Matrix for android

Plugins

• APK Checker:

Analyse the APK package, give suggestions of reducing the APK's size; Compare two APK and find out the most significant increment on size

• Resource Canary:

Detect the activity leak and bitmap duplication basing on WeakReference and Square Haha

• Trace Canary:

FPS Monitor, Startup Performance, ANR, UI-Block / Slow Method Detection

• SQLite Lint:

Evaluate the quality of SQLite statement automatically by using SQLite official tools

• IO Canary:

Detect the file IO issues, including performance of file IO and closeable leak

• Battery Canary:

App thread activities monitor (Background watch & foreground loop watch), Sonsor usage monitor (WakeLock/Alarm/Gps/Wifi/Bluetooth), Background network activities (Wifi/Mobile) monitor.

• MemGuard

Detect heap memory overlap, use-after-free and double free issues.

Features

APK Checker

• Easy-to-use. Matrix provides a JAR tool, which is more convenient to apply to your integration systems.
• More features. In addition to APK Analyzer, Matrix find out the R redundancies, the dynamic libraries statically linked STL, unused resources, and supports custom checking rules.
• Visual Outputs. supports HTML and JSON outputs.

Resource Canary

• Separated detection and analysis. Make possible to use in automated test and in release versions (monitor only).
• Pruned Hprof. Remove the useless data in hprof and easier to upload.
• Detection of duplicate bitmap.

Trace Canary

• High performance. Dynamically modify bytecode at compile time, record function cost and call stack with little performance loss.
• Accurate call stack of ui-block. Provide informations such as call stack, function cost, execution times to solve the problem of ui-block quickly.
• Non-hack. High compatibility to Android versions.
• More features. Automatically covers multiple fluency indicators such as ui-block, startup time, activity switching, slow function detection.
• High-accuracy ANR detector. Detect ANRs accurately and give ANR trace file with high compatibility and high stability.

SQLite Lint

• Easy-to-use. Non-invasive.
• High applicability. Regardless of the amount of data, you can discover SQLite performance problems during development and testing.
• High standards. Detection algorithms based on best practices, make SQLite statements to the highest quality.
• May support multi-platform. Implementing in C++ makes it possible to support multi-platform.

IO Canary

• Easy-to-use. Non-invasive.
• More feature. Including performance of file IO and closeable leak.
• Compatible with Android P.

Battery Canary

• Easy-to-use. Use out of box (unit tests as example).
• More feature. Flexible extending with base and utils APIs.

Memory Hook

• A native memory leak detection tool for Android.
• Non-invasive. It is based on PLT-hook(iqiyi/xHook), so we do NOT need to recompile the native libraries.
• High performance. we use WeChat-Backtrace for fast unwinding which supports both aarch64 and armeabi-v7a architectures.

Pthread Hook

• A Java and native thread leak detection and native thread stack space trimming tool for Android.
• Non-invasive. It is based on PLT-hook(iqiyi/xHook), so we do NOT need to recompile the native libraries.
• It saves virtual memory overhead by trimming default stack size of native thread in half, which can reduce crashes caused by virtual memory insufficient under 32bit environment.

WVPreAllocHook

• A tool for saving virtual memory overhead caused by WebView preloading when WebView is not actually used. It's useful for reducing crashes caused by virtual memory insufficient under 32bit environment.
• Non-invasive. It is based on PLT-hook(iqiyi/xHook), so we do NOT need to recompile the native libraries.
• WebView still works after using this tool.

MemGuard

• A tool base on GWP-Asan to detect heap memory issues.
• Non-invasive. It is based on PLT-hook(iqiyi/xHook), so we do NOT need to recompile the native libraries.

• It's able to apply on specific libraries that needs to be detected by RegEx.

• It detects heap memory accessing overlap, use-after-free and double free issues.

Backtrace Component

• A fast native backtrace component designed by Matrix based on quicken unwind tables that are generated and simplified from DWARF and ARM exception handling informations. It is about 15x ~ 30x faster than libunwindstack.

Getting Started

The JCenter repository will stop service on February 1, 2022. So we uploaded Matrix(since 0.8.0) to the MavenCentral repository.

1. Configure MATRIX_VERSION in gradle.properties.

  MATRIX_VERSION=2.1.0

1. Add matrix-gradle-plugin in your build.gradle:

  dependencies {
      classpath ("com.tencent.matrix:matrix-gradle-plugin:${MATRIX_VERSION}") { changing = true }
  }

1. Add dependencies to your app/build.gradle.

  dependencies {
    implementation group: "com.tencent.matrix", name: "matrix-android-lib", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-android-commons", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-trace-canary", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-resource-canary-android", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-resource-canary-common", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-io-canary", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-sqlite-lint-android-sdk", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-battery-canary", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-hooks", version: MATRIX_VERSION, changing: true
    implementation group: "com.tencent.matrix", name: "matrix-backtrace", version: MATRIX_VERSION, changing: true
  }

  apply plugin: 'com.tencent.matrix-plugin'
  matrix {
    trace {
        enable = true   //if you don't want to use trace canary, set false
        baseMethodMapFile = "${project.buildDir}/matrix_output/Debug.methodmap"
        blackListFile = "${project.projectDir}/matrixTrace/blackMethodList.txt"
    }
  }

1. Implement PluginListener to receive data processed by Matrix.

  public class TestPluginListener extends DefaultPluginListener {
    public static final String TAG = "Matrix.TestPluginListener";
    public TestPluginListener(Context context) {
        super(context);

    }

    @Override
    public void onReportIssue(Issue issue) {
        super.onReportIssue(issue);
        MatrixLog.e(TAG, issue.toString());

        //add your code to process data
    }
}

Matrix gradle plugin could work with Android Gradle Plugin 3.5.0/4.0.0/4.1.0 currently.

1. Implement DynamicConfig to change parameters of Matrix.

  public class DynamicConfigImplDemo implements IDynamicConfig {
    public DynamicConfigImplDemo() {}

    public boolean isFPSEnable() { return true;}
    public boolean isTraceEnable() { return true; }
    public boolean isMatrixEnable() { return true; }
    public boolean isDumpHprof() {  return false;}

    @Override
    public String get(String key, String defStr) {
        //hook to change default values
    }

    @Override
    public int get(String key, int defInt) {
      //hook to change default values
    }

    @Override
    public long get(String key, long defLong) {
        //hook to change default values
    }

    @Override
    public boolean get(String key, boolean defBool) {
        //hook to change default values
    }

    @Override
    public float get(String key, float defFloat) {
        //hook to change default values
    }
}

1. Init Matrix in the onCreate of your application.

``` java Matrix.Builder builder = new Matrix.Builder(application); // build matrix builder.patchListener(new TestPluginListener(this)); // add general pluginListener DynamicConfigImplDemo dynamicConfig = new DynamicConfigImplDemo(); // dynamic config

// init plugin IOCanaryPlugin ioCanaryPlugin = new IOCanaryPlugin(new