Skip to main content

Programmable debugger

Project description

PyPI CI Status Documentation Status black badge

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.

Additionally, drgn is 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.

Packaging Status
  • Fedora, RHEL/CentOS Stream >= 9

    $ sudo dnf install drgn
  • RHEL/CentOS < 9

    Enable EPEL. Then:

    $ sudo dnf install drgn
  • Oracle Linux >= 8

    Enable the ol8_addons or ol9_addons repository. Then:

    $ sudo dnf config-manager --enable ol8_addons  # OR: ol9_addons
    $ sudo dnf install drgn

    drgn is also available for Python versions in application streams. For example, use dnf install python3.12-drgn to install drgn for Python 3.12. See the documentation for drgn in Oracle Linux 9 and Oracle Linux 8 for more information.

  • Debian >= 12 (Bookworm)/Ubuntu >= 24.04 (Noble Numbat)

    $ sudo apt install python3-drgn

    To get the latest version on Ubuntu, enable the michel-slm/kernel-utils PPA first.

  • Arch Linux

    $ sudo pacman -S drgn
  • Gentoo

    $ sudo emerge dev-debug/drgn
  • openSUSE

    $ sudo zypper install python3-drgn

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 Stream >= 9

    $ sudo dnf install autoconf automake check-devel elfutils-debuginfod-client-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel
  • RHEL/CentOS < 9, Oracle Linux

    $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

    Optionally, install libkdumpfile-devel from EPEL on RHEL/CentOS >= 8 or install libkdumpfile from source if you want support for the makedumpfile format. For Oracle Linux >= 7, libkdumpfile-devel can be installed directly from the corresponding addons repository (e.g. ol9_addons).

    Replace dnf with yum for RHEL/CentOS/Oracle Linux < 8.

    When building on RHEL/CentOS/Oracle Linux < 8, you may need to use a newer version of GCC, for example, using the devtoolset-12 developer toolset. Check your distribution’s documentation for information on installing and using these newer toolchains.

  • Debian/Ubuntu

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

    On Debian <= 11 (Bullseye) and Ubuntu <= 22.04 (Jammy Jellyfish), libkdumpfile-dev is not available, so you must install libkdumpfile from source if you want support for the makedumpfile format.

  • Arch Linux

    $ sudo pacman -S --needed autoconf automake check gcc git libelf libkdumpfile libtool make pkgconf python python-pip python-setuptools xz
  • Gentoo

    $ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils sys-devel/gcc dev-vcs/git dev-libs/libkdumpfile dev-build/libtool dev-build/make dev-python/pip virtual/pkgconfig dev-lang/python dev-python/setuptools app-arch/xz-utils
  • openSUSE

    $ sudo zypper install autoconf automake check-devel gcc git libdebuginfod-devel libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

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; simply run drgn. To debug a running program, run 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 .:

$ drgn
>>> prog["init_task"].comm
(char [16])"swapper/0"

You can use various predefined helpers:

>>> len(list(bpf_prog_for_each()))
11
>>> task = find_task(115)
>>> cmdline(task)
[b'findmnt', b'-p']

You can get stack traces with stack_trace() and access parameters or local variables with trace["name"]:

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

Getting Help

License

Copyright (c) Meta Platforms, Inc. and affiliates.

drgn is licensed under the LGPLv2.1 or later.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

drgn-0.0.32.tar.gz (1.5 MB view details)

Uploaded Source

Built Distributions

drgn-0.0.32-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.4 MB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.3 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.4 MB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.3 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.3 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.3 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.3 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.3 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.17+ x86-64

drgn-0.0.32-cp38-cp38-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (9.3 MB view details)

Uploaded CPython 3.8manylinux: glibc 2.17+ x86-64

File details

Details for the file drgn-0.0.32.tar.gz.

File metadata

  • Download URL: drgn-0.0.32.tar.gz
  • Upload date:
  • Size: 1.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for drgn-0.0.32.tar.gz
Algorithm Hash digest
SHA256 537b0300ccd11a181baf953e7bf1903bd49316b7a278c9af878e8ab25764932a
MD5 e8ed716ed4f83e233cf58ad36af2c105
BLAKE2b-256 986728f61a9dec0c6a343a62b2c0f07efe97827960832b13dc2dabdddd285547

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 621289fb12f55a56a441f5d09cae930b6dbd998791ba37ec64bf2863037402b5
MD5 ddd2ed826c764b9a1c3f7ee45bbb35be
BLAKE2b-256 06e963ac3f86ffa23bad274e8eb93e6494046a8058fb991bacd2027cf232feeb

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 52a3cf85e4ceb2eb02400fa3dfd459fb637828f61b13494083132eba52b57196
MD5 98dc266115293b989b9a73ab1c9197c0
BLAKE2b-256 1e43c4ea2384ec9db5fa147f5463b6341c94cf2635ee4e13fcc7fb3df0f01793

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 960f40d894e9371afa880311d38f219fe5df7859b039e265ae1b31351be0d59a
MD5 666c27e4b7ad1425b1a761a5806e0fa5
BLAKE2b-256 6700b72b784d49da39e92d5ba0d514bfa331920fc6e492fe6c9462e45cec2211

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 2d54ce3944bcca535c58c498183c2ee389e3d8bec3b565703d3d3db8f783cad5
MD5 f7d824d14d92ceeb49510f8495ba1ffa
BLAKE2b-256 9a03a4c7f1c2b0adf669e7ff8be797c67eb4fe68768e61f58cd728c4cda41904

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 528d431a920977db8d125024c889c929960c096fd7ca4f1676ad825b9536f955
MD5 99fe59f0d2831ffdd53ee40b15cd5566
BLAKE2b-256 1751ffca40ab65c448d9afc34c95f8f7d99ea64e025e65045a932d9a4e8ac7bc

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 a659901f6e5ecbb92619e63725fa9d395dd2708bf1c4a10c466fb3834a4f4a0f
MD5 72dd46e05e81246a1eddf0f8a401510e
BLAKE2b-256 9b273d66af0d16af796eb5eba6bf1608e356e4fb051cb150a7a8e75bbcf1cc1e

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 94b5de6622f1c050471a2f037621c687cacb10921e7979caa5842030a331f528
MD5 ae4eec843d41fa98093ac7291319e33c
BLAKE2b-256 3ee972d1a8585278c55348acb1cd4607952fb37f4be7f54d42f7bf9ee71899be

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 a7232cdf86d55da1f6768e487e156b25aaf533859b189ab6c75c609ff44ac00c
MD5 95e823282b437835ee3d33085e2b5c55
BLAKE2b-256 ad98f2e94a14c23da0249afd7eaab98b3d23d08787cc0e1bededabdc390e32d8

See more details on using hashes here.

File details

Details for the file drgn-0.0.32-cp38-cp38-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for drgn-0.0.32-cp38-cp38-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 4c6948ee32ce4aa6c020e5640864446da57beeb5dfda0dca70be4ad0b68b8fba
MD5 c3c74a89b8a4b5d540ff41c462c13324
BLAKE2b-256 062e12d5653b6df98271e29643ee8e42f5d064f65a8f8fd48a4f04ecc68344f9

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page