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 at Meta 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
Package Manager
drgn can be installed using the package manager on some Linux distributions.
Fedora >= 32
$ sudo dnf install drgnRHEL/CentOS >= 8
Enable EPEL. Then:
$ sudo dnf install drgnArch Linux
pip
If your Linux distribution doesn’t package the latest release of drgn, you can install it with pip.
First, install pip. Then, run:
$ sudo pip3 install drgnThis will install a binary wheel by default. If you get a build error, then pip wasn’t able to use the binary wheel. Install the dependencies listed below and try again.
Note that RHEL/CentOS 6, Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship Python versions which are too old. Python 3.6 or newer must be installed.
From Source
To get the development version of drgn, you will need to build it from source. First, install dependencies:
Fedora/RHEL/CentOS
$ sudo dnf install autoconf automake elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptoolsReplace dnf with yum for RHEL/CentOS < 8.
Debian/Ubuntu
$ sudo apt-get install autoconf automake gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-devArch Linux
$ sudo pacman -S --needed autoconf automake gcc git libelf libtool make pkgconf python python-pip python-setuptools
Optionally, install libkdumpfile if you want support for the makedumpfile compressed kernel core dump format. libkdumpfile is currently only packaged on Fedora and EPEL. For other distributions, you must install it manually.
Then, run:
$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py installSee 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. Make sure to install debugging symbols for whatever you are debugging.
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) Meta Platforms, Inc. and affiliates.
drgn is licensed under the GPLv3 or later.
1 maintainer
Metadata
1 maintainer
Release files for drgn 0.0.18
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| drgn-0.0.18.tar.gz | 972.2 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| drgn-0.0.18-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.12+ x86-64 | Details |
| drgn-0.0.18-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl | CPython 3.9 | CPython 3.9 | Linux glibc 2.12+ x86-64 | Details |
| drgn-0.0.18-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl | CPython 3.8 | CPython 3.8 | Linux glibc 2.12+ x86-64 | Details |
| drgn-0.0.18-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl | CPython 3.7 | CPython 3.7 pymalloc | Linux glibc 2.12+ x86-64 | Details |
| drgn-0.0.18-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl | CPython 3.6 | CPython 3.6 pymalloc | Linux glibc 2.12+ x86-64 | Details |
Total release size: 21.5 MB
Release files / drgn-0.0.18.tar.gz
| Download URL | drgn-0.0.18.tar.gz |
|---|---|
| Size | 972.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2e2fec7ffa706bc6febf64dea8f5a9600d1e0f784b6e2f00f08e57cf38a4f36c
|
|
BLAKE2b-256 checksum How to use checksums |
d43ce702313ae956c95bdd2e28b9e5175f191fda4e1989e9f3ce19f0d1208579
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.6.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.2
|
Release files / drgn-0.0.18-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
| Download URL | drgn-0.0.18-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl |
|---|---|
| Size | 4.1 MB |
| Tags | CPython 3.10 Linux glibc 2.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
f80e28a03f8428dac86f9c057ae0fdf3e104d4570d5396148e9de06f8e617a00
|
|
BLAKE2b-256 checksum How to use checksums |
2f57306147e346526bf5d64d372a01b670425a0b72adff205c1f81abc2580fae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.6.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.2
|
Release files / drgn-0.0.18-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
| Download URL | drgn-0.0.18-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl |
|---|---|
| Size | 4.1 MB |
| Tags | CPython 3.9 Linux glibc 2.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
851ae5d36445e3bf9bc69b7242d8c6669fa64d38c20a053020f371ee00ae3d08
|
|
BLAKE2b-256 checksum How to use checksums |
c8f207cb9a139074c64630d2e151f165c2e182fe872975ced212b1b8debdb438
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.6.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.2
|
Release files / drgn-0.0.18-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
| Download URL | drgn-0.0.18-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl |
|---|---|
| Size | 4.1 MB |
| Tags | CPython 3.8 Linux glibc 2.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
621cf4f4bd14596a5420ba7a3966b7479376d9ad1701f4bea0eaf639af558e72
|
|
BLAKE2b-256 checksum How to use checksums |
1e61001e06fc351f80897f4fa6576f8008fae49ceb0394559c8e59c984b34888
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.6.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.2
|
Release files / drgn-0.0.18-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
| Download URL | drgn-0.0.18-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl |
|---|---|
| Size | 4.1 MB |
| Tags | CPython 3.7 CPython 3.7 pymalloc Linux glibc 2.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
db47e3224cc3f9b297025e244a80bf666d10420e36079701a349fe29a27b87de
|
|
BLAKE2b-256 checksum How to use checksums |
e1cd82ffa783ba01dc3f1372484f712173d530c262ece38298e98821b38cd523
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.6.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.2
|
Release files / drgn-0.0.18-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
| Download URL | drgn-0.0.18-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl |
|---|---|
| Size | 4.1 MB |
| Tags | CPython 3.6 CPython 3.6 pymalloc Linux glibc 2.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
d01799a50ea613f62c8af4805ba3b5096fedfb9a549225ffe1823e631effb899
|
|
BLAKE2b-256 checksum How to use checksums |
d3098fb2d10038fb367bca8a8fc06cf6e7d67a0e13beb0a6ba4e10e10dd68ab3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.6.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.2
|
