Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/osandov/drgn

Programmable debugger
https://github.com/osandov/drgn

Last synced: 15 days ago
JSON representation

Programmable debugger

Host: GitHub
URL: https://github.com/osandov/drgn
Owner: osandov
License: other
Created: 2018-08-17T08:34:50.000Z (about 6 years ago)
Default Branch: main
Last Pushed: 2024-05-29T05:49:10.000Z (6 months ago)
Last Synced: 2024-05-29T10:22:53.532Z (6 months ago)
Language: Python
Homepage:
Size: 14.2 MB
Stars: 1,669
Watchers: 35
Forks: 157
Open Issues: 90
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.rst
- License: COPYING
- Support: docs/support_matrix.rst

Awesome Lists containing this project

README

drgn
====

.. |pypi badge| image:: https://img.shields.io/pypi/v/drgn
:target: https://pypi.org/project/drgn/
:alt: PyPI

.. |ci badge| image:: https://github.com/osandov/drgn/workflows/CI/badge.svg
:target: https://github.com/osandov/drgn/actions
:alt: CI Status

.. |docs badge| image:: https://readthedocs.org/projects/drgn/badge/?version=latest
:target: https://drgn.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black

.. start-introduction

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:

.. code-block:: pycon

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

.. end-introduction

Documentation can be found at `drgn.readthedocs.io
`_.

.. start-installation

Installation
------------

Package Manager
^^^^^^^^^^^^^^^

drgn can be installed using the package manager on some Linux distributions.

.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg
:target: https://repology.org/project/drgn/versions
:alt: Packaging Status

* Fedora >= 32

.. code-block:: console

$ sudo dnf install drgn

* RHEL/CentOS >= 8

`Enable EPEL `_. Then:

.. code-block:: console

$ sudo dnf install drgn

* Oracle Linux >= 8

Enable the ``ol8_addons`` or ``ol9_addons`` repository and install drgn:

.. code-block:: console

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

See the documentation for drgn in `Oracle Linux 9
`_
and `Oracle Linux 8
`_
for more information.

* Arch Linux

.. code-block:: console

$ sudo pacman -S drgn

* Debian >= 12 (Bookworm)

.. code-block:: console

$ sudo apt install python3-drgn

* Gentoo

.. code-block:: console

$ sudo emerge dev-debug/drgn

* openSUSE

.. code-block:: console

$ sudo zypper install python3-drgn

* Ubuntu

Enable the `michel-slm/kernel-utils PPA `_.
Then:

.. code-block:: console

$ sudo apt 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:

.. code-block:: console

$ 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
<#from-source>`_ 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

.. code-block:: console

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

* RHEL/CentOS/Oracle Linux

.. code-block:: console

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

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

.. code-block:: console

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

Optionally, install libkdumpfile from source if you want support for the
makedumpfile format.

* Arch Linux

.. code-block:: console

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

* Gentoo

.. code-block:: console

$ 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

* openSUSE

.. code-block:: console

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

Then, run:

.. code-block:: console

$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py install

.. end-installation

See the `installation documentation
`_ for more options.

Quick Start
-----------

.. start-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 ``.``:

.. code-block:: pycon

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

You can use various predefined helpers:

.. code-block:: pycon

>>> 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']``:

.. code-block:: pycon

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

.. end-quick-start

See the `user guide `_
for more details and features.

.. start-for-index

Getting Help
------------

* The `GitHub issue tracker `_ is the
preferred method to report issues.
* There is also a `Linux Kernel Debuggers Matrix room
`_.

License
-------

drgn is licensed under the `LGPLv2.1
`_ or later.

.. end-for-index