PHPScope

PHPScope is a PHP profiling tool based on phpspy that integrates with Pyroscope to provide continuous profiling for PHP applications. It captures trought phpspy PHP-FPM and PHP CLI processes performance data and sends it to a Pyroscope server for visualization and analysis.

Features

• Real-time PHP process profiling
• Integration with Pyroscope
• Configurable sampling rate and batch processing
• Support for PHP-FPM and PHP CLI processes
• Customizable tags for better data organization
• Function exclusion patterns
• Concurrent processing support ( WIP )

Architecture

The diagram above shows the main components of PHPScope:

1. Collector (phpspy): Captures stack traces from PHP processes
2. Processor: Processes and filters the raw stack traces
3. Converter: Converts traces to Pyroscope-compatible format
4. Sender: Handles communication with Pyroscope server

Prerequisites

• Go 1.23.3 or higher
• PHP-FPM or PHP CLI processes running ( Tested on PHP 8.3 )
• Access to a Pyroscope server
• phpspy installed on the system ( Incuded in docker container )

Installation

You can either run PHPScope using Docker Compose or build it from source.

Using Docker Compose

curl -sSL https://raw.githubusercontent.com/everythings-gonna-be-alright/phpScope/refs/heads/main/docker-compose.yaml | docker compose -f - up -d

After installation, you can access the Pyroscope UI at:

http://127.0.0.1:4040

Building from Source

git clone https://github.com/everythings-gonna-be-alright/phpscope
cd phpscope
go build

Usage

Basic usage example:

./phpscope --pyroscopeUrl="http://pyroscope:4040" --appName="your-app-name"

Command Line Options

| Option | Default | Description | |--------|---------|-------------| | --pyroscopeUrl | required | URL of the Pyroscope server | | --auth | "" | Pyroscope authentication token | | --appName | required | Application name for profiling | | --rateHz | 400 | Sample rate in Hz | | --interval | 0.1 | Maximum time between requests to Pyroscope server | | --batch | 50000 | Maximum number of traces in request | | --concurrent | 1 | Concurrent request limit | | --exclude | "" | Regex pattern to exclude functions | | --tags | [] | Tags in format key=value | | --phpspyBufferSize | 131072 | phpspy buffer size | | --phpspyMaxDepth | 50000 | phpspy max stack depth | | --phpspyThreads | 64 | phpspy threads count | | --debug | false | Enable debug logging |

Example

Profile a PHP application with custom tags and exclusion pattern:

./phpscope \
  --pyroscopeUrl="http://pyroscope:4040" \
  --appName="my-php-app" \
  --tags="environment=production" \
  --tags="version=1.0" \
  --exclude="vendor/*" \
  --rateHz=100

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.