{"id":19134033,"url":"https://github.com/umbrellio/event-tracker","last_synced_at":"2025-05-06T19:27:34.143Z","repository":{"id":65842120,"uuid":"598609336","full_name":"umbrellio/event-tracker","owner":"umbrellio","description":"Package for tracking any custom events and logging them to influxdb or prometheus in Laravel framework.","archived":false,"fork":false,"pushed_at":"2023-08-08T07:30:10.000Z","size":87,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-05T16:19:11.417Z","etag":null,"topics":["exporter","laravel","metrics","prometheus"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umbrellio.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,"governance":null}},"created_at":"2023-02-07T13:14:52.000Z","updated_at":"2023-08-02T13:16:51.000Z","dependencies_parsed_at":"2023-02-24T17:00:25.867Z","dependency_job_id":null,"html_url":"https://github.com/umbrellio/event-tracker","commit_stats":{"total_commits":15,"total_committers":4,"mean_commits":3.75,"dds":0.5333333333333333,"last_synced_commit":"dbcfe6d63d42bdca6a0f51392fbde3f89a681e9b"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fevent-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fevent-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fevent-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fevent-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umbrellio","download_url":"https://codeload.github.com/umbrellio/event-tracker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223793167,"owners_count":17203768,"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":["exporter","laravel","metrics","prometheus"],"created_at":"2024-11-09T06:25:00.881Z","updated_at":"2024-11-09T06:25:01.353Z","avatar_url":"https://github.com/umbrellio.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Event tracker\n\nPackage for tracking any custom events and logging them to influxdb or prometheus in Laravel framework.\n\n## Installation\n\n- Install\n\n```shell\ncomposer require umbrellio/event-tracker\n```\n\n## Features\n\n- Out of box it has few ready trackers:\n    - Response time - middleware for logging response-time of different endpoints\n    - Jobs duration - set of listeners for logging execution time of all jobs\n    - Jobs log - set of listeners for logging all executed jobs\n- Log anything you want by multipurpose classes - EventRepository and PrometheusRepository\n- Log into influxdb directly or by telegraf\n- Prometheus support\n- Application metrics exporter\n\n## Known issues\n\n- Prometheus integration. If your app deployed to kubernetes and it has more than one pod, where Prometheus gets metrics, then your metrics will be doubled. The reason it happens is one storage for metrics (Redis). Prometheus requests metrics from every fpm pod and they give same metrics, which prometheus sums up. \n\n## Integration\n\n### General\n\n1. Execute `php artisan vendor:publish` for publishing config example in your `config` directory\n2. Write your credentials and settings in config. If you don't need some connections or trackers you can delete them.\n\n### Prometheus\n\nEach instances of your application must have own storage for your metrics. You cannot use shared storage with several replicas of your application. In that case scraping will return metrics for both the current replica and other replicas.\n\nYou could still use shared storage if you have only one fpm replica.\n\nIn distributed systems like Kubernetes probably your application is likely running in multiple instances and in different modes (fpm, horizon). Each of them produces metrics and each of them has to be monitored by Prometheus. The exporter provided by this package will solve mentioned above problem. Correct setup should include:\n\n- Each replica has its own (local) redis instance to store metrics\n- Each replica has its own exporter which exposes `/metrics`-endpoint and grabs metrics from the redis instance. The provided exporter is available: [event-tracker/exporter](ghcr.io/umbrellio/event-tracker/exporter:latest)\n- Application writes metrics to that local redis instance\n- `event_tracker.php` config has correct credentials for local redis\n\n```php\nreturn [\n    'connection' =\u003e 'prometheus',\n    'connections' =\u003e [\n        'prometheus' =\u003e [\n            'redis' =\u003e [\n                'client' =\u003e env('EVENT_TRACKER_REDIS_CLIENT', 'phpredis'),\n                'credentials' =\u003e [\n                    'host' =\u003e env('EVENT_TRACKER_REDIS_HOST', 'localhost'),\n                    'username' =\u003e env('EVENT_TRACKER_REDIS_USERNAME', 'redis'),\n                    'password' =\u003e env('EVENT_TRACKER_REDIS_PASSWORD'),\n                    'port' =\u003e env('EVENT_TRACKER_REDIS_PORT', '6379'),\n                    'database' =\u003e env('EVENT_TRACKER_REDIS_DATABASE', 0),\n                ],\n            ],\n        ],\n    ],\n];\n```\n\n## Trackers\n\n### Response time tracker\n\nThis tracker collects information about time, that your application spends for handle request on different endpoints.\n\nAll you need for integrate this tracker is include a middleware - `ResponseTimeTrackerMiddleware` in your route's list.\nThis middleware has to be last one in your routes. Use Laravel's feature\n\n- [Sorting middleware](https://laravel.com/docs/9.x/middleware#sorting-middleware).\n\n\u003e **Influx**\n\u003e\n\u003e Records have follow format: `app_prefix.response_time,action=ExampleController@index val=1608201916\"`, where `url` is tag's\n\u003e name, and val is field's name.\n\n\u003e **Prometheus**\n\u003e\n\u003e - Buckets can be configured in config\n\u003e - Metrics have follow format: app_prefix_response_time_bucket{namespace=\"app-nc\",action=\"ExampleController@index\",le=\"1\"} 1\n\nYou can change measurement name instead of 'response_time' in config at `trackers` block. All trackers have this\nopportunity.\n\n### Jobs duration tracker\n\nThis one collects metrics about duration time of jobs in your application.\n\n\u003e **Influx**\n\u003e\n\u003e This tracker will write records in follow format: `app_prefix.jobs_duration,jobName=App\\Example\\JobName val=160820191`\n\u003e .\n\n\u003e **Prometheus**\n\u003e\n\u003e - Buckets can be configured in config\n\u003e - Metrics have follow format: app_prefix_jobs_duration_bucket{namespace=\"app-ns\",jobName=\"App\\\\Jobs\\\\JobName\",le=\"1\"}\n    2\n\nThis tracker allows you to skip any jobs, you don't want to track via config.\n\n### Jobs log\n\nThis one collects information about amount of each kind of jobs in application.\n\n\u003e **Influx**\n\u003e\n\u003e Format of writing will be: `app_prefix.jobs_log,event=processing,jobName=App\\Example\\JobName`\n\n\u003e **Prometheus**\n\u003e\n\u003e Metrics have follow format: app_prefix_jobs_log{namespace=\"app-ns\",jobName=\"App\\\\Jobs\\\\JobName\",eventName=\"processed\"}\n\u003e 2\n\nYou can skip any jobs similarly like in previous tracker.\n\n### External api response\n\nThis one collects information about requests, that your application sends to external apis.\n\nFor integrate this tracker you need create all GuzzleClient's instances with config `on_stats`.\nDuring creating GuzzleClient in your ServiceProvider you need write something like:\n\n```\n$callbackCreator = app(Umbrellio\\EventTracker\\Trackers\\ExternalApiResponse\\GuzzleClientOnStatsCallbackCreator);\n$client = new GuzzleHttp\\Client(['on_stats' =\u003e $callbackCreator-\u003ecreate()]);\n```\n\nIn this case you can modify client as you want. But if you dont need it - you can create new ServiceProvider and use\ntracker's binder:\n\n```\nclass GuzzleClientServiceProvider extends ServiceProvider\n{\n    public function boot(Umbrellio\\EventTracker\\Trackers\\ExternalApiResponse\\GuzzleClientBinder $binder): void\n    {\n        $binder-\u003ebind($this-\u003eapp);\n    }\n}\n```\n\n\u003e **Influx**\n\u003e\n\u003e Format of writing will\n\u003e\nbe: `app_prefix.external_api_response,host=api.domain.com,status=200,total_time=1.0,connect_time=0.5,namelookup_time=0.5 val=1.0`\n\n\u003e **Prometheus**\n\u003e\n\u003e - Buckets can be configured in config\n\u003e - Metrics have follow format: app_prefix_external_api_response_bucket{namespace=\"app-ns\",host=\"domain.com\",status=200,le=\"2\"} 1\n\nYou can configure last three tags in `metrics` option, if you don't need something. Beside of this tags you can specify\nany fields from handlerStats attribute in GuzzleHttp\\TransferStats object.\n\nBy default, option `group_redirects_in_one_request` is set in `false`. It means **every** request will be tracked. Even\nif it was response with redirect status code.\nHowever if you want track common time of response, set this option to `true`.\n\nField `val` can be configured by option `main_metric`. This field must be one of list in `metrics` option.\n\n### Custom trackers\n\n#### Influx\n\nYou can create your own wrap for EventRepository class and log any custom events from your app.\nPass `timestamp` attribute in `write` method for use specific time of event instead of current one. Use only nanoseconds\nfor specify time. For example - 1612369449000000000.\n\n#### Prometheus\n\nSimilarly, like in Influx case, you can use PrometheusRepositoryContract for write custom metrics.\nThere are methods for each type of Prometheus metrics: counter, gauge, histogram, summary.\n\nFor disable all trackers - use `enabled` field in package config.\n\n## Connections\n\n### Influx\n\nThis connection allows you to send event directly in influx db. This way is not recommended, because there is can be\nproblems with performance.\n\n### Telegraf\n\nThis connection just like previous one, but all events is sent to Telegraf daemon. This way is faster and more optimized\nthan previous one.\n\n### Prometheus\n\nThis connection uses Redis for temporary storing metrics. All your events will be written to redis.\nAll metrics can be fetched by `/metrics` endpoint (it will be automatically added to your routes). You can configure\nendpoint name.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumbrellio%2Fevent-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumbrellio%2Fevent-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumbrellio%2Fevent-tracker/lists"}