{"id":13694116,"url":"https://github.com/didi/rdebug","last_synced_at":"2025-05-16T03:02:09.971Z","repository":{"id":57503190,"uuid":"170628970","full_name":"didi/rdebug","owner":"didi","description":"Rdebug — Real Debugger","archived":false,"fork":false,"pushed_at":"2019-12-24T02:52:05.000Z","size":20131,"stargazers_count":1160,"open_issues_count":11,"forks_count":171,"subscribers_count":63,"default_branch":"master","last_synced_at":"2025-05-05T11:37:29.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/didi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-14T04:49:54.000Z","updated_at":"2025-04-14T08:32:18.000Z","dependencies_parsed_at":"2022-09-13T08:21:43.316Z","dependency_job_id":null,"html_url":"https://github.com/didi/rdebug","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Frdebug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Frdebug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Frdebug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Frdebug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/didi","download_url":"https://codeload.github.com/didi/rdebug/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252788517,"owners_count":21804284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T17:01:24.774Z","updated_at":"2025-05-16T03:02:04.937Z","avatar_url":"https://github.com/didi.png","language":"PHP","funding_links":[],"categories":["开源类库","Open source library","PHP"],"sub_categories":["调试","Debugging"],"readme":"\u003ch1 align=\"center\"\u003eRDebug - Real Debugger\u003c/h1\u003e\n\n[![Gitter](https://badges.gitter.im/didi/rdebug.svg)](https://gitter.im/didi/rdebug?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/didi/rdebug/blob/master/LICENSE)\n\n## Translation\n\n- [中文](./README_zh_CN.md)\n\n## 1. Introduction\n\nRdebug is an open source *tool chain* that focusing on efficiency of daily developing, testing and debugging for developers. The code will be robust.\n\n### 1.1 Background\n\nAs micro-service architecture makes services *isomerous*, *easy-to-deploy* and *superbly extensible*, large systems are divided into several micro services.\n\nBut, micro-service architecture is not a silver bullet. It has several drawbacks. One service is divided into several small services, test environment becomes hard to maintain. Unit test needs to mock downstream services. This will downgrade the efficiency of developing, and increase production bugs.\n\nWe do believe this industry needs an evolution.\n\n### 1.2 Principle\n\nEfficiency improvement, release cycle reduction, code quality improvement, production bug reduction\n\n### 1.3 When to use\n\nSuitable for old api refactoring that traffic have already been recorded.\n\nNot suitable for new api or api that has no traffic recorded.\n\nSupport for new api is under investigation.\n\n## 2. Quick Started\n\n### Traffic Recording\n\n```shell\n# Modify php-fpm config, set `clear_env = no`\n\n# Compile koala-libc.so \u0026 koala-recorder.so\n\n# Start php-fpm with koala-libc.so \u0026 koala-recorder.so\n# Set environment first\n$ export KOALA_SO=/path/to/koala-recorder.so \n$ export KOALA_RECORD_TO_DIR=/path/to/your-save-recorded-session-dir\n$ export LC_CTYPE=\"C\"\n\n# Recording\n# macOS\n$ DYLD_INSERT_LIBRARIES=\"/path/to/koala-libc.so\" DYLD_FORCE_FLAT_NAMESPACE=\"y\" /path/to/sbin/php-fpm\n\n# or, Linux\n$ LD_PRELOAD=\"/path/to/koala-libc.so\" /path/to/sbin/php-fpm\n```\n\n### Traffic Replaying\n\nThree ways to replay: replay from source, replay by midi.phar, replay by composer vendor/bin.\n\n```shell\n# Source\n$ git clone https://github.com/didi/rdebug.git\n$ cd rdebug/php/midi\n$ sh install.sh\n$ cd /path/to/your/project\n$ /path/to/rdebug/php/midi/bin/midi run -f RECORD-SESSION-FILE\n\n# Or, Phar\n$ wget -O midi.phar -q https://github.com/didi/rdebug/raw/master/output/bin/midi.phar\n$ midi.phar run -f RECORD-SESSION-FILE\n\n# Or, Composer global\n$ composer global require rdebug/midi\n$ cd /path/to/your/project\n$ ~/.composer/vendor/bin/midi run -f RECORD-SESSION-FILE\n\n# Or, Composer\n$ cd /path/to/your/project\n$ composer require rdebug/midi --dev\n$ ./vendor/bin/midi run -f RECORD-SESSION-FILE\n```\n\n### PHP Example\n\n- [Try Record \u0026 Replay With Docker](./doc/Docker.md)\n- [PHP Record \u0026 Replay Example](./example/php/README.md)\n- [Replay Local File](./doc/midi/Replay-file.md)\n\n## 3. Technical Details\n\nWe are using real production traffic to test on non-production environment. So, the core features of `Rdebug` are traffic recording and traffic replaying.\n\n* **Traffic Recording**\n\n  Recording production traffic, including RPC between micro-services. The most difficult part is to trace requests that will span multiple services.\n\n* **Traffic Replaying**\n\n  Replaying recorded production traffic against non-production environment, mock downstream traffic based on traffic matching. The most difficult part is interception and traffic matching.\n\n![koala-midi](./doc/images/koala-midi_en-US.png)\n\n### 3.1 Koala \u0026 Koala-libc\n\nKoala and Koala-libc is the engine of Rdebug.\n\nBecause the problems such as *RPC tracing*, *libc interception* that a traffic replaying system may concern is what a traffic recording system concerns. The traffic recording and replaying system shares the same engine.\n\n#### Koala\n\nKoala is written in Go, libc contains some c++ code for interception part which will complied to *koala-recorder.so* and *koala-replayer.so*\n\nKoala support replaying and recording separately as well as simultaneously.\n\nFor more details: [koala](./koala/README.md) 。\n\n#### Koala-libc\n\nkoala-libc is written in C, and compiled to *koala-libc.so*\n\nGo does not support `fork`. To avoid problems bring by PHP-FPM fork worker, you need to inject *koala-libc.so* into parent process of PHP. So that *koala-libc.so* will forward requests libc intercepted to *koala-recorder.so when `accept` in child process\n\nFor more details: [koala-libc](./koala-libc/README.md) 。\n\n### 3.2 Midi\n\nMidi is a traffic replay client for PHP using command line written in PHP.\n\n*koala-replayer.so* is embedded in Midi, and it can replay production traffic against new code, analyze test result, generate diff report, trace report, coverage report.\n\nMidi support Xdebug.\n\nFor more details: [midi](./php/midi/README.md) 。\n\n## 4. Compile\n\n### 4.1 Requirement\n\n#### Koala \u0026 Koala-libc\n\n- GCC \u003e= 4.8\n- Go \u003e= 1.8\n- Glide\n\n#### Midi\n\n- macOS/Linux\n- PHP \u003e= 7.0\n- Xdebug (Optional)\n- Composer (Optional)\n\n### 4.2 Compile Koala-libc\n\n```shell\n$ cd koala-libc\n$ sh build.sh\n```\n\nwill generate `../output/libs/koala-libc.so`。\n\n### 4.3 Compile Koala\n\n```shell\n$ cd koala\n\n# install depends\n$ sh build.sh vendor\n\n# koala-recorder.so\n$ sh build.sh recorder\n\n# koala-replayer.so\n$ sh build.sh\n```\n\nwill generate `../output/libs/koala-recorder.so` and `../output/libs/koala-replayer.so`。\n\n### 4.4 Compile midi.phar\n\nBefore compile midi.pahr, recommend compile `koala-replayer.so` at your system and store in `php/midi/res/replayer` directory.\n\n`php/midi/res/replayer/koala-replayer.so` in repository is for macOS.\n\n```shell\n$ cd php/midi\n$ sh build.sh\n```\n\nwill generate `../output/bin/midi.phar`\n\nDefault phar will not include `DiPlugin` plugin, which is an internal plugin of didi.\n\nIf your want to compile with `DiPlugin` plugin:\n\n```\n$ cd php/midi\n$ sh build.sh midi-diplugin\n```\n\n## 5. Usage\n\n### 5.1 Traffic Recording\n\nRecord traffic in file or Elastic.\n\nSet environment variable `KOALA_RECORD_TO_DIR` to save record to specified dir\n\nInject so. Use `DYLD_INSERT_LIBRARIES` in macOs or `LD_PRELOAD` in Linux\n\nFor more details: [Recorder](./doc/recorder/recorder.md)。\n\n#### 5.1.1 macOS Recording\n\n```shell\n$ DYLD_INSERT_LIBRARIES=\"/path/to/koala-libc.so:/usr/lib/libcurl.dylib\" DYLD_FORCE_FLAT_NAMESPACE=\"y\" LC_CTYPE=\"C\" KOALA_SO=/path/to/koala-recorder.so KOALA_RECORD_TO_DIR=/tmp /usr/local/sbin/php-fpm\n```\n\n#### 5.1.2 Linux Recording\n\n```shell\nLD_PRELOAD=\"/path/to/koala-libc.so /usr/lib64/libcurl.so.4\" LC_CTYPE=\"C\" KOALA_SO=\"/path/to/koala-recorder.so\" KOALA_RECORD_TO_DIR=/tmp /usr/local/sbin/php-fpm\n```\n\nKoala support writing to Elastic by replacing `KOALA_RECORD_TO_DIR` with `KOALA_RECORD_TO_ES` which value is elastic write url\n\n### 5.2 Traffic Replay\n\nTraffic replaying is to replay recorded traffic in production against non-production environment. You need only to deploy your code w/o deploying downstream services.\n\nBelow is a simple example of replaying with '-f', which specified the file to replay.\n\n#### 5.2.1 Replay\n\n```Shell\n# Source\n$ /path/to/rdebug/php/midi/bin/midi run -f RECORD-SESSION-FILE\n\n# Or, phar\n$ midi.phar run -f RECORD-SESSION-FILE\n\n# Or, composer vendor bin\n$ ./vendor/bin/midi -f RECORD-SESSION-FILE\n```\n\nFor more details: [Replay](#traffic-replaying)\n\nUse -v, -vv or -vvv for more verbose log.\n\n#### 5.2.2 Report\n\nUse `-R`，`-T`，`-C` to generate：Replay report, Trace report, Coverage report\n\n![report](./example/php/report.png)\n\n![report-upstream](./example/php/report-upstream.png)\n\n![report-coverage](./example/php/report-coverage.png)\n\nFor more details: [Midi](./php/midi/README.md)。\n\n## 6. More\n\n### 6.1 Translation\n\n* [中文](./README_zh_CN.md)\n\n### 6.2 Documentation\n\n* [Documentation](./doc/DocList.md)\n* [Wiki](https://github.com/didi/rdebug/wiki)\n\n### 6.3 Contribute\n\nAny contributions are welcome. [More Details](./CONTRIBUTING.md)\n\n### 6.4 Contract\n\n- Add Weixin\n\n\u003cimg src=\"https://raw.githubusercontent.com/didi/rdebug/master/doc/images/weixin_add_friend.jpg\" width=\"180\" height = \"180\"\u003e\n\n- QQ Group\n    \n![QQ](doc/images/QQChat.png)\n\n### 6.5 License\n\nRdebug is licensed under the Apache 2.0 License. [LICENSE](./LICENSE)\n\n### 6.6 Contributors\n\nSpecial thanks to [TaoWen](https://github.com/taowen) Developer of Koala \u0026 Koala-libc.\n\nThanks to all the people who [contribute](https://github.com/didi/rdebug/graphs/contributors).\n\u003ca href=\"https://github.com/didi/rdebug/graphs/contributors\"\u003e\u003cimg src=\"https://opencollective.com/rdebug/contributors.svg?width=890\u0026button=true\" /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidi%2Frdebug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdidi%2Frdebug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidi%2Frdebug/lists"}