Scriptable debugger library
Project description
drgn (pronounced “dragon”) is a debugger with an emphasis on programmability. drgn exposes the types and variables in a program for easy, expressive scripting in Python. For example, you can debug the Linux kernel:
>>> from drgn.helpers.linux import list_for_each_entry
>>> for mod in list_for_each_entry('struct module',
... prog['modules'].address_of_(),
... 'list'):
... if mod.refcnt.counter > 10:
... print(mod.name)
...
(char [56])"snd"
(char [56])"evdev"
(char [56])"i915"
Although other debuggers like GDB have scripting support, drgn aims to make scripting as natural as possible so that debugging feels like coding. This makes it well-suited for introspecting the complex, inter-connected state in large programs. It is also designed as a library that can be used to build debugging and introspection tools; see the official tools.
drgn was developed for debugging the Linux kernel (as an alternative to the crash utility), but it can also debug userspace programs written in C. C++ support is in progress.
Documentation can be found at drgn.readthedocs.io.
Installation
Install dependencies:
Arch Linux:
$ sudo pacman -S --needed gcc libelf make pkgconf python python-pip python-setuptools
Debian/Ubuntu:
$ sudo apt-get install gcc liblzma-dev libelf-dev libdw-dev make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
Note that Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship Python versions which are too old. Python 3.6 or newer must be installed manually.
Fedora:
$ sudo dnf install elfutils-devel gcc make pkgconf python3 python3-devel python3-pip python3-setuptools
Optionally, install:
libkdumpfile if you want support for kdump-compressed kernel core dumps
Then, run:
$ sudo pip3 install drgn
See the installation documentation for more options.
Quick Start
drgn debugs the running kernel by default; run sudo drgn. To debug a running program, run sudo drgn -p $PID. To debug a core dump (either a kernel vmcore or a userspace core dump), run drgn -c $PATH. The program must have debugging symbols available.
Then, you can access variables in the program with prog['name'] and access structure members with .:
$ sudo drgn
>>> prog['init_task'].comm
(char [16])"swapper/0"
You can use various predefined helpers:
>>> len(list(bpf_prog_for_each(prog)))
11
>>> task = find_task(prog, 115)
>>> cmdline(task)
[b'findmnt', b'-p']
You can get stack traces with prog.stack_trace() and access parameters or local variables with stack_trace['name']:
>>> trace = prog.stack_trace(task)
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> poll_list = trace[5]['list']
>>> file = fget(task, poll_list.entries[0].fd)
>>> d_path(file.f_path.address_of_())
b'/proc/115/mountinfo'
See the user guide for more details and features.
License
Copyright (c) Facebook, Inc. and its affiliates.
drgn is licensed under the GPLv3 or later.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for drgn-0.0.14-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 98a5f15893bd15b7f1a525172f67e9c8ee16f635aa1824203ef5670c2931215e |
|
MD5 | 2dfc87f17db326f2cf837e3a456827e6 |
|
BLAKE2b-256 | b140231b9012238c444b5d7ba1fb07031d9a5247ee8cd06882d4607c956d9452 |
Hashes for drgn-0.0.14-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 52f0c82a597ec5cf82fdd43eb28ba0561f7ccae757f6ab557582c7f59a4f4c6e |
|
MD5 | d58dd3784da19ec25759cc079627c777 |
|
BLAKE2b-256 | 39c4bfe7a9d83b3987b59c1d8ac1b7360c5ffe809998598e4be92bb2861f9938 |
Hashes for drgn-0.0.14-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9571cbe087ce72e3df8ef8de5f93eee4bbb67e137212841e5f4d6f8f8c219ee0 |
|
MD5 | 9810e5e2799ed07322aebc54da53712b |
|
BLAKE2b-256 | 894bb3d5d463e2892f8fa0a543db61481fa59736116bda903145986c8757a829 |
Hashes for drgn-0.0.14-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9c3654fcd65a380893933b6271fbada5872dedf78fcbeb07ab42af2d6c5895f8 |
|
MD5 | cb7cc340410a3fd8c24cbb02b6170739 |
|
BLAKE2b-256 | 859ae6111679e3bfe3e2ef651e5019dc25018c33bf22ecf0efd7cf1676b88539 |
Hashes for drgn-0.0.14-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 78923998a5650547b1d70c9ebbc151ef487d144492d7874f2dd8faea7054abd2 |
|
MD5 | 8c8e3acb714d91822802d82d1309bc50 |
|
BLAKE2b-256 | d9b288debb67237310898635904cc678a55dea15e16c4b87186116414e81a58a |