{"id":13617788,"url":"https://github.com/cronitorio/cronitor-python","last_synced_at":"2025-07-08T08:33:36.504Z","repository":{"id":43021716,"uuid":"88736633","full_name":"cronitorio/cronitor-python","owner":"cronitorio","description":"Python client for Cronitor","archived":false,"fork":false,"pushed_at":"2025-06-20T19:31:44.000Z","size":155,"stargazers_count":77,"open_issues_count":3,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-26T02:04:29.666Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/cronitorio.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-19T11:23:33.000Z","updated_at":"2025-06-20T19:31:48.000Z","dependencies_parsed_at":"2024-01-17T00:54:13.636Z","dependency_job_id":"cc58afc4-c134-43bb-8d5b-458fb8258585","html_url":"https://github.com/cronitorio/cronitor-python","commit_stats":{"total_commits":135,"total_committers":8,"mean_commits":16.875,"dds":0.2962962962962963,"last_synced_commit":"b5e17a9579773b005cb86a42c2aa1a12a35e7a51"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/cronitorio/cronitor-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronitorio%2Fcronitor-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronitorio%2Fcronitor-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronitorio%2Fcronitor-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronitorio%2Fcronitor-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cronitorio","download_url":"https://codeload.github.com/cronitorio/cronitor-python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronitorio%2Fcronitor-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261984719,"owners_count":23240312,"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-01T20:01:48.012Z","updated_at":"2025-07-08T08:33:36.493Z","avatar_url":"https://github.com/cronitorio.png","language":"Python","readme":"# Cronitor Python Library\n![Test](https://github.com/cronitorio/cronitor-python/workflows/Test/badge.svg)\n\n[Cronitor](https://cronitor.io/) 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 Python. See our [API docs](https://cronitor.io/docs/api) for detailed references on configuring monitors and sending telemetry pings.\n\nIn this guide:\n\n- [Installation](#Installation)\n- [Monitoring Background Jobs](#monitoring-background-jobs)\n- [Sending Telemetry Events](#sending-telemetry-events)\n- [Configuring Monitors](#configuring-monitors)\n- [Package Configuration \u0026 Env Vars](#package-configuration)\n- [Command Line Usage](#command-line-usage)\n\n## Installation\n\n```\npip install cronitor\n```\n\n## Monitoring Background Jobs\n\n#### Celery Auto-Discover\n`cronitor-python` can automatically discover all of your declared Celery tasks, including your Celerybeat scheduled tasks,\ncreating monitors for them and sending pings when tasks run, succeed, or fail. Your API keys can be found [here](https://cronitor.io/settings/api).\n\nRequires Celery 4.0 or higher. Celery auto-discover utilizes the Celery [message protocol version 2](https://docs.celeryproject.org/en/stable/internals/protocol.html#version-2).\n\n**Some important notes on support**\n\n* Tasks on [solar schedules](https://docs.celeryproject.org/en/stable/userguide/periodic-tasks.html#solar-schedules) are not supported and will be ignored.\n* [`django-celery-beat`](https://docs.celeryproject.org/en/stable/userguide/periodic-tasks.html#using-custom-scheduler-classes) is not yet supported, but is in the works.\n* If you use the default `PersistentScheduler`, the celerybeat integration overrides the celerybeat local task run database (as referenced [here](https://docs.celeryproject.org/en/stable/userguide/periodic-tasks.html#starting-the-scheduler) in the docs), named `celerybeat-schedule` by default. If you currently specify a custom location for this database, this integration will override it. **Very** few people require setting custom locations for this database. If you fall into this group and want to use `cronitor-python`'s celerybeat integration, please reach out to Cronitor support.\n\n\n```python\nimport cronitor.celery\nfrom celery import Celery\n\napp = Celery()\napp.conf.beat_schedule = {\n    'run-me-every-minute': {\n        'task': 'tasks.every_minute_celery_task',\n        'schedule': 60\n    }\n}\n\n# Discover all of your celery tasks and automatically add monitoring.\ncronitor.celery.initialize(app, api_key=\"apiKey123\")\n\n@app.task\ndef every_minute_celery_task():\n    print(\"running a background job with celery...\")\n\n@app.task\ndef non_scheduled_celery_task():\n    print(\"Even though I'm not on a schedule, I'll still be monitored!\")\n```\n\nIf you want only to monitor Celerybeat periodic tasks, and not tasks triggered any other way, you can set `celereybeat_only=True` when initializing:\n```python\napp = Celery()\ncronitor.celery.initialize(app, api_key=\"apiKey123\", celerybeat_only=True)\n```\n\n#### Manual Integration\n\nThe `@cronitor.job` is a lightweight way to monitor any background task regardless of how it is executed. It 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).\n\n```python\nimport cronitor\n\n# your api keys can found here - https://cronitor.io/settings/api\ncronitor.api_key = 'apiKey123'\n\n# Apply the cronitor decorator to monitor any function.\n# If no monitor matches the provided key, one will be created automatically.\n@cronitor.job('send-invoices')\ndef send_invoices_task(*args, **kwargs):\n    ...\n```\n\n#### You can provide monitor attributes that will be synced when your app starts\n\nTo sync attributes, provide an API key with monitor:write privileges.\n\n```python\nimport cronitor\n\n# Copy your SDK Integration key from https://cronitor.io/app/settings/api\ncronitor.api_key = 'apiKey123'\n\n@cronitor.job('send-invoices', attributes={'schedule': '0 8 * * *', 'notify': ['devops-alerts']})\ndef send_invoices_task(*args, **kwargs):\n    ...\n```\n\n## Sending Telemetry Events\n\nIf you want to send a heartbeat events, or want finer control over when/how [telemetry events](https://cronitor.io/docs/telemetry-api) are sent for your jobs, you can create a monitor instance and call the `.ping` method.\n\n```python\nimport cronitor\n\n# your api keys can found here - https://cronitor.io/settings/api\ncronitor.api_key = 'apiKey123'\n\n# optionally, set an environment\ncronitor.environment = 'staging'\n\nmonitor = cronitor.Monitor('heartbeat-monitor')\nmonitor.ping() # send a heartbeat event\n\n# optional params can be passed as keyword arguements.\n# for a complete list see https://cronitor.io/docs/telemetry-api#parameters\nmonitor.ping(\n    state='run|complete|fail|ok', # run|complete|fail used to measure lifecycle of a job, ok used for manual reset only.\n    message='', # message that will be displayed in alerts as well as monitor activity panel on your dashboard.\n    metrics={\n        'duration': 100, # how long the job ran (complete|fail only). cronitor will calculate this when not provided\n        'count': 4500, # if your job is processing a number of items you can report a count\n        'error_count': 10 # the number of errors that occurred while this job was running\n    }\n)\n```\n\n## Configuring Monitors\n\n### YAML Configuration File\n\nYou can configure all of your monitors using a single YAML file. This can be version controlled and synced to Cronitor as part of\na deployment or build process. For details on all of the attributes that can be set, see the [Monitor API](https://cronitor.io/docs/monitor-api) documentation.\n\n```python\nimport cronitor\n\n# your api keys can found here - https://cronitor.io/settings/api\ncronitor.api_key = 'apiKey123'\n\ncronitor.read_config('./cronitor.yaml') # parse the yaml file of monitors\n\ncronitor.validate_config() # send monitors to Cronitor for configuration validation\n\ncronitor.apply_config() # sync the monitors from the config file to Cronitor\n\ncronitor.generate_config() # generate a new config file from the Cronitor API\n```\n\nThe timeout value for validate_config, apply_config and generate_config is 10 seconds by default. The value can be rewritten by setting the environment variable `CRONITOR_TIMEOUT`. It can also be rewritten by assigning a value to cronitor.timeout.\n\n```python\nimport cronitor\n\ncronitor.timeout = 30\ncronitor.apply_config()\n```\n\nThe `cronitor.yaml` file includes three top level keys `jobs`, `checks`, `heartbeats`. You can configure monitors under each key by defining [monitors](https://cronitor.io/docs/monitor-api#attributes).\n\n```yaml\njobs:\n    nightly-database-backup:\n        schedule: 0 0 * * *\n        notify:\n            - devops-alert-pagerduty\n        assertions:\n            - metric.duration \u003c 5 minutes\n\n    send-welcome-email:\n        schedule: every 10 minutes\n        assertions:\n            - metric.count \u003e 0\n            - metric.duration \u003c 30 seconds\n\nchecks:\n    cronitor-homepage:\n        request:\n            url: https://cronitor.io\n            regions:\n                - us-east-1\n                - eu-central-1\n                - ap-northeast-1\n        assertions:\n            - response.code = 200\n            - response.time \u003c 2s\n\n    cronitor-ping-api:\n        request:\n            url: https://cronitor.link/ping\n        assertions:\n            - response.body contains ok\n            - response.time \u003c .25s\n\nheartbeats:\n    production-deploy:\n        notify:\n            alerts: ['deploys-slack']\n            events: true # send alert when the event occurs\n\n```\n#### Async Uploads\nIf you are working with large YAML files (300+ monitors), you may hit timeouts when trying to sync monitors in a single http request. This workload to be processed asynchronously by adding the key `async: true` to the config file. The request will immediately return a `batch_key`. If a `webhook_url` parameter is included, Cronitor will POST to that URL with the results of the background processing and will include the `batch_key` matching the one returned in the initial response.\n\n### Monitor.put\n\nYou can also create and update monitors by calling `Monitor.put`. For details on all of the attributes that can be set see the Monitor API [documentation](https://cronitor.io/docs/monitor-api#attributes).\n\n```python\nimport cronitor\n\nmonitors = cronitor.Monitor.put([\n  {\n    'type': 'job',\n    'key': 'send-customer-invoices',\n    'schedule': '0 0 * * *',\n    'assertions': [\n        'metric.duration \u003c 5 min'\n    ],\n    'notify': ['devops-alerts-slack']\n  },\n  {\n    'type': 'check',\n    'key': 'Cronitor Homepage',\n    'schedule': 'every 45 seconds',\n    'request': {\n        'url': 'https://cronitor.io'\n    },\n    'assertions': [\n        'response.code = 200',\n        'response.time \u003c 600ms',\n    ]\n  }\n])\n```\n\n### Pausing, Reseting, and Deleting\n\n```python\nimport cronitor\n\nmonitor = cronitor.Monitor('heartbeat-monitor');\n\nmonitor.pause(24) # pause alerting for 24 hours\nmonitor.unpause() # alias for .pause(0)\nmonitor.ok() # manually reset to a passing state alias for monitor.ping({state: ok})\nmonitor.delete() # destroy the monitor\n```\n\n## Package Configuration\n\nThe package needs to be configured with your account's `API key`, which is available on the [account settings](https://cronitor.io/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`.\n\n```python\nimport cronitor\n\n# your api keys can found here - https://cronitor.io/settings\ncronitor.api_key = 'apiKey123'\ncronitor.api_version = '2020-10-01'\ncronitor.environment = 'cluster_1_prod'\n```\n\n## Command Line Usage\n\n```bash\n\u003e\u003e python -m cronitor -h\n\nusage: cronitor [-h] [--apikey APIKEY] [--key KEY] [--msg MSG]\n                (--run | --complete | --fail | --ok | --pause PAUSE)\n\nSend status messages to Cronitor ping API.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --authkey AUTHKEY, -a AUTHKEY\n                        Auth Key from Account page\n  --key KEY, -k KEY     Unique key for the monitor to take ping\n  --msg MSG, -m MSG     Optional message to send with ping/fail\n  --tick, -t            Call ping on given monitor\n  --run, -r             Call ping with state=run on given monitor\n  --complete, -C        Call ping with state=complete on given monitor\n  --fail, -f            Call ping with state=fail on given monitor\n  --pause PAUSE, -P PAUSE\n                        Call pause on given monitor\n```\n\n\n## Contributing\n\nPull requests and features are happily considered! By participating in this project you agree to abide by the [Code of Conduct](http://contributor-covenant.org/version/2/0).\n\n### To contribute\n\nFork, then clone the repo:\n\n    git clone git@github.com:your-username/cronitor-python.git\n\nSet up your machine:\n\n    pip install -r requirements\n\nMake sure the tests pass:\n\n    pytest\n\nMake your change. Add tests for your change. Make the tests pass:\n\n    pytest\n\n\nPush to your fork and [submit a pull request]( https://github.com/cronitorio/cronitor-python/compare/)\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcronitorio%2Fcronitor-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcronitorio%2Fcronitor-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcronitorio%2Fcronitor-python/lists"}