{"id":18753353,"url":"https://github.com/pingidentity/status-servlet","last_synced_at":"2025-04-13T00:31:40.314Z","repository":{"id":45536533,"uuid":"51186710","full_name":"pingidentity/status-servlet","owner":"pingidentity","description":"A load balancer health check target for the PingData servers","archived":false,"fork":false,"pushed_at":"2023-04-17T14:43:21.000Z","size":141,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-26T18:57:21.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pingidentity.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}},"created_at":"2016-02-06T02:47:35.000Z","updated_at":"2023-04-17T14:43:01.000Z","dependencies_parsed_at":"2023-01-21T19:22:40.736Z","dependency_job_id":null,"html_url":"https://github.com/pingidentity/status-servlet","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fstatus-servlet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fstatus-servlet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fstatus-servlet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fstatus-servlet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pingidentity","download_url":"https://codeload.github.com/pingidentity/status-servlet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650590,"owners_count":21139670,"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-07T17:25:29.187Z","updated_at":"2025-04-13T00:31:39.264Z","avatar_url":"https://github.com/pingidentity.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# status-servlet [![Build Status](https://travis-ci.org/pingidentity/status-servlet.svg?branch=master)](https://travis-ci.org/pingidentity/status-servlet)\n\n:warning: | This project is no longer actively maintained. We encourage you instead to use the availability servlet introduced in the 7.3.0.0 release.\n:---: | :---\n\nThis is a status servlet extension for PingData server products like the Directory\nServer and Data Governance. It may be used as the health check target for\na layer 7 HTTP load balancer such as HAProxy or Amazon Elastic Load Balancer. \nUsing this status servlet can generally be considered a more reliable indicator\nof server availability than an arbitrary service path or '/', because it will\nonly return a success response if the server's services are in fact online and\navailable.\n\n## Usage\n\nRequest the servlet at the configured path. \nFor example, `https://server/status`. If the server's services are available, a\n200 OK will be returned. If the server is available but degraded, for example if\ndisk space if low, a 429 TOO MANY REQUESTS will be returned. Otherwise, a 503\nSERVICE UNAVAILABLE will be returned.\n\n```http\nGET /status HTTP/1.1\nAccept: application/json\nContent-Type: application/json; charset=utf-8\nHost: example.com\n\n\n\nHTTP/1.1 200 OK\nContent-Type: application/json\nDate: Sun, 05 Jun 2016 03:59:14 GMT\nTransfer-Encoding: chunked\n\n{\n    \"server\": \"available\",\n    \"loadBalancingAlgorithms\": [\n        {\n            \"available\": true, \n            \"name\": \"User Store LBA\", \n            \"numAvailableServers\": 2, \n            \"numDegradedServers\": 0, \n            \"numUnavailableServers\": 0\n        }\n    ], \n    \"servlets\": [\n        {\n            \"enabled\": true, \n            \"name\": \"SCIM2\"\n        }\n    ], \n    \"storeAdapters\": [\n        {\n            \"available\": true, \n            \"name\": \"UserStoreAdapter\"\n        }\n    ]\n}\n```\n\nFollowing is an example of the server being degraded due to having\na critical alarm condition:\n\n```http\nGET /status HTTP/1.1\nAccept: application/json\nContent-Type: application/json; charset=utf-8\nHost: example.com\n\n\n\nHTTP/1.1 429 TOO MANY REQUESTS\nContent-Type: application/json\nDate: Sun, 05 Jun 2016 03:59:14 GMT\nTransfer-Encoding: chunked\n\n{\n    \"server\": \"degraded\",\n    \"alertType\": [\n        \"alarm-critical\"\n    ]\n}\n```\n\nFollowing is an example of the server being unavailable due to having\nentered lockdown mode:\n\n```http\nGET /status HTTP/1.1\nAccept: application/json\nContent-Type: application/json; charset=utf-8\nHost: example.com\n\n\n\nHTTP/1.1 503 SERVICE UNAVAILABLE\nContent-Type: application/json\nDate: Sun, 05 Jun 2016 03:59:14 GMT\nTransfer-Encoding: chunked\n\n{\n    \"server\": \"unavailable\",\n    \"alertType\": [\n        \"entering-lockdown-mode\"\n    ]\n}\n```\n\nFollowing is an example of status based on an entry from the `cn=monitor` backend:\n\n```http\nGET /status HTTP/1.1\nAccept: application/json\nContent-Type: application/json; charset=utf-8\nHost: example.com\n\n\n\nHTTP/1.1 200 OK\nContent-Type: application/json\nDate: Fri, 18 May 2018 06:25:59 GMT\nTransfer-Encoding: chunked\n\n{\n    \"monitors\": [\n        {\n            \"available\": true,\n            \"name\": \"Consent Service Monitor\",\n            \"properties\": {\n                \"cn\": \"Consent Service Monitor\",\n                \"is-available\": \"true\",\n                \"num-failed-creates\": \"0\",\n                \"num-failed-deletes\": \"0\",\n                \"num-failed-reads\": \"1\",\n                \"num-failed-updates\": \"0\",\n                \"num-successful-creates\": \"1\",\n                \"num-successful-deletes\": \"1\",\n                \"num-successful-reads\": \"6\",\n                \"num-successful-updates\": \"1\",\n                \"objectClass\": [\n                    \"top\",\n                    \"ds-monitor-entry\",\n                    \"ds-consent-service-monitor-entry\",\n                    \"extensibleObject\"\n                ],\n                \"total-failed\": \"1\",\n                \"total-successful\": \"9\"\n            }\n        }\n    ],\n    \"server\": \"available\",\n    \"servlets\": [\n        {\n            \"enabled\": true,\n            \"name\": \"Consent\"\n        }\n    ]\n}\n```\n\n## Installation\n\nJava 7 or up is required.\n\nFirst, build the extension bundle by running `mvn package`. The extension bundle \nwill be saved as a zip file in the `target` directory.\n\nNext, install the extension bundle.\n\n```\nmanage-extension --install com.unboundid.ops.status-servlet-VERSION.zip\n```\n\nThen configure the extension, assign it to an HTTPS connection handler and \nrestart the connection handler.\n\nExample configuration for Directory Server:\n\n```\ndsconfig create-http-servlet-extension --extension-name Status \\\n  --type third-party --set \"description:Reports DS service availability\" \\\n  --set extension-class:com.unboundid.ops.StatusServletExtension\ndsconfig set-connection-handler-prop --handler-name \"HTTPS Connection Handler\" \\\n  --set enabled:false --add http-servlet-extension:Status\ndsconfig set-connection-handler-prop --handler-name \"HTTPS Connection Handler\" \\\n  --set enabled:true\n```\n\nExample configuration for Directory Server with Consent Service:\n\n```\ndsconfig create-http-servlet-extension --extension-name Status \\\n  --type third-party --set \"description:Reports DS service availability\" \\\n  --set extension-class:com.unboundid.ops.StatusServletExtension \\\n  --set extension-argument:path=/status \\\n  --set extension-argument:monitored-servlet=Consent \\\n  --set \"extension-argument:monitor=Consent Service Monitor:is-available:true\"\ndsconfig set-connection-handler-prop --handler-name \"HTTPS Connection Handler\" \\\n  --set enabled:false --add http-servlet-extension:Status\ndsconfig set-connection-handler-prop --handler-name \"HTTPS Connection Handler\" \\\n  --set enabled:true\n```\n\nExample configuration for Data Governance:\n\n```\ndsconfig create-http-servlet-extension --extension-name Status \\\n  --type third-party --set \"description:Reports Data Governance service availability\" \\\n  --set extension-class:com.unboundid.ops.StatusServletExtension \\\n  --set extension-argument:path=/status \\\n  --set extension-argument:monitored-servlet=SCIM2\ndsconfig set-connection-handler-prop --handler-name \"HTTPS Connection Handler\" \\\n  --set enabled:false --add http-servlet-extension:Status\ndsconfig set-connection-handler-prop --handler-name \"HTTPS Connection Handler\" \\\n  --set enabled:true\n```\n\nPlease see the following section for a description of the extension arguments.\n\n## Reference\n\n### Extension arguments\n\nThe `create-http-servlet-extension` command above takes the following \n`extension-argument` values:\n\n| Extension argument | Required | Description |\n| --- | --- | --- |\n| path | no | The servlet's path. Defaults to `/status`. |\n| monitored-servlet | no | The name of a servlet to monitor. This corresponds to an entry in the server's _HTTP Servlet Extensions_ configuration. If the servlet name ends with the word 'Servlet', this should be omitted. For example, 'SCIM2 Servlet' is specified as 'SCIM2'. This argument may be specified multiple times. If not specified, then no servlets are monitored. |\n| monitor | no | Criteria for determining availability using an entry in the `cn=monitor` backend. The format of this argument value is `\u003cMonitor entry name\u003e:\u003cAvailability attribute\u003e:\u003cAvailability value list\u003e`, where the availability attribute is the name of an attribute of the monitor entry that should be checked to determine availablility, and the availability value list is a comma-separated list of one or more values that positively indicate availability. Availability values are treated case-insensitively. For example, `Consent Service Monitor:is-available:true` means that the Consent Service Monitor entry in `cn=monitor` will be checked and marked as available if its `is-available` attribute has a value of `true`. |\n\nPlease be aware that every entity monitored via the `monitored-servlet` or \n`monitor` argument will be considered when determining overall server \navailability. For example, if a servlet referenced by the `monitored-servlet` \nargument does not exist or is disabled, then the status servlet will respond \nwith a 503 status code.\n\n### Response codes\n\n| Status code | Description |\n| --- | --- |\n| 200 OK | The server is operating normally, and all entities monitored by the status servlet are in an available state. |\n| 429 TOO MANY REQUESTS | The server is operating in a degraded state. |\n| 503 SERVICE UNAVAILABLE | Unavailable. One or more entities monitored by the status servlet is in an unavailable state. |\n\n### Response fields\n\nNote that the fields present in the response will vary depending on the product \ntype, the server state, and the status servlet configuration.\n\n| Field | Description |\n| --- | --- |\n| server | The server's operational status. Values are `unknown`, `available`, `degraded`, or `unavailable`. |\n| alertType | An array of any current alerts. |\n| servlets | An array consisting of any monitored servlets. |\n| monitors | An array consisting of any monitored entries from `cn=monitor`. |\n| loadBalancingAlgorithms | An array of load balancing algorithms. |\n| storeAdapters | An array of store adapters. Data Governance only. |\n\n## Support and reporting bugs\n\nThis is an unsupported example, but support will be provided on a best-effort basis.\n\nPlease report issues using the project's [issue tracker](https://github.com/pingidentity/status-servlet/issues). \nSee the [contribution guidelines](CONTRIBUTING.md) for more information.\n\n## License\n\nThis is licensed under the Apache License 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingidentity%2Fstatus-servlet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpingidentity%2Fstatus-servlet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingidentity%2Fstatus-servlet/lists"}