pykdebugparser

1.2.7 · active · verified Thu Apr 16

pykdebugparser is a Python library designed to parse Darwin's (iOS and macOS) kdebug events and ktraces. It provides utilities to convert raw kdebug dumps into meaningful traces, offering a more formatted output compared to tools like `fs_usage` or `ktrace`. Currently at version 1.2.7, the library is actively maintained with frequent updates for bug fixes, compatibility with newer Python versions, and expanded event handling.

Common errors

```
ModuleNotFoundError: No module named 'pykdebugparser.pykdebugparser'
```
cause The `PyKdebugParser` class is nested within a submodule of the same name. Users often attempt to import it directly from the top-level package.

fix Change your import statement to `from pykdebugparser.pykdebugparser import PyKdebugParser`.
```
FileNotFoundError: [Errno 2] No such file or directory: 'kdebug.bin'
```
cause The specified kdebug trace file does not exist at the given path or the path is incorrect.

fix Ensure the kdebug trace file exists in the specified location. On macOS, you can generate a `ktrace` file using `sudo ktrace dump`.
```
struct.error: unpack requires a buffer of ... bytes
```
cause This error occurs when the input binary file is corrupted, malformed, or not a valid kdebug trace, causing the internal `struct` unpacking to fail.

fix Verify the integrity and source of your `kdebug` file. Ensure it is a genuine, uncorrupted binary trace generated by a Darwin system. Try generating a fresh trace file.

Warnings

gotcha The `pykdebugparser` library is designed exclusively for parsing kdebug events from Darwin (iOS and macOS) systems. Using it with trace files from other operating systems (e.g., Linux `perf` or Windows ETW) will lead to parsing errors or unexpected behavior.
Fix: Ensure trace files originate from a Darwin-based system. On macOS, use `sudo ktrace dump` to generate compatible kdebug traces.
deprecated Official CI support for Python 3.7 was removed in `v1.2.5`. While the library might still function on Python 3.7, it is highly recommended to upgrade to Python 3.8 or newer to ensure full compatibility, stability, and ongoing support.
Fix: Upgrade your Python environment to version 3.8 or later.
gotcha The `PyKdebugParser` expects raw binary kdebug trace files. Passing incorrectly formatted, corrupted, or non-binary files will result in low-level parsing failures such as `struct.error` or `IndexError`.
Fix: Verify the integrity and format of your kdebug trace file. Ensure it was generated as a raw binary dump from a Darwin system (e.g., using `ktrace dump`).

Install

pip install pykdebugparser Install latest stable version

Imports

PyKdebugParser
wrong:
```
from pykdebugparser import PyKdebugParser
```
correct:
```
from pykdebugparser.pykdebugparser import PyKdebugParser
```
The main class is nested within a submodule of the same name. Attempting to import directly from the top-level package will result in a ModuleNotFoundError.

Quickstart

Initialize the PyKdebugParser and attempt to open a kdebug trace file. The example includes creating a simple dummy file for demonstration purposes if a real kdebug.bin is not present. For actual usage, generate a trace using `sudo ktrace dump` on a macOS system.

import os
from pykdebugparser.pykdebugparser import PyKdebugParser

# Create a dummy kdebug.bin for demonstration if it doesn't exist
dummy_kdebug_path = 'kdebug.bin'
if not os.path.exists(dummy_kdebug_path):
    print(f"Creating a dummy '{dummy_kdebug_path}' file for quickstart example.")
    # A minimal, valid kdebug header (approximate structure, might not be fully functional)
    # This is highly simplified and for demonstration purposes only.
    # Real kdebug files require specific kernel structures.
    # For a real trace, use `sudo ktrace dump` on macOS.
    dummy_content = b'\x00\x00\x00\x00\x00\x00\x00\x00' * 10 # Simulate some binary data
    with open(dummy_kdebug_path, 'wb') as f:
        f.write(dummy_content)

parser = PyKdebugParser()
parser.color = True # Enable colored output

try:
    with open(dummy_kdebug_path, 'rb') as f:
        # In a real scenario, you'd iterate over parsed events or traces
        # For this quickstart, we'll just demonstrate opening and a basic print.
        print(f"Attempting to parse '{dummy_kdebug_path}'...")
        # Note: Actual parsing methods (e.g., parser.parse_file, parser.parse_traces)
        # would be used here. This example focuses on instantiation and file handling.
        # If the dummy file is too simple, parse_events might return nothing or error.
        # We'll just print a success message for file opening.
        print(f"Successfully opened '{dummy_kdebug_path}'. Further parsing requires valid kdebug data.")
        # Example of attempting to parse (may not yield meaningful results with dummy data)
        # events = parser.parse_file(f)
        # for event in events:
        #     print(event)
except FileNotFoundError:
    print(f"Error: The file '{dummy_kdebug_path}' was not found. Please ensure it exists or create a real kdebug dump using `sudo ktrace dump` on macOS.")
except Exception as e:
    print(f"An error occurred during parsing: {e}")
finally:
    # Clean up dummy file
    if os.path.exists(dummy_kdebug_path) and dummy_kdebug_path == 'kdebug.bin' and b'\x00\x00\x00\x00\x00\x00\x00\x00' * 10 in open(dummy_kdebug_path, 'rb').read():
        os.remove(dummy_kdebug_path)
        print(f"Cleaned up dummy '{dummy_kdebug_path}'.")

view raw JSON →