phbpf/README.md

eBPF Observability for PHP

phbpf is specifically designed for PHP, enabling the efficient creation of kernel-level tracing and manipulation programs in Linux systems. Centered around eBPF technology, it offers a rich set of tools and examples to empower PHP developers with robust kernel observability and dynamic instrumentation capabilities within their familiar ecosystem.

✨ Features

• Natively operate BPF programs with PHP scripts, ideal for rapid development and debugging of eBPF functionalities.
• Adheres to bcc frontend usage patterns, allowing bcc tool projects to be implemented in PHP with minimal effort, including built-in examples.
• Core logic written in C/C++, invoking libbpf and LLVM interfaces.
• Supports common BPF hooks: kprobe/uprobe, tracepoint, etc.
• Operates as an external, independent process for transparent monitoring of running systems and target processes.

🛠 Architecture Overview

+-------------+        +---------------------------+
|  PHP Script  | <----> | PHP Extension Module (C) |
+-------------+        +---------------------------+
                                   |
                                   v
                          +------------------+
                          |   libbpf / BCC   |
                          +------------------+
                                   |
                                   v
                          +------------------+
                          |  eBPF Subsystem  |
                          +------------------+

Screenshot

This example traces a disk I/O kernel function, and populates an in-kernel power-of-2 histogram of the I/O size. For efficiency, only the histogram summary is returned to user-level.

# php ./examples/tracing/bitehist.php
Tracing... Hit Ctrl-C to end.
^C
     kbytes          : count     distribution
       0 -> 1        : 3        |                                      |
       2 -> 3        : 0        |                                      |
       4 -> 7        : 211      |**********                            |
       8 -> 15       : 0        |                                      |
      16 -> 31       : 0        |                                      |
      32 -> 63       : 0        |                                      |
      64 -> 127      : 1        |                                      |
     128 -> 255      : 800      |**************************************|

🔗 Dependencies

• PHP 7 / 8
• Kernel with BPF support enabled
• libbpf
• libbcc >= v0.29.0
• Clang / LLVM

🚀 Quick Start

Dependency Installation

# Install llvm / bcc / clang, etc.
For example, on Ubuntu:
sudo apt install bpfcc-tools linux-headers-$(uname -r)

For more information on system or dependency installation issues, refer to: https://github.com/iovisor/bcc/blob/master/INSTALL.md

Extension Installation

git clone --recursive https://git.yunzhihui.ltd/root/phbpf.git
cd phbpf
phpize
./configure
make && sudo make install
# Configure php.ini
echo "extension=ebpf.so" >> php.ini
# Run example
php examples/hello_world.php

Contents

Tracing

Examples

• examples/tracing/bitehist.php: Block I/O size histogram.
• examples/tracing/disksnoop.php: Trace block device I/O latency.
• examples/hello_world.php: Prints "Hello, World!" for new processes.
• examples/tracing/stacksnoop: Trace a kernel function and print all kernel stack traces.
• tools/statsnoop: Trace stat() syscalls.
• examples/tracing/tcpv4connect.php: Trace TCP IPv4 active connections.
• examples/tracing/trace_fields.php: Simple example of printing fields from traced events.
• examples/tracing/undump.php: Dump UNIX socket packets
• examples/tracing/urandomread.php: A kernel tracepoint example, which traces random:urandom_read.
• examples/tracing/kvm_hypercall.php: Conditional static kernel tracepoints for KVM entry, exit and hypercal.

Tools

This section is under construction. Please check back later.

Networking

Examples:

• examples/networking/net_monitor.php: Used to monitor network packets on a specified network interface.

Contributing

We welcome contributions to this project! Please feel free to submit a pull request.