PHPackages tuupola/instrument - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. tuupola/instrument ActiveLibrary[Logging & Monitoring](/categories/logging) tuupola/instrument ================== Application metrics toolbox for InfluxDB 1.3.0(4y ago)4214.3k31MITPHPPHP ^7.0|^8.0 Since Mar 6Pushed 4y ago2 watchersCompare [ Source](https://github.com/tuupola/instrument)[ Packagist](https://packagist.org/packages/tuupola/instrument)[ Docs](https://github.com/tuupola/instrument)[ GitHub Sponsors](https://github.com/tuupola)[ RSS](/packages/tuupola-instrument/feed)WikiDiscussions master Synced 3w ago READMEChangelog (1)Dependencies (5)Versions (8)Used By (1) Instrument ========== [](#instrument) [![Latest Version](https://camo.githubusercontent.com/c1bf75840a4f5a3a6275eafd1f2cdd20ba820c0ebbda7dc3bec15b18118bb4db/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f747575706f6c612f696e737472756d656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tuupola/instrument)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Build Status](https://camo.githubusercontent.com/2ab473699168fccfef0b7846d0c0f10f020c87d988446039831466b7cf75aeff/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f747575706f6c612f696e737472756d656e742f54657374732f6d61737465723f7374796c653d666c61742d737175617265)](https://github.com/tuupola/instrument/actions)[![Coverage](https://camo.githubusercontent.com/a4f414dd65566f8c864fca8df4ea8685c315cd9d1582ca85a34258278e433c6d/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f747575706f6c612f696e737472756d656e742e7376673f7374796c653d666c61742d737175617265)](https://codecov.io/github/tuupola/instrument) With Instrument you can monitor and measure your PHP application performance. It can collect and store metrics such as script execution time and memory usage or time spent in database. [![Instrument](https://camo.githubusercontent.com/1107dfc2040d3b4eada3b94d93375d6e8f9ecad9b355243c2f300590ff244606/68747470733a2f2f617070656c7369696e692e6e65742f696d672f696e737472756d656e742d686561646c696e652d313430302e706e67)](https://camo.githubusercontent.com/1107dfc2040d3b4eada3b94d93375d6e8f9ecad9b355243c2f300590ff244606/68747470733a2f2f617070656c7369696e692e6e65742f696d672f696e737472756d656e742d686561646c696e652d313430302e706e67) Usage ----- [](#usage) Install using [composer](https://getcomposer.org/). ``` $ composer require tuupola/instrument ``` You also must have access to [InfluxDB](https://influxdata.com/) database to store the data. After installing connect to your database and start sending metrics. ``` require __DIR__ . "/vendor/autoload.php"; $influxdb = InfluxDB\Client::fromDSN("http+influxdb://user:pass@localhost:8086/instrument"); $instrument = new Instrument\Instrument([ "adapter" => new Instrument\Adapter\InfluxDB($influxdb), "transformer" => new Instrument\Transformer\InfluxDB ]); $instrument->count("users", 100); $instrument->send(); ``` Optionally if you want to use the [gauge](https://github.com/tuupola/instrument#gauge) datatype you need the [shmop extension](http://php.net/manual/en/book.shmop.php) and [klaussilveira/simple-shm](https://github.com/klaussilveira/SimpleSHM/) library. ``` composer require klaussilveira/simple-shm ``` There is also a [companion middleware](https://github.com/tuupola/instrument-middleware) which can automate basic instrumenting of application code if you are using PSR-7 based framework. Demo ---- [](#demo) Example [Grafana](http://grafana.org/) dashboard is included. To see Instrument in action start the Vagrant demo server and make some example requests. ``` $ cd demo $ vagrant up $ while sleep 1; do curl http://192.168.50.53/random; done ``` The above commands start the server and inserts random Instrument data every second. You can now access the provided [demo dashboard](http://192.168.50.53:3000/dashboard/db/instrument) (admin:admin) to see this happening live. [![Grafana](https://camo.githubusercontent.com/31c18f86c8e213fb45cb5310069fa7309760474c65d18131bc8a1b70281ae032/687474703a2f2f7777772e617070656c7369696e692e6e65742f696d672f696e737472756d656e742d67726166616e612d313430302d322e706e67)](https://camo.githubusercontent.com/31c18f86c8e213fb45cb5310069fa7309760474c65d18131bc8a1b70281ae032/687474703a2f2f7777772e617070656c7369696e692e6e65742f696d672f696e737472756d656e742d67726166616e612d313430302d322e706e67) Writing data ------------ [](#writing-data) Documentation assumes you have working knowledge of [InfluxDB data structures](https://docs.influxdata.com/influxdb/v1.0/concepts/key_concepts/). Each measurement must have a `name`. Measurements should contain either one `value` or several value `fields` or both. Optionally measurement can have one or more `tags`. For example to create a new `count` measurement with name `users` with one value of `100` use either of the following. ``` $instrument->count("users", 100); $instrument->count("users")->set(100); $instrument->send(); ``` ``` > SELECT * FROM users name: users --------- time value 1457067288109133121 100 ``` To log several values and additionally tag the measurement. ``` $instrument ->count("users") ->set("total", 100) ->set("active", 27) ->tags(["host" => "localhost"]); $instrument->send(); ``` ``` > SELECT * FROM users name: users --------- time total active host 1457067288109134122 100 27 localhost ``` The event datatype does not contain numerical measurements. ``` $instrument ->event("deploy", "New version deployed") ->tags(["host" => "localhost"]); $instrument->send(); ``` ``` > SELECT * FROM events; name: events ------------ time title description host 1464277178854200406 deploy New version deployed localhost ``` Datatypes --------- [](#datatypes) ### Count [](#count) Count is the simplest datatype. In addition to setting the value you can also increment and decrement it. ``` $requests = $instrument->count("requests", 50); /* 50 */ $requests->increase(); /* 51 */ $requests->decrease(); /* 50 */ $requests->increase(5); /* 55 */ $instrument->send(); ``` Or if you prefer fluent interfaces you can also do the following. ``` $instrument ->count("users") ->set("active", 27) /* 27 */ ->increase("active", 5) /* 32 */ ->decrease("active", 2); /* 30 */ $instrument->send(); ``` ### Timing [](#timing) With timing you can measure execution time in milliseconds. You can either pass the value yourself or use the provided helpers to measure code execution time. ``` $instrument->timing("roundtrip")->set("firstbyte", 28); $instrument->timing("roundtrip")->set("lastbyte", 40); $instrument->timing("roundtrip")->set("processing", function () { /* Code to be measured */ }); $instrument->timing("roundtrip")->start("fetching"); /* Code to be measured */ $instrument->timing("roundtrip")->stop("fetching"); $instrument->send(); ``` Since timing internally uses [symfony/stopwatch](https://github.com/symfony/stopwatch) you can get PHP memory usage as a bonus. It is not automatically included in the measurement data, but you can include it manually. ``` $memory = $instrument->timing("roundtrip")->memory() $instrument->timing("roundtrip")->set("memory", $memory); $instrument->send(); ``` ### Gauge [](#gauge) Gauge is same as count. However it remembers the value between requests. Gauge values are zeroed when server restarts. You need the [shmop extension](http://php.net/manual/en/book.shmop.php) and [klaussilveira/simple-shm](https://github.com/klaussilveira/SimpleSHM/) to be able to use gauges. ``` $errors = $instrument->gauge("errors"); $errors->increase("fatal"); /* 1 */ $errors->increase("critical"); /* 1 */ unset($errors); $errors = $instrument->gauge("errors"); $errors->increase("fatal"); /* 2 */ $errors->increase("critical", 4); /* 5 */ $instrument->send(); ``` Single value can be deleted from shared memory with `delete()` method. All values of the named gauge can be deleted at once with `clear()` method. ``` $errors = $instrument->gauge("errors"); $errors->delete("fatal"); /* null */ $errors->clear(); ``` ### Event [](#event) Events can be used to display [annotations](http://docs.grafana.org/reference/annotations/) in your dashboard. By default they do not contain numerical measurements. Instead it contains `title` and `description` fields. These should contain a short name and longer description for the event. ``` $instrument ->event("deploy", "Version 0.9.0 deployed") ->tags(["host" => "localhost"]); $instrument ->event("deploy", "Version 0.9.1 deployed") ->tags(["host" => "localhost"]); $instrument->send(); ``` ``` > SELECT * FROM events; name: events ------------ time title description host 1464277178854200406 deploy Version 0.9.0 deployed localhost 1464277178854201240 deploy Version 0.9.1 deployed localhost ``` If you are using Grafana you can use above data by using `SELECT * FROM events WHERE $timeFilter` as the annotation query. Also set the column mappings as shown below. [![Grafana](https://camo.githubusercontent.com/f536a91640e3e6a1335e55fa6a6f87607273b3449c29e6b4e45f44b9c9c3b374/687474703a2f2f7777772e617070656c7369696e692e6e65742f696d672f696e737472756d656e742d67726166616e612d6576656e742d313430302e706e67)](https://camo.githubusercontent.com/f536a91640e3e6a1335e55fa6a6f87607273b3449c29e6b4e45f44b9c9c3b374/687474703a2f2f7777772e617070656c7369696e692e6e65742f696d672f696e737472756d656e742d67726166616e612d6576656e742d313430302e706e67) Testing ------- [](#testing) You can run tests either manually... ``` $ composer test ``` ... or automatically on every code change. This requires [entr](http://entrproject.org/) to work. ``` $ composer watch ``` Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security -------- [](#security) If you discover any security related issues, please email instead of using the issue tracker. License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 38 — LowBetter than 83% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity31 Limited adoption so far Community12 Small or concentrated contributor base Maturity73 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~404 days Recently: every ~504 days Total 6 Last Release 1748d ago Major Versions 0.3.0 → 1.0.02016-05-20 PHP version history (3 changes)0.2.0PHP >=5.5.0 1.0.0PHP ^5.5 || ^7.0 1.3.0PHP ^7.0|^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/3325405a7d8a43bc40dd0e760a4b7f268fba32a7150cf0327f64f13d1661df0b?d=identicon)[tuupola](/maintainers/tuupola) --- Top Contributors [![tuupola](https://avatars.githubusercontent.com/u/21913?v=4)](https://github.com/tuupola "tuupola (80 commits)") --- Tags Metricsinfluxdb ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/tuupola-instrument/health.svg) ``` [![Health](https://phpackages.com/badges/tuupola-instrument/health.svg)](https://phpackages.com/packages/tuupola-instrument) ``` ### Alternatives [beberlei/metrics Simple library to talk to metrics collector services. 3211.2M4](/packages/beberlei-metrics)[artprima/prometheus-metrics-bundle Symfony 5.4/6.4/7.4/8.x Prometheus Metrics Bundle 1764.0M3](/packages/artprima-prometheus-metrics-bundle)[leventcz/laravel-top Real-time monitoring straight from the command line for Laravel applications. 583112.2k1](/packages/leventcz-laravel-top)[open-telemetry/api API for OpenTelemetry PHP. 1938.5M262](/packages/open-telemetry-api)[open-telemetry/sdk SDK for OpenTelemetry PHP. 2326.5M315](/packages/open-telemetry-sdk)[slickdeals/statsd a PHP client for statsd 254.8M10](/packages/slickdeals-statsd) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)