{"id":15984864,"url":"https://github.com/gggeek/pinba_php","last_synced_at":"2025-03-17T15:32:12.760Z","repository":{"id":5914254,"uuid":"7133525","full_name":"gggeek/pinba_php","owner":"gggeek","description":"A clone of the pinba extension for php, in pure php","archived":false,"fork":false,"pushed_at":"2022-12-13T10:43:31.000Z","size":168,"stargazers_count":21,"open_issues_count":0,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-25T15:01:48.338Z","etag":null,"topics":["performance-monitoring","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gggeek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-12-12T16:31:00.000Z","updated_at":"2023-12-31T17:25:58.000Z","dependencies_parsed_at":"2023-01-13T13:44:58.230Z","dependency_job_id":null,"html_url":"https://github.com/gggeek/pinba_php","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gggeek%2Fpinba_php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gggeek%2Fpinba_php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gggeek%2Fpinba_php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gggeek%2Fpinba_php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gggeek","download_url":"https://codeload.github.com/gggeek/pinba_php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243869400,"owners_count":20361008,"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":["performance-monitoring","php"],"created_at":"2024-10-08T02:10:51.142Z","updated_at":"2025-03-17T15:32:12.385Z","avatar_url":"https://github.com/gggeek.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Polyfill-Pinba\n==============\n\nPure-php reimplementation of the \"PHP extension for Pinba\".\n\nSee http://pinba.org for the original.\n\n## Requirements\n\nPHP 5.3 or any later version.\n\nA Pinba server to send the data to. Known servers include http://pinba.org/ and https://github.com/badoo/pinba2. Both\nare available as Docker Container images for trying out.\n\n## Installation\n\n    composer require gggeek/polyfill-pinba\n\nthen set up configuration settings `pinba.enabled` and `pinba.server` in `php.ini` as described at\nhttps://github.com/tony2001/pinba_engine/wiki/PHP-extension#INI_Directives\n\nThat's all.\n\n**NB** gathering of metrics and sending them to the server is disabled by default. You _have_ to enable it via ini settings,\nunless you have added explicit calls to the pinba api in your php code.\n\n## Usage\n\nSee the API described at https://github.com/tony2001/pinba_engine/wiki/PHP-extension\n\nA trivial usage example can be found in [doc/sample.php](doc/sample.php).\n\nFor viewing the gathered metrics, check out https://github.com/intaro/pinboard, https://github.com/pinba-server/pinba-server\nor https://github.com/ClickHouse-Ninja/Proton\n\n### Extensions to the original API\n\n#### Pinba::ini_set\n\nIf the pinba php extension is not enabled in your setup (which is most likely the case, as otherwise you would not\nbe using this package), it is not possible from php code to modify the values for ini options `pinba.enabled` and\n`pinba.server`. While it is possible to set their value in `php.ini`, if you want to modify their value at runtime you\nwill have instead to use methods `\\PinbaPhp\\Polyfill\\pinba::ini_set($option, $value)`. You should also use corresponding\nmethod `\\PinbaPhp\\Polyfill\\pinba::ini_get($option)` to check it.\n\n### ini option `pinba.inhibited`\n\nIn case you want to keep your code instrumented with `pinba_timer_add`, `pinba_timer_stop` and similar calls but are\nnot collecting the pinba data anymore, and you want to reduce as much as possible the overhead imposed by this package,\nplease set in `pinba.inhibited=1` `php.ini`.\n\nUsing `pinba.enabled=0` or `pinba.auto_flush=0` is not recommended in that scenario, as, while they both disable the sending\nof data, they do not prevent timers to be actually created.\n\n## Compatibility\n\nWe strive to implement the same API as Pinba extension ver. 1.1.2.\n\nAs for the server side, the library is tested for compatibility against both a Pinba server and a Pinba2 one.\n\nFeatures not (yet) supported:\n- Timers data misses `ru_utime` and `ru_stime` members. This is true also for timers added to `PinbaClient` instances\n\nKnown issues - which cannot / won't be fixed:\n- lack in precision in time reporting: the time reported for page execution will be much shorter with any php code than\n  it can be measured with a php extension. We suggest thus not to take the time reported by this package as an absolute\n  value, but rather use it to check macro-issues, such as a page taking 10 seconds to run, or 10 times as much as another\n  page. In the demo file [doc/sample.php](doc/sample.php) we showcase how to make time measurement as precise as possible\n- impact on system performances: the cpu time and ram used by this implementation (which runs on every page of your site!)\n  are also bigger than the resources used by the php extension. It is up to you to decide if the extra load added to\n  your server by using this package is worth it or not, esp. for heavily loaded production servers\n- the warnings raised when incorrect data is passed to the pinba php functions are of severity `E_USER_WARNING` instead of\n  `E_WARNING`\n- in the data reported by `pinba_get_info` and reported to the Pinba server, `doc_size` has always a value of 0. This\n  can be worked around by using an instance of `PinbaClient` and calling `setDocumentSize` - see\n  [doc/measure_body_size.php](doc/measure_body_size.php) for an example\n- in the data reported to the Pinba server, `memory_footprint` has always a fixed value of 0 or is not reported at all.\n  Again, using a `PinbaClient` instance can fix that - but there is no php function available that I know of which can\n  report the equivalent usage of the `mallinfo` C call done by the php extension\n- ini setting `pinba.resolve_interval` is not supported and most likely never will\n- the default value reported to the Pina engine for the `schema` field is an empty string, rather than not being set at\n  all. This results in the database table storing a value of '\u003cempty\u003e' instead of NULL. At the same time, sending a\n  value of NULL makes the server-side engine re-use the last non-null value from a previous pinba packet, which seems a\n  faulty behaviour\n- the `pinba_reset` call does delete all exiting timers, unlike what the same function from the php extension does.\n  Again, the upstream behaviour does feel faulty\n\n## Performances\n\nThese results are indicative of the time and memory overhead of executing 1000 function calls in a loop, and instrumenting\neach execution with a separate timer.\n\nAs you can see, the execution delay introduced is very small, less than 1 millisecond. The memory overhead is proportional\nto the number of timers added and the tags attached to each timer.\n\n```\nNo timing:       0.00001 secs,       0 bytes used\nPinba-extension: 0.00072 secs,  280.640 bytes used\nPHP-Pinba:       0.00062 secs,  412.920 bytes used\n```\n\nNB: weirdly enough, the php extension seems to be slightly slower on average than the pure-php implementations. Having\ntaken a cursory look at the C code of the extension, I suspect this is because it executes too many `gettimeofday` calls...\n\nIn case you want to keep your code instrumented with lots of `pinba_timer_start` calls, and reduce the overhead of using\nthe extension as much as possible (while of course not measuring anything anymore), you can set `pinba.inhibited=1` in php.ini.\n\nWith that set, this is the overhead you can expect for \"timing\" 1000 executions of a function call:\n\n```\nNo timing:      0.00001 secs,       0 bytes used\nPHPPinba timed: 0.00009 secs,       0 bytes used\n```\n\n(tests executed with php 7.4 in an Ubuntu Focal container, running within an Ubuntu Jammy VM with 4 vCPU allocated)\n\n## Notes\n\nIncludes code from the Protobuf for PHP lib by Iván -DrSlump- Montes: https://github.com/drslump/Protobuf-PHP\n\nOther known packages exist implementing the same idea, such as: https://github.com/vearutop/pinba-pure-php\n\n## FAQ\n\n- **Q:** Can I run the polyfill in conjunction with the pinba php extension? **A:** yes, although I fail to see the\n  reason why you would do that. When doing so, unless taking care to selectively disable either the php extension\n  or this bundle (f.e. via calls to `Pinba::ini_set` in your code), you will get double data reported to the Pinba server\n\n## Running tests\n\nThe recommended way to run the library's test suite is via the provided Docker containers and the corresponding\nDocker Compose configuration.\nA handy shell script is available that simplifies usage of Docker and Docker Compose.\n\nThe full sequence of operations is:\n\n    ./tests/ci/vm.sh build\n    ./tests/ci/vm.sh start\n    ./tests/ci/vm.sh runtests\n    ./tests/ci/vm.sh stop\n\n    # and, once you have finished all testing related work:\n    ./tests/ci/vm.sh cleanup\n\nBy default, tests are run using php 7.4 in a Container based on Ubuntu 20 Focal. The data is sent to a container running\nthe original Pinba server - it can also be configured to be sent to a container running the Pinba2 server instead.\n\nYou can change the version of PHP and Ubuntu in use by setting the environment variables `PHP_VERSION` and `UBUNTU_VERSION`\nbefore building the containers.\n\nYou can switch the target Container used for the testsuite to the one running Pinba2 by setting the environment variables\n`PINBA_DB_SERVER=pinba2`, `PINBA_SERVER=pinba2` and `PINBA_PORT=3002` before starting the containers.\n\n### Testing tips\n\n* to debug the communication between php and the Pinba server, it is possible to use tcpdump within the `php` container:\n\n        sudo tcpdump udp -w packets.cap\n\n  once the capture file is saved, it can be analyzed by fe. opening it in Wireshark. To improve the ability of\n  Wireshark of decoding the protobuf-formatted messages, set up its configuration as described at https://wiki.wireshark.org/Protobuf.md.\n  The `.proto` file describing the messages used by Pinba can be found at https://github.com/badoo/pinba2/blob/master/proto/pinba.proto\n\n  As an alternative which does not require Wireshark, it is also possible to save to a file the string resulting from\n  `pinba_get_data()` calls, then decode it using the `protoc` tool - which is included by default in the test container:\n\n      php myTestFile \u003e test.rawmsg\n      protoc --decode=Pinba.Request tests/pinba.proto \u003c test.rawmsg\n\n## License\n\nUse of this software is subject to the terms in the [license](LICENSE) file\n\n[![License](https://poser.pugx.org/gggeek/polyfill-pinba/license)](https://packagist.org/packages/gggeek/polyfill-pinba)\n[![Latest Stable Version](https://poser.pugx.org/gggeek/polyfill-pinba/v/stable)](https://packagist.org/packages/gggeek/polyfill-pinba)\n[![Total Downloads](https://poser.pugx.org/gggeek/polyfill-pinba/downloads)](https://packagist.org/packages/gggeek/polyfill-pinba)\n\n[![Build Status](https://github.com/gggeek/pinba_php/actions/workflows/ci.yml/badge.svg)](https://github.com/gggeek/pinba_php/actions/workflows/ci.yml)\n[![Code Coverage](https://codecov.io/gh/gggeek/pinba_php/branch/master/graph/badge.svg)](https://app.codecov.io/gh/gggeek/pinba_php)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgggeek%2Fpinba_php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgggeek%2Fpinba_php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgggeek%2Fpinba_php/lists"}