Log

Why provide KeePassDX logs?

KeePassDX is open source, and even though it undergoes extensive testing, bugs and errors can still occur. As each environment is different, with devices that have different overlays and databases, the help of the community is crucial to eradicating these bugs.

To understand a behavior, reproduce it and see which piece of code isn't working properly, it's necessary to analyze logs that trace the application's behavior. These logs allows us to contextualize errors and identify them so we can analyze and resolve them more quickly when you open an issue.

No sensitive data is included in the logs, only metadata.

How to extract Logs

This guide will walk you through setting up your environment and using ADB's logcat command to filter and capture logs specifically from KeePassDX.

Please note that the procedure below is for non-rooted phones. For a rooted phone, just use a simple method such as logging applications. Logging applications can also provide a filter interface so you don't have to write commands from the PC, but still require ADB if the device is unrooted.

KeePassDX can also be debugged directly from your local Android Studio IDE. However, this requires knowledge of Android development and the correct version of Android Studio.

Requirements

If you haven't already, install ADB on your computer. You can follow the instructions provided below or find detailed guides for your operating system (Windows, macOS, Linux) on the Android Developer website. Verify ADB installation by opening your computer's command line/terminal and type adb devices. If ADB is installed correctly, you should see output indicating no devices or a list of connected devices.

Android Phone Setup:

• Use a reliable USB data cable to connect your Android phone to your computer.

• Go to Settings > About phone (or About device) and tap Build number 7 times rapidly until You are now a developer! appears to enable Developer Options.

• Go back to Settings > System > Developer options (or simply Developer options directly under Settings) and toggle on USB debugging.

• When prompted, allow USB debugging for your computer. You might also want to check Always allow from this computer.

ADB Connection

• Open your computer's Command Prompt (Windows), Terminal (macOS/Linux) and type the following command and press Enter:

adb devices

You should see your device listed, for example:

    List of devices attached
    XXXXXXXXXXXXXX    device

If it says unauthorized, check your phone screen for a "Allow USB debugging?" prompt and tap "OK" (and optionally "Always allow from this computer"). Then re-run adb devices.

If no device is listed, ensure USB debugging is enabled, the cable is good, and necessary drivers are installed (especially for Windows).

Capture Logs with ADB

1. Before capturing logs, you might want to clear the device's log buffer to ensure you only get fresh logs related to your actions:

adb logcat -c

2. Create log file:

• MacOS/Linux (using grep):

adb logcat | grep "com.kunzisoft.keepass" > keepassdx_logs.txt

• Windows (using findstr in Command Prompt):

adb logcat | findstr "com.kunzisoft.keepass" > keepassdx_logs.txt

• Windows (PowerShell's Select-String is similar to grep):

adb logcat | Select-String "com.kunzisoft.keepass" > keepassdx_logs.txt

This will start log capture and create a specific log file containing only non-sensitive KeePassDX metadata.

3. Reproduce the Issue:

Once logcat is running, go to your Android phone, perform the actions that lead to the issue you are trying to debug in KeePassDX.

4. Stop Log Capture:

After reproducing the issue (or after the app crashes), switch back to your computer's command line/terminal and stop the logcat process by pressing Ctrl + C (on Windows/Linux) or Cmd + C (on macOS).

5. Review the Log File:

You can now open the -keepassdx_logs.txt- file with any text editor to review the collected logs. Look for error messages, exceptions, or any relevant information around the time the issue occurred and you can upload the file to your github issue.

By following these steps, you should be able to effectively extract and review logs from KeePassDX on your Android phone, aiding in debugging and troubleshooting.

Log applications

You can then use an Android application to extract the logs you need from ADB.

• LogFox
• Logcat Reader

---

ADB

Android Debug Bridge (ADB) is a versatile command-line tool used by developers and tech enthusiasts to communicate with and control Android devices (phones, tablets, etc.) from a computer. It allows you to perform various tasks such as debugging software and viewing system logs.

ADB Installation

Installing ADB on your computer is relatively straightforward, but the exact steps vary slightly depending on your operating system (Windows, macOS, or Linux).

Windows

The easiest way is to download the standalone platform-tools package.

1. Go to the official Android Developers website: https://developer.android.com/tools/releases/platform-tools and download the "SDK Platform-Tools for Windows" ZIP file.

2. Create a new folder in a convenient location (e.g., C:\platform-tools or C:\Users\YourUser\platform-tools) and extract the contents of the downloaded ZIP file into this new folder. You should see adb.exe, fastboot.exe, and other files inside.

3. Navigate to the platform-tools folder you just created using File Explorer. In the address bar of File Explorer, type cmd and press Enter. This will open a Command Prompt window directly in that folder. Alternatively, you can type powershell and press Enter to open PowerShell.

4. Connect your Android device to your computer via USB. In the Command Prompt/PowerShell window, type:

adb devices

5. On your phone, you might see a pop-up asking to "Allow USB debugging." Tap "Always allow from this computer" and then "OK."

6. Run adb devices again. You should now see your device listed with a serial number. If it says "unauthorized," ensure you've allowed USB debugging on your device.

7. Optional: Add ADB to your System PATH (for advanced users): This allows you to run adb commands from any directory in Command Prompt/PowerShell, not just from within the platform-tools folder.

   • Search for "Environment Variables" in Windows Search and select "Edit the system environment variables."
   • Click "Environment Variables..."
   • Under "System variables," find the Path variable and double-click it.
   • Click "New" and add the full path to your platform-tools folder (e.g., C:\platform-tools).
   • Click "OK" on all open windows.
   • Restart your Command Prompt/PowerShell for the changes to take effect.

MacOS

Homebrew is a popular package manager for macOS that makes installing command-line tools very easy.

1. Open Terminal (Applications > Utilities > Terminal) and paste the following command, then press Enter:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

and follow the on-screen instructions.

2. Once Homebrew is installed, in Terminal, type: bash brew install --cask android-platform-tools and follow the on-screen instructions.

3. Connect your Android device to your computer via USB and type in terminal :

adb devices

4. On your phone, allow USB debugging when prompted.
5. Run adb devices again. Your device should appear.

Linux

Most Linux distributions include ADB/Fastboot in their official repositories, making installation very simple.

1. Open Terminal and type:

• Debian/Ubuntu-based distributions

sudo apt update
sudo apt install android-sdk-platform-tools-core

Some older guides might suggest adb or android-tools-adb, but android-sdk-platform-tools-core is generally the correct package for the latest versions.

• Fedora/SUSE-based distributions

sudo dnf install android-tools

• Arch Linux (and derivatives like Manjaro)

sudo pacman -S android-tools

2. Connect your Android device to your computer via USB and type in terminal:

adb devices

3. On your phone, allow USB debugging when prompted.
4. Run adb devices again. Your device should appear.

Troubleshooting

• "unauthorized" device: Make sure you've enabled USB Debugging and allowed the computer's fingerprint on your phone when prompted. You might need to revoke USB debugging authorizations in Developer Options and re-plug the device.
• "device not found":
  • Try a different USB port or cable.
  • Ensure your device's USB mode is set to "File transfer" (MTP) if that option is available.
  • Restart your computer and phone.
  • On Windows, you might need to install specific USB drivers for your Android device's manufacturer. Many manufacturers provide these on their support websites.
• ADB server not running: If you get an error like "adb server not running," try adb kill-server followed by adb start-server in your terminal.