PyPI CI Status Documentation Status https://img.shields.io/badge/code%20style-black-000000.svg

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 drgn

  • RHEL/CentOS >= 8

    Enable EPEL. Then:

    $ sudo dnf install drgn

  • Arch Linux

    Install the drgn package from the AUR.

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 drgn

This 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 gawk gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

    Replace dnf with yum for RHEL/CentOS < 8.

  • Debian/Ubuntu

    $ sudo apt-get install autoconf automake gawk gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev

  • Arch Linux

    $ sudo pacman -S --needed autoconf automake gawk 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 install

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. 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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for osandov from gravatar.com osandov

Credits

Author: Omar Sandoval

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.6

Classifiers

Report project as malware

Metadata

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for osandov from gravatar.com osandov

Credits

Author: Omar Sandoval

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.6

Classifiers

Report project as malware

Release files for drgn 0.0.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for drgn 0.0.15
File Size Uploaded
drgn-0.0.15.tar.gz 879.8 kB Details

Built distributions (wheels)

Table of built distributions (wheels) for drgn 0.0.15
File
drgn-0.0.15-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.1 MB CPython 3.10 CPython 3.10 Linux glibc 2.12+ x86-64 Details
drgn-0.0.15-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.1 MB CPython 3.9 CPython 3.9 Linux glibc 2.12+ x86-64 Details
drgn-0.0.15-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.1 MB CPython 3.8 CPython 3.8 Linux glibc 2.12+ x86-64 Details
drgn-0.0.15-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.1 MB CPython 3.7 CPython 3.7 pymalloc Linux glibc 2.12+ x86-64 Details
drgn-0.0.15-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.1 MB CPython 3.6 CPython 3.6 pymalloc Linux glibc 2.12+ x86-64 Details

Total release size: 21.2 MB

Release files / drgn-0.0.15.tar.gz

Download URL drgn-0.0.15.tar.gz
Size 879.8 kB
Tags Source
SHA-256 checksum
How to use checksums 		a27b5203cf014ced148fe6169e889c4228ca7d66085f949ed16d6cf2f09bd730
BLAKE2b-256 checksum
How to use checksums 		db03de22adbacb025d96acffe2615b2e64a9450a573348c7fc82cd6423edb7ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

Release files / drgn-0.0.15-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.15-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 		8f3229b4b1cab9a5f32eb1977fd9d5e65113f84d4af6b8e6262d8e8c3739bc78
BLAKE2b-256 checksum
How to use checksums 		3cdf3df9ec8339e371fec589faaec9a8c9263d12669cb928436cbe7382fb3203
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

Release files / drgn-0.0.15-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.15-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 		fec76f491e6a6ce73f5d91186ade65050d0ad4c86fdf017baa762e6c1e8e0a0e
BLAKE2b-256 checksum
How to use checksums 		1e868b4891efbb4bb471594e060cf688f99da64cb63ee08517e935db2781e536
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

Release files / drgn-0.0.15-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.15-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 		53d779d6e060a8ae79e7496f1acf8a350866c752aad59891837a35b084851b1f
BLAKE2b-256 checksum
How to use checksums 		26714d4e757a66bea1623205afc3fe25bb36fb29d38d25e20657b8e136f28611
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

Release files / drgn-0.0.15-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.15-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 		2c24afbdb6e32e8b83f2c68bf02aa0b721eb00d1f6f7b7b1ff045818a7846912
BLAKE2b-256 checksum
How to use checksums 		33ed53e86367c5c7757c3b0c26fa9b9c3784b7e92a82de30c0737633fac50f72
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

Release files / drgn-0.0.15-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.15-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 		6b409537bec02e6b3b176c31d1479e3ca29ed5f8a10b385ebbde7e56b6dd01f8
BLAKE2b-256 checksum
How to use checksums 		4039c7d3f55dd7b052046649ec8fa4a1d0545bfc847ca32a5b64cb019869fd93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page