{"id":20491649,"url":"https://github.com/dalibo/check_patroni","last_synced_at":"2025-04-13T16:55:13.079Z","repository":{"id":44454851,"uuid":"512687544","full_name":"dalibo/check_patroni","owner":"dalibo","description":"A nagios plugin for patroni.","archived":false,"fork":false,"pushed_at":"2025-02-18T11:03:33.000Z","size":193,"stargazers_count":8,"open_issues_count":2,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-27T07:51:32.125Z","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":"postgresql","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dalibo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2022-07-11T09:09:12.000Z","updated_at":"2025-03-12T13:30:51.000Z","dependencies_parsed_at":"2024-05-02T08:50:29.033Z","dependency_job_id":"d3317833-f29f-4dd4-9278-ae4395f20ffb","html_url":"https://github.com/dalibo/check_patroni","commit_stats":{"total_commits":64,"total_committers":3,"mean_commits":"21.333333333333332","dds":0.109375,"last_synced_commit":"0800fc72e9a5e8d68ff6de091608bdd5c70d63f0"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fcheck_patroni","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fcheck_patroni/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fcheck_patroni/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fcheck_patroni/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalibo","download_url":"https://codeload.github.com/dalibo/check_patroni/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248750011,"owners_count":21155682,"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-11-15T17:25:22.721Z","updated_at":"2025-04-13T16:55:13.072Z","avatar_url":"https://github.com/dalibo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# check_patroni\n\nA nagios plugin for patroni.\n\n## Features\n\n- Check presence of leader, replicas, node counts.\n- Check each node for replication status.\n\n\n```\nUsage: check_patroni [OPTIONS] COMMAND [ARGS]...\n\n  Nagios plugin that uses Patroni's REST API to monitor a Patroni cluster.\n\nOptions:\n  --config FILE         Read option defaults from the specified INI file\n                        [default: config.ini]\n  -e, --endpoints TEXT  Patroni API endpoint. Can be specified multiple times\n                        or as a list of comma separated addresses. The node\n                        services checks the status of one node, therefore if\n                        several addresses are specified they should point to\n                        different interfaces on the same node. The cluster\n                        services check the status of the cluster, therefore\n                        it's better to give a list of all Patroni node\n                        addresses.  [default: http://127.0.0.1:8008]\n  --cert_file PATH      File with the client certificate.\n  --key_file PATH       File with the client key.\n  --ca_file PATH        The CA certificate.\n  -v, --verbose         Increase verbosity -v (info)/-vv (warning)/-vvv\n                        (debug)\n  --version\n  --timeout INTEGER     Timeout in seconds for the API queries (0 to disable)\n                        [default: 2]\n  --help                Show this message and exit.\n\nCommands:\n  cluster_config_has_changed    Check if the hash of the configuration...\n  cluster_has_leader            Check if the cluster has a leader.\n  cluster_has_replica           Check if the cluster has healthy replicas...\n  cluster_has_scheduled_action  Check if the cluster has a scheduled...\n  cluster_is_in_maintenance     Check if the cluster is in maintenance...\n  cluster_node_count            Count the number of nodes in the cluster.\n  node_is_alive                 Check if the node is alive ie patroni is...\n  node_is_leader                Check if the node is a leader node.\n  node_is_pending_restart       Check if the node is in pending restart...\n  node_is_primary               Check if the node is the primary with the...\n  node_is_replica               Check if the node is a replica with no...\n  node_patroni_version          Check if the version is equal to the input\n  node_tl_has_changed           Check if the timeline has changed.\n```\n\n## Install\n\ncheck_patroni is licensed under PostgreSQL license.\n\n```\n$ pip install git+https://github.com/dalibo/check_patroni.git\n```\n\ncheck_patroni works on python 3.6, we keep it that way because patroni also\nsupports it and there are still lots of RH 7 variants around. That being said\npython 3.6 has been EOL for ages and there is no support for it in the github\nCI.\n\n## Support\n\nIf you hit a bug or need help, open a [GitHub\nissue](https://github.com/dalibo/check_patroni/issues/new). Dalibo has no\ncommitment on response time for public free support. Thanks for you\ncontribution !\n\n## Config file\n\nAll global and service specific parameters can be specified via a config file has follows:\n\n```\n[options]\nendpoints = https://10.20.199.3:8008, https://10.20.199.4:8008,https://10.20.199.5:8008\ncert_file = ./ssl/my-cert.pem\nkey_file = ./ssl/my-key.pem\nca_file = ./ssl/CA-cert.pem\ntimeout = 0\n\n[options.node_is_replica]\nlag=100\n```\n## Thresholds\n\nThe format for the threshold parameters is `[@][start:][end]`.\n\n* `start:` may be omitted if `start == 0`\n* `~:` means that start is negative infinity\n* If `end` is omitted, infinity is assumed\n* To invert the match condition, prefix the range expression with `@`.\n\nA match is found when: `start \u003c= VALUE \u003c= end`.\n\nFor example, the following command will raise:\n\n* a warning if there is less than 1 nodes, which can be translated to outside of range [2;+INF[\n* a critical if there are no nodes, which can be translated to outside of range [1;+INF[\n\n```\ncheck_patroni -e https://10.20.199.3:8008 cluster_has_replica --warning 2: --critical 1:\n```\n\n## SSL\n\nSeveral options are available:\n\n* the server's CA certificate is not available or trusted by the client system:\n  * `--ca_cert`: your certification chain `cat CA-certificate server-certificate \u003e cabundle`\n* you have a client certificate for authenticating with Patroni's REST API:\n  * `--cert_file`: your certificate or the concatenation of your certificate and private key\n  * `--key_file`: your private key (optional)\n\n## Shell completion\n\nWe use the [click] library which supports shell completion natively.\n\nShell completion can be added by typing the following command or adding it to\na file spécific to your shell of choice.\n\n* for Bash (add to `~/.bashrc`):\n  ```\n  eval \"$(_CHECK_PATRONI_COMPLETE=bash_source check_patroni)\"\n  ```\n* for Zsh  (add to `~/.zshrc`):\n  ```\n  eval \"$(_CHECK_PATRONI_COMPLETE=zsh_source check_patroni)\"\n  ```\n* for Fish (add to `~/.config/fish/completions/check_patroni.fish`):\n  ```\n  eval \"$(_CHECK_PATRONI_COMPLETE=fish_source check_patroni)\"\n  ```\n\nPlease note that shell completion is not supported far all shell versions, for\nexample only Bash versions older than 4.4 are supported.\n\n[click]: https://click.palletsprojects.com/en/8.1.x/shell-completion/\n\n## Connection errors and service status\n\nIf patroni is not running, we have no way to know if the provided endpoint is\nvalid, therefore the check returns UNKNOWN.\n\n## Cluster services\n\n### cluster_config_has_changed\n\n```\nUsage: check_patroni cluster_config_has_changed [OPTIONS]\n\n  Check if the hash of the configuration has changed.\n\n  Note: either a hash or a state file must be provided for this service to\n  work.\n\n  Check:\n  * `OK`: The hash didn't change\n  * `CRITICAL`: The hash of the configuration has changed compared to the input (`--hash`) or last time (`--state_file`)\n\n  Perfdata:\n  * `is_configuration_changed` is 1 if the configuration has changed\n\nOptions:\n  --hash TEXT            A hash to compare with.\n  -s, --state-file TEXT  A state file to store the hash of the configuration.\n  --save                 Set the current configuration hash as the reference\n                         for future calls.\n  --help                 Show this message and exit.\n```\n\n### cluster_has_leader\n\n```\nUsage: check_patroni cluster_has_leader [OPTIONS]\n\n  Check if the cluster has a leader.\n\n  This check applies to any kind of leaders including standby leaders.\n\n  A leader is a node with the \"leader\" role and a \"running\" state.\n\n  A standby leader is a node with a \"standby_leader\" role and a \"streaming\" or\n  \"in archive recovery\" state. Please note that log shipping could be stuck\n  because the WAL are not available or applicable. Patroni doesn't provide\n  information about the origin cluster (timeline or lag), so we cannot check\n  if there is a problem in that particular case. That's why we issue a warning\n  when the node is \"in archive recovery\". We suggest using other supervision\n  tools to do this (eg. check_pgactivity).\n\n  Check:\n  * `OK`: if there is a leader node.\n  * 'WARNING': if there is a stanby leader in archive mode.\n  * `CRITICAL`: otherwise.\n\n  Perfdata:\n  * `has_leader` is 1 if there is any kind of leader node, 0 otherwise\n  * `is_standby_leader_in_arc_rec` is 1 if the standby leader node is \"in\n     archive recovery\", 0 otherwise\n  * `is_standby_leader` is 1 if there is a standby leader node, 0 otherwise\n  * `is_leader` is 1 if there is a \"classical\" leader node, 0 otherwise\n\nOptions:\n  --help  Show this message and exit.\n```\n\n### cluster_has_replica\n\n```\nUsage: check_patroni cluster_has_replica [OPTIONS]\n\n  Check if the cluster has healthy replicas and/or if some are sync or quorum\n  standbies\n\n  For patroni (and this check):\n  * a replica is `streaming` if the `pg_stat_wal_receiver` say's so.\n  * a replica is `in archive recovery`, if it's not `streaming` and has a `restore_command`.\n\n  A healthy replica:\n  * has a `replica`, `quorum_standby` or `sync_standby` role\n  * has the same timeline as the leader and\n    * is in `running` state (patroni \u003c V3.0.4)\n    * is in `streaming` or `in archive recovery` state (patroni \u003e= V3.0.4)\n  * has a lag lower or equal to `max_lag`\n\n  Please note that replica `in archive recovery` could be stuck because the\n  WAL are not available or applicable (the server's timeline has diverged for\n  the leader's). We already detect the latter but we will miss the former.\n  Therefore, it's preferable to check for the lag in addition to the healthy\n  state if you rely on log shipping to help lagging standbies to catch up.\n\n  Since we require a healthy replica to have the same timeline as the leader,\n  it's possible that we raise alerts when the cluster is performing a\n  switchover or failover and the standbies are in the process of catching up\n  with the new leader. The alert shouldn't last long.\n\n  In PostgreSQL, synchronous replication has two modes: on and quorum and is\n  configured with the gucs `synchronous_standby_names` and\n  `synchronous_commit`. Patroni uses the parameter `synchronous_mode`, which\n  can be set to `on`, `quorum` and `off`, and has `synchronous_node_count` to\n  configure the synchronous replication factor. Please note that, in\n  synchronous replication, the number of servers tagged as\n  \"{sync|quorum}_standby\" (what we measure) is not always equal tot\n  `synchronous_node_count`.\n\n  Check:\n  * `OK`: if the healthy_replica count and their lag are compatible with the replica count threshold.\n          and if the synchronous replica count is compatible with the sync replica count threshold.\n  * `WARNING` / `CRITICAL`: otherwise\n\n  Perfdata:\n  * healthy_replica \u0026 unhealthy_replica count\n  * the number of sync_replica (sync or quorum depending on `--sync-type`), they are included\n    in the previous count\n  * the lag of each replica labelled with \"member name\"_lag\n  * the timeline of each replica labelled with \"member name\"_timeline\n  * a boolean to tell if the node is a sync stanbdy labelled with \"member name\"_sync\n\nOptions:\n  -w, --warning TEXT             Warning threshold for the number of healthy\n                                 replica nodes.\n  -c, --critical TEXT            Critical threshold for the number of healthy\n                                 replica nodes.\n  --sync-warning TEXT            Warning threshold for the number of sync\n                                 replica.\n  --sync-critical TEXT           Critical threshold for the number of sync\n                                 replica.\n  --sync-type [any|sync|quorum]  Synchronous replication mode used to filter\n                                 and count sync standbies.  [default: any]\n  --max-lag TEXT                 maximum allowed lag\n  --help                         Show this message and exit.\n```\n\n### cluster_has_scheduled_action\n\n```\nUsage: check_patroni cluster_has_scheduled_action [OPTIONS]\n\n  Check if the cluster has a scheduled action (switchover or restart)\n\n  Check:\n  * `OK`: If the cluster has no scheduled action\n  * `CRITICAL`: otherwise.\n\n  Perfdata:\n  * `scheduled_actions` is 1 if the cluster has scheduled actions.\n  * `scheduled_switchover` is 1 if the cluster has a scheduled switchover.\n  * `scheduled_restart` counts the number of scheduled restart in the cluster.\n\nOptions:\n  --help  Show this message and exit.\n```\n\n### cluster_is_in_maintenance\n\n```\nUsage: check_patroni cluster_is_in_maintenance [OPTIONS]\n\n  Check if the cluster is in maintenance mode or paused.\n\n  Check:\n  * `OK`: If the cluster is in maintenance mode.\n  * `CRITICAL`: otherwise.\n\n  Perfdata:\n  * `is_in_maintenance` is 1 the cluster is in maintenance mode,  0 otherwise\n\nOptions:\n  --help  Show this message and exit.\n```\n\n### cluster_node_count\n\n```\nUsage: check_patroni cluster_node_count [OPTIONS]\n\n  Count the number of nodes in the cluster.\n\n  The role refers to the role of the server in the cluster. Possible values\n  are:\n  * leader (master was removed in patroni 4.0.0)\n  * replica\n  * standby_leader\n  * sync_standby\n  * quorum_standby\n  * demoted\n  * promoted\n  * uninitialized\n\n  The state refers to the state of PostgreSQL. Possible values are:\n  * initializing new cluster, initdb failed\n  * running custom bootstrap script, custom bootstrap failed\n  * starting, start failed\n  * restarting, restart failed\n  * running, streaming, in archive recovery\n  * stopping, stopped, stop failed\n  * creating replica\n  * crashed\n\n  The \"healthy\" checks only ensures that:\n  * a leader has the running state\n  * a standby_leader has the running or streaming (V3.0.4) state\n  * a replica, quorum_standby or sync_standby has the running or streaming (V3.0.4) state\n\n  Since we dont check the lag or timeline, \"in archive recovery\" is not\n  considered a valid state for this service. See cluster_has_leader and\n  cluster_has_replica for specialized checks.\n\n  Check:\n  * Compares the number of nodes against the normal and healthy nodes warning and critical thresholds.\n  * `OK`:  If they are not provided.\n\n  Perfdata:\n  * `members`: the member count.\n  * `healthy_members`: the running and streaming member count.\n  * all the roles of the nodes in the cluster with their count (start with \"role_\").\n  * all the statuses of the nodes in the cluster with their count (start with \"state_\").\n\nOptions:\n  -w, --warning TEXT       Warning threshold for the number of nodes.\n  -c, --critical TEXT      Critical threshold for the number of nodes.\n  --healthy-warning TEXT   Warning threshold for the number of healthy nodes\n                           (running + streaming).\n  --healthy-critical TEXT  Critical threshold for the number of healthy nodes\n                           (running + streaming).\n  --help                   Show this message and exit.\n```\n\n## Node services\n\n### node_is_alive\n\n```\nUsage: check_patroni node_is_alive [OPTIONS]\n\n  Check if the node is alive ie patroni is running. This is a liveness check\n  as defined in Patroni's documentation. If patroni is not running, we have no\n  way to know if the provided endpoint is valid, therefore the check returns\n  UNKNOWN.\n\n  Check:\n  * `OK`: If patroni the liveness check returns with HTTP status 200.\n  * `CRITICAL`: if partoni's liveness check returns with an HTTP status\n     other than 200.\n\n  Perfdata:\n  * `is_running` is 1 if patroni is running, 0 otherwise\n\nOptions:\n  --help  Show this message and exit.\n```\n\n### node_is_pending_restart\n\n```\nUsage: check_patroni node_is_pending_restart [OPTIONS]\n\n  Check if the node is in pending restart state.\n\n  This situation can arise if the configuration has been modified but requires\n  a restart of PostgreSQL to take effect.\n\n  Check:\n  * `OK`: if the node has no pending restart tag.\n  * `CRITICAL`: otherwise\n\n  Perfdata: `is_pending_restart` is 1 if the node has pending restart tag, 0\n  otherwise.\n\nOptions:\n  --help  Show this message and exit.\n```\n\n### node_is_leader\n\n```\nUsage: check_patroni node_is_leader [OPTIONS]\n\n  Check if the node is a leader node.\n\n  This check applies to any kind of leaders including standby leaders. To\n  check explicitly for a standby leader use the `--is-standby-leader` option.\n\n  Check:\n  * `OK`: if the node is a leader.\n  * `CRITICAL:` otherwise\n\n  Perfdata: `is_leader` is 1 if the node is a leader node, 0 otherwise.\n\nOptions:\n  --is-standby-leader  Check for a standby leader\n  --help               Show this message and exit.\n```\n\n### node_is_primary\n\n```\nUsage: check_patroni node_is_primary [OPTIONS]\n\n  Check if the node is the primary with the leader lock.\n\n  This service is not valid for a standby leader, because this kind of node is\n  not a primary.\n\n  Check:\n  * `OK`: if the node is a primary with the leader lock.\n  * `CRITICAL:` otherwise\n\n  Perfdata: `is_primary` is 1 if the node is a primary with the leader lock, 0\n  otherwise.\n\nOptions:\n  --help  Show this message and exit.\n```\n\n### node_is_replica\n\n```\nUsage: check_patroni node_is_replica [OPTIONS]\n\n  Check if the node is a replica with no noloadbalance tag.\n\n  It is possible to check if the node is synchronous or asynchronous. If\n  nothing is specified any kind of replica is accepted.  When checking for a\n  synchronous replica, it's not possible to specify a lag.\n\n  This service is using the following Patroni endpoints: replica, asynchronous\n  and synchronous. The first two implement the `lag` tag. For these endpoints\n  the state of a replica node doesn't reflect the replication state\n  (`streaming` or `in archive recovery`), we only know if it's `running`. The\n  timeline is also not checked.\n\n  Therefore, if a cluster is using asynchronous replication, it is recommended\n  to check for the lag to detect a divegence as soon as possible.\n\n  Check:\n  * `OK`: if the node is a running replica with noloadbalance tag and the lag is under the maximum threshold.\n  * `CRITICAL`:  otherwise\n\n  Perfdata: `is_replica` is 1 if the node is a running replica with\n  noloadbalance tag and the lag is under the maximum threshold, 0 otherwise.\n\nOptions:\n  --max-lag TEXT                 maximum allowed lag\n  --is-sync                      check if the replica is synchronous\n  --sync-type [any|sync|quorum]  Synchronous replication mode.  [default: any]\n  --is-async                     check if the replica is asynchronous\n  --help                         Show this message and exit.\n```\n\n### node_patroni_version\n\n```\nUsage: check_patroni node_patroni_version [OPTIONS]\n\n  Check if the version is equal to the input\n\n  Check:\n  * `OK`: The version is the same as the input `--patroni-version`\n  * `CRITICAL`: otherwise.\n\n  Perfdata:\n  * `is_version_ok` is 1 if version is ok, 0 otherwise\n\nOptions:\n  --patroni-version TEXT  Patroni version to compare to  [required]\n  --help                  Show this message and exit.\n```\n\n### node_tl_has_changed\n\n```\nUsage: check_patroni node_tl_has_changed [OPTIONS]\n\n  Check if the timeline has changed.\n\n  Note: either a timeline or a state file must be provided for this service to\n  work.\n\n  Check:\n  * `OK`: The timeline is the same as last time (`--state_file`) or the inputted timeline (`--timeline`)\n  * `CRITICAL`: The tl is not the same.\n\n  Perfdata:\n  * `is_timeline_changed` is 1 if the tl has changed, 0 otherwise\n  * the timeline\n\nOptions:\n  --timeline TEXT        A timeline number to compare with.\n  -s, --state-file TEXT  A state file to store the last tl number into.\n  --save                 Set the current timeline number as the reference for\n                         future calls.\n  --help                 Show this message and exit.\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalibo%2Fcheck_patroni","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdalibo%2Fcheck_patroni","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalibo%2Fcheck_patroni/lists"}