{"id":20101914,"url":"https://github.com/manabu-gt/debugoverlay-android","last_synced_at":"2026-04-02T17:50:28.072Z","repository":{"id":57726767,"uuid":"86544386","full_name":"Manabu-GT/DebugOverlay-Android","owner":"Manabu-GT","description":"Android library to display various debugging information in an overlay window","archived":false,"fork":false,"pushed_at":"2017-11-11T08:47:30.000Z","size":1207,"stargazers_count":100,"open_issues_count":5,"forks_count":22,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-06-21T04:30:24.337Z","etag":null,"topics":["android","android-library","cpu","debugoverlay","fps","logcat","network-statistics","overlay-window","pss","timber"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Manabu-GT.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-29T06:05:51.000Z","updated_at":"2024-05-12T19:13:07.000Z","dependencies_parsed_at":"2022-09-26T21:51:01.388Z","dependency_job_id":null,"html_url":"https://github.com/Manabu-GT/DebugOverlay-Android","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Manabu-GT%2FDebugOverlay-Android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Manabu-GT%2FDebugOverlay-Android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Manabu-GT%2FDebugOverlay-Android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Manabu-GT%2FDebugOverlay-Android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Manabu-GT","download_url":"https://codeload.github.com/Manabu-GT/DebugOverlay-Android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224493990,"owners_count":17320620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-library","cpu","debugoverlay","fps","logcat","network-statistics","overlay-window","pss","timber"],"created_at":"2024-11-13T17:27:23.828Z","updated_at":"2026-01-27T07:17:21.396Z","avatar_url":"https://github.com/Manabu-GT.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"DebugOverlay-Android\n===========\n[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-DebugOverlay--Android-brightgreen.svg?style=flat)](https://android-arsenal.com/details/1/5516)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.ms-square/debugoverlay/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.ms-square/debugoverlay)\n[![API 16+](https://img.shields.io/badge/API-16%2B-brightgreen.svg?style=flat)](https://android-arsenal.com/api?level=16)\n[![License](https://img.shields.io/badge/license-Apache%202-brightgreen.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n\n**DebugOverlay** is an Android library that allows developers to easily add custom overlay window/view for debugging purpose.\n\nYou can use it to show some performance related metrics such as cpu, memory, and fps. Or you can show logcat messages within your app for light debugging.\n\nThis library is fully customizable in terms of what you can show on the overlay. If you want to show something other than what's being provided, please go ahead and create your own overlay module!\n\n\u003cimg src=\"art/readme_simple_demo.gif\" width=\"50%\" alt=\"DebugOverlay Simple Demo\"\u003e\n\nRequirements\n-------------\nAPI Level 16 (Android 4.1) and above.\n\nSetup\n------\nThe library is pushed to Maven Central as an AAR,\nso you just need to add the followings to your ***build.gradle*** file:\n\n```groovy\ndependencies {\n  debugCompile 'com.ms-square:debugoverlay:1.1.3'\n  releaseCompile 'com.ms-square:debugoverlay-no-op:1.1.3'\n  testCompile 'com.ms-square:debugoverlay-no-op:1.1.3'\n}\n```\n\nPlease note that `com.ms-square:debugoverlay:1.1.3`  will add `android.permission.SYSTEM_ALERT_WINDOW`  to your app.\nThrefore, you should avoid to use that dependency for your release build.\n\nFYI, the following table describes the total number of method/field references in this library's release aar.\nThis data is acquired by using [Dexcount Gradle Plugin](https://github.com/KeepSafe/dexcount-gradle-plugin).\n\n| library  | methods  | fields |\n|:------------- |:-------------|:-------------|\n|com.ms-square:debugoverlay:1.1.3|566|252|\n|com.ms-square:debugoverlay-no-op:1.1.3|141|37|\n\nDue to the extensibility of this library, no-op version unfortunately has more than a few methods.\nIf you want to eliminate such method count in your release build, consider having separate `Application` class only for your debug build which uses this library and just specify `debugCompile 'com.ms-square:debugoverlay:1.1.3'` in the dependencies section of build.gradle.\n\nUsage\n------\n\n### Simple\n\nIn your `Application` class:\n\n```java\npublic class ExampleApplication extends Application {\n\n  @Override public void onCreate() {\n    super.onCreate();\n    DebugOverlay.with(this).install();\n    // Normal app init code...\n  }\n}\n```\nIt will show a debug overlay on system layer with the follwing three default modules just like the gif animation image displayed on this README.\n\n- [CpuUsageModule](#cpuusagemodule) - will not be shown on Android O and above\n- [MemInfoModule](#meminfomodule)\n- [FpsModule](#fpsmodule)\n\n### w/ Configurations\n\n\u003cimg src=\"art/overlay_with_configurations.png\" width=\"50%\" alt=\"DebugOverlay Screen Capture\"\u003e\n\n```java\nnew DebugOverlay.Builder(this)\n        .modules(new CpuUsageModule(),\n                new MemInfoModule(this),\n                new FpsModule(),\n                new LogcatModule())\n        .position(Position.BOTTOM_START)\n        .bgColor(Color.parseColor(\"#60000000\"))\n        .textColor(Color.MAGENTA)\n        .textSize(14f)\n        .textAlpha(.8f)\n        .allowSystemLayer(true)\n        .notification(true, MainActivity.class.getName())\n        .build()\n        .install();\n```\n\n* modules - [list or as variable length arguments]\n\u003eList of [OverlayModule][3]s to install\n\n* position - [Position]\n\u003eEnum which specifies where to show the overlay. Default is `BOTTOM_START`.\n\n* bgColor - [color]\n\u003eColor used for the background of the overlay. Default is `25% Black`.\n\n* textColor - [color]\n\u003eColor used for text on the overlay. Default is `White`.\n\n* textSize - [float]\n\u003eSize in `sp` used for text on the overlay. Default is `12sp`.\n\n* textAlpha - [float]\n\u003eAlpha value used for text on the overlay.  Default is `1f`(fully opaque).\n\n* allowSystemLayer - [boolean]\n\u003eIf true, it adds the overlay window on Android's system window layer; in Android 7.1.1 and after, it will ask you for the overlay permission by taking you to the Android's settings screen when you first set up. If set to false, it  will automatically add the overlay on each application window. In most cases, you want to set this to `true`.\nDefault is `true`.\n\n* notification - [boolean, string(optional)]\n\u003e *applicable only when allowSystemLayer is set to true*\n\u003e\n\u003e When set to true, it will show notification which allows you to show/hide the overlay window.\nDefault is `true`.\nYou can optionally supply string which must be your *activity's class name*.\nIt will be used to create PendingIntent to start the activity when the notification is tapped.\n\nProvided Modules\n------\n\n#### CpuUsageModule\n\n`default`\n\u003e Collects total and app cpu usage % by reading `/proc/stat` and `/proc/[myPid]/stat` respectively.\n\nNote: CpuUsageModule will be no-op on Android O and above. Please see this [issue](https://github.com/Manabu-GT/DebugOverlay-Android/issues/11) for why.\n\n#### MemInfoModule\n\n`default`\n\u003e Collects device's current available memory, app's total PSS, and app's total private dirty info. Display unit is in `Megabyte`.\n\nRefer to [Investigating Your RAM Usage](https://developer.android.com/studio/profile/investigate-ram.html#ViewingAllocations) for more info about PSS and private dirty RAM.\n\nIf low memory situation is detected by reading [lowMemory](https://developer.android.com/reference/android/app/ActivityManager.MemoryInfo.html#lowMemory), texts will be automatically displayed in `RED`.\n\n#### FpsModule\n`default`\n\u003e Measures FPS using [Choreographer](https://developer.android.com/reference/android/view/Choreographer.html).\n\n#### LogcatModule\n`optional`\n\u003e Collects logcat messages generated by your own app even on non-rooted devices.\n\n#### CpuFreqModule\n`optional`\n\u003e Collects each cpu core's current and max frequency by reading `/sys/devices/system/cpu/cpu[num]/cpufreq/scaling_cur_freq` and `/sys/devices/system/cpu/cpu[num]/cpufreq/cpuinfo_max_freq` respectively.\n\nNote: CpuFreqModule will be no-op on Android O and above. Please see this [issue](https://github.com/Manabu-GT/DebugOverlay-Android/issues/11) for why.\n\nExtension Modules (available separately)\n------\n#### TimberModule\n`optional`\n\u003e An extension module which shows [Timber](https://github.com/JakeWharton/timber) logs for debugging.\n\nFor details, please check out [debugoverlay-ext-timber](https://github.com/Manabu-GT/DebugOverlay-Android/tree/develop/debugoverlay-ext-timber).\n\n#### NetStatsModule\n`optional`\n\u003e An extension module which shows the total network usage of the application. The stats include all network interfaces, and both TCP and UDP usage.\n\nFor details, please check out [debugoverlay-ext-netstats](https://github.com/Manabu-GT/DebugOverlay-Android/tree/develop/debugoverlay-ext-netstats).\n\nCustomization\n------\n\n### Filtering and coloring scheme of logcat view\n\n\n#### Filtering\n\n* [LogcatLineFilter][1]\n\nimplement the follwing IF method\n\n```java\nboolean shouldFilterOut(LogcatLine.Priority priority, @NonNull String tag)\n```\n\n#### Coloring\n\n* [LogcatLineColorScheme][2]\n\nimplement the follwing IF method\n\n```java\n@ColorInt\nint getTextColor(LogcatLine.Priority priority, @NonNull String tag)\n```\n\nExample:\n\n```java\n// filtering with LogcatLineFilter.SimpleLogcatLineFilter\n// it filters out VERBOSE logs because DEBUG is minimum priority required\nmodule = new LogcatModule(LogcatModule.DEFAULT_MAX_LINES,\n                new LogcatLineFilter.SimpleLogcatLineFilter(LogcatLine.Priority.DEBUG));\n\n// filtering with your own line filter\nmodule = new LogcatModule(LogcatModule.DEFAULT_MAX_LINES, your_line_filter);\n\n// coloring\nmodule = new LogcatModule(LogcatModule.DEFAULT_MAX_LINES, your_color_scheme);\n\n// both\nmodule = new LogcatModule(LogcatModule.DEFAULT_MAX_LINES, your_line_filter, your_color_scheme);\n```\n\n### Using custom overlay view for provided modules\n\nFor any modules provided, you can pass your own implementation of [ViewModule][5] to use your custom view entirely to display the module data.\n\nExample:\n\n```java\n// here, MyCpuViewModule must implement ViewModule interface\nmodule = new CpuUsageModule(new MyCpuViewModule());\n```\n\nFor **CpuUsage, CpuFreq, MemInfo, and Fps modules**, you can pass your own layout resource id as long as it contains TextView as a direct child with id set to `debugoverlay_overlay_text` which is already defined in this library. This allows you to style the TextView used within those modules very easily without fully implementing new [ViewModule][5] by yourself.\n\n### Adding your own overlay module\n\nAs an example, let's add a new overlay module in the [sample project][7] which displays a list of IP addresses on your device. It can be quite useful if you have any server-type service running within your app.\n\nFor any type of module you want to add, you need to implement the following three types of components. (In most cases, the real work will be done in [DataModule][4].)\n\n- [OverlayModule][3] - composed of DataModule and ViewModule\n - [DataModule][4] - responsible for getting data and notifying its observers\n - [ViewModule][5] - responsible for creating an overlay view and updating it with the latest data\n\nSince this is a very simple overlay module which is going to display just one line of text using TextView, you can just use the provided [SimpleViewModule][6] as ViewModule.\n\nDataModule is where the hardwork is done to get some meaningful data to show.\nIn this case, it will look like the following. For its full implementation, please take a look at [IPAddressDataModule][8].\n\n```java\npublic class IPAddressDataModule extends BaseDataModule\u003cString\u003e {\n    ....\n    @Override\n    public void start() {\n        context.registerReceiver(receiver, new IntentFilter(ConnectivityManager.CONNECTIVITY_ACTION));\n        ipAddresses = getV4IPAddressesString();\n        notifyObservers();\n    }\n\n    @Override\n    public void stop() {\n        context.unregisterReceiver(receiver);\n    }\n\n    @Override\n    protected String getLatestData() {\n        return ipAddresses;\n    }\n    ....\n}\n```\n\nWe're almost done. Now just subclass [OverlayModule][3] and create `IPAddressModule` class  using the `IPAddressDataModule` as its data module.\n\n```java\npublic class IPAddressModule extends OverlayModule\u003cString\u003e {\n\n    public IPAddressModule(@NonNull Context context) {\n        super(new IPAddressDataModule(context), new SimpleViewModule(R.layout.view_overlay_ip));\n    }\n}\n```\n\nSince a new custom module called `IPAddressModule` is created, let's actually show it on the overlay.\n\n```java\n// inside Application's onCreate()\nnew DebugOverlay.Builder(this)\n        .modules(new CpuFreqModule(),\n                 new CpuUsageModule(),\n                 new MemInfoModule(this),\n                 new FpsModule(),\n                 new IPAddressModule(this))\n                .build()\n                .install();\n```\n\nNow, the overlay successfully shows the newly added custom module at the bottom.\n\n\u003cimg src=\"art/overlay_with_custom_module_and_cpufreq_small.png\" width=\"50%\" alt=\"DebugOverlay Screen Capture\"\u003e\n\nThanks for reading!\n\nLicense\n----------\n\n    Copyright 2017 Manabu Shimobe\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n\n[1]: https://github.com/Manabu-GT/DebugOverlay-Android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/modules/LogcatLineFilter.java\n[2]: https://github.com/Manabu-GT/DebugOverlay-Android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/modules/LogcatLineColorScheme.java\n[3]: https://github.com/Manabu-GT/DebugOverlay-Android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/OverlayModule.java\n[4]: https://github.com/Manabu-GT/DebugOverlay-Android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/DataModule.java\n[5]: https://github.com/Manabu-GT/DebugOverlay-Android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/ViewModule.java\n[6]: https://github.com/Manabu-GT/DebugOverlay-Android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/modules/SimpleViewModule.java\n[7]: https://github.com/Manabu-GT/DebugOverlay-Android/tree/master/sample\n[8]: https://github.com/Manabu-GT/DebugOverlay-Android/tree/master/sample/src/main/java/com/ms_square/debugoverlay/sample/IPAddressDataModule.java","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanabu-gt%2Fdebugoverlay-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanabu-gt%2Fdebugoverlay-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanabu-gt%2Fdebugoverlay-android/lists"}