nathanielks / cronitor-io-php
Cronitor PHP Library
Requires
- php: >=5.6
- symfony/yaml: ^4.4|^5.2|^6.0|^7.0
Requires (Dev)
- ext-curl: *
- codeception/aspect-mock: ^3.1
- friendsofphp/php-cs-fixer: ^2.18
- phpunit/phpunit: ^6.0
- dev-master
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.7
- 1.0.6
- 1.0.5.x-dev
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.3.1
- 0.3.0
- 0.2.0
- 0.1.5
- 0.1.4
- 0.1.2
- 0.1.1
- 0.1.0
- dev-dynamic-headers
- dev-generate-config
- dev-github-actions
- dev-monitor-tests
- dev-tests
- dev-unit-tests
- dev-fix-exception
- dev-fix/readme
- dev-fix/autoloading
- dev-fix/feedback
- dev-modernize
- dev-rebuild
- dev-feature/new-sdk
- dev-aflanagan-patch-2
- dev-aflanagan-patch-1
- dev-feature/update-names
- dev-develop
This package is auto-updated.
Last update: 2024-10-29 05:10:29 UTC
README
Cronitor provides end-to-end monitoring for background jobs, websites, APIs, and anything else that can send or receive an HTTP request. This library provides convenient access to the Cronitor API from applications written in PHP. See our API docs for detailed references on configuring monitors and sending telemetry pings.
In this guide:
- Installation
- Monitoring Background Jobs
- Sending Telemetry Events
- Configuring Monitors
- Package Configuration & Env Vars
Installation
composer require cronitor/cronitor-php
To use manually, you can include the init.php
file from source.
require_once('/path/to/cronitor-php/init.php');
Monitoring Background Jobs
The $cronitor->job
function will send telemetry events before calling your function and after it exits. If your function raises an exception a fail
event will be sent (and the exception re-raised).
$cronitor = new Cronitor\Client('api_key_123'); $closureVar = time(); $cronitor->job('weekly-report-job', function() use ($closureVar){ new WeeklyReportJob($closureVar)->run(); });
Sending Telemetry Events
If you want to send a heartbeat events, or want finer control over when/how telemetry events are sent for your jobs, you can create a Monitor
instance and call the .ping
method.
$cronitor = new Cronitor\Client('api_key_123'); $monitor = $cronitor->monitor('heartbeat-monitor'); $monitor->ping(); # a basic heartbeat event # optional params can be passed as kwargs # complete list - https://cronitor.io/docs/telemetry-api#parameters $monitor->ping(['state' => 'run']); # a job/process has started # a job/process has completed (include metrics for Cronitor to record) $monitor->ping(['state' => 'complete', 'metrics' => ['count' => 1000, 'error_count' => 17]]);
Configuring Monitors
You can configure all of your monitors using a single YAML file. This can be version controlled and synced to Cronitor as part of a deployment or build process. For details on all of the attributes that can be set, see the Monitor API documentation.
# read config file and set credentials (if included). $cronitor->readConfig('./cronitor.yaml'); # sync config file's monitors to Cronitor. $cronitor->applyConfig(); # send config file's monitors to Cronitor to validate correctness. # monitors will not be saved. $cronitor->validateConfig(); # save config to local YAML file (defaults to cronitor.yaml) $cronitor->generateConfig();
The cronitor.yaml
file includes three top level keys jobs
, checks
, heartbeats
. You can configure monitors under each key by declaring a monitor key
and defining Monitor attributes
jobs: nightly-database-backup: schedule: 0 0 * * * notify: - devops-alert-pagerduty assertions: - metric.duration < 5 minutes send-welcome-email: schedule: every 10 minutes assertions: - metric.count > 0 - metric.duration < 30 seconds checks: cronitor-homepage: request: url: https://cronitor.io regions: - us-east-1 - eu-central-1 - ap-northeast-1 assertions: - response.code = 200 - response.time < 2s cronitor-telemetry-api: request: url: https://cronitor.link/ping assertions: - response.body contains ok - response.time < .25s heartbeats: production-deploy: notify: alerts: ["deploys-slack"] events: true # send alert when the event occurs
You can also create and update monitors by calling $cronitor->monitors->put
. For details on all of the attributes that can be set see the Monitor API [documentation)(https://cronitor.io/docs/monitor-api#attributes).
$cronitor->monitors->put([ [ 'type' => 'job', 'key' => 'send-customer-invoices', 'schedule' => '0 0 * * *', 'assertions' => [ 'metric.duration < 5 min' ], 'notify' => ['devops-alerts-slack'] ], [ 'type' => 'check', 'key' => 'Cronitor Homepage', 'schedule' => 'every 45 seconds', 'request' => [ 'url' => 'https://cronitor.io' ] 'assertions' => [ 'response.code = 200', 'response.time < 1.5s', 'response.json "open_orders" < 2000' ] ] ])
Pause, Reset, Delete
require 'cronitor' $monitor = $cronitor->monitor('heartbeat-monitor'); $monitor->pause(24) # pause alerting for 24 hours $monitor->unpause() # alias for ->pause(0) $monitor->ok() # manually reset to a passing state alias for $monitor->ping({state: ok}) $monitor->delete() # destroy the monitor
Package Configuration
The package needs to be configured with your account's API key
, which is available on the account settings page. You can also optionally specify an api_version
and an environment
. If not provided, your account default is used. These can also be supplied using the environment variables CRONITOR_API_KEY
, CRONITOR_API_VERSION
, CRONITOR_ENVIRONMENT
.
$apiKey = 'apiKey123'; $apiVersion = '2020-10-01'; $environment = 'staging'; $cronitor = new Cronitor\Client($apiKey, $apiVersion, $environment);
Contributing
Pull requests and features are happily considered! By participating in this project you agree to abide by the Code of Conduct.
To contribute
Fork, then clone the repo:
git clone git@github.com:your-username/cronitor-php.git
Push to your fork and submit a pull request