demo-kratia commented on code in PR #14528:
URL: https://github.com/apache/druid/pull/14528#discussion_r1258950856
##########
docs/api-reference/service-status-api.md:
##########
@@ -23,154 +23,1002 @@ sidebar_label: Service status
~ under the License.
-->
-This document describes the API endpoints to retrieve service (process)
status, cluster information for Apache Druid
+
+This document describes the API endpoints to retrieve service (process)
status, cluster information for Apache Druid.
+
+In this document, `{domain}` is a placeholder for the server address of
deployment. For example, on the quickstart configuration, replace `{domain}`
with `http://localhost:8888`.
## Common
All processes support the following endpoints.
-### Process information
+### Get process information
+
+#### URL
+<code class="getAPI">GET</code> `/status`
+
+Retrieves the Druid version, loaded extensions, memory used, total memory, and
other useful information about the process.
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved process information*
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+---
+
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/status"
+```
+<!--HTTP-->
+```http
+GET /status HTTP/1.1
+Host: {domain}
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```json
+ {
+ "version": "26.0.0",
+ "modules": [
+ {
+ "name": "org.apache.druid.common.aws.AWSModule",
+ "artifact": "druid-aws-common",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.common.gcp.GcpModule",
+ "artifact": "druid-gcp-common",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.storage.hdfs.HdfsStorageDruidModule",
+ "artifact": "druid-hdfs-storage",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.indexing.kafka.KafkaIndexTaskModule",
+ "artifact": "druid-kafka-indexing-service",
+ "version": "26.0.0"
+ },
+ {
+ "name":
"org.apache.druid.query.aggregation.datasketches.theta.SketchModule",
+ "artifact": "druid-datasketches",
+ "version": "26.0.0"
+ },
+ {
+ "name":
"org.apache.druid.query.aggregation.datasketches.theta.oldapi.OldApiSketchModule",
+ "artifact": "druid-datasketches",
+ "version": "26.0.0"
+ },
+ {
+ "name":
"org.apache.druid.query.aggregation.datasketches.quantiles.DoublesSketchModule",
+ "artifact": "druid-datasketches",
+ "version": "26.0.0"
+ },
+ {
+ "name":
"org.apache.druid.query.aggregation.datasketches.tuple.ArrayOfDoublesSketchModule",
+ "artifact": "druid-datasketches",
+ "version": "26.0.0"
+ },
+ {
+ "name":
"org.apache.druid.query.aggregation.datasketches.hll.HllSketchModule",
+ "artifact": "druid-datasketches",
+ "version": "26.0.0"
+ },
+ {
+ "name":
"org.apache.druid.query.aggregation.datasketches.kll.KllSketchModule",
+ "artifact": "druid-datasketches",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.msq.guice.MSQExternalDataSourceModule",
+ "artifact": "druid-multi-stage-query",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.msq.guice.MSQIndexingModule",
+ "artifact": "druid-multi-stage-query",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.msq.guice.MSQDurableStorageModule",
+ "artifact": "druid-multi-stage-query",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.msq.guice.MSQServiceClientModule",
+ "artifact": "druid-multi-stage-query",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.msq.guice.MSQSqlModule",
+ "artifact": "druid-multi-stage-query",
+ "version": "26.0.0"
+ },
+ {
+ "name": "org.apache.druid.msq.guice.SqlTaskModule",
+ "artifact": "druid-multi-stage-query",
+ "version": "26.0.0"
+ }
+ ],
+ "memory": {
+ "maxMemory": 268435456,
+ "totalMemory": 268435456,
+ "freeMemory": 139060688,
+ "usedMemory": 129374768,
+ "directMemory": 134217728
+ }
+ }
+ ```
+</details>
+
+### Get process health
+
+#### URL
+
+<code class="getAPI">GET</code> `/status/health`
+
+Retrieves the health of the Druid service. If online, it will always return a
JSON object with the boolean `true` value, indicating that the service can
receive API calls. This endpoint is suitable for automated health checks.
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved process health*
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/status/health"
+```
+<!--HTTP-->
+```http
+GET /status/health HTTP/1.1
+Host: {domain}
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+<details>
+ <summary>Click to show sample response</summary>
+ ```json
+ true
+ ```
+</details>
+
+
+### Get configuration properties
+
+#### URL
+<code class="getAPI">GET</code> `/status/properties`
+
+Retrieves the current configuration properties of the process.
-`GET /status`
+#### Responses
-Returns the Druid version, loaded extensions, memory used, total memory, and
other useful information about the process.
+<!--DOCUSAURUS_CODE_TABS-->
-`GET /status/health`
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved process configuration properties*
+<!--END_DOCUSAURUS_CODE_TABS-->
-Always returns a boolean `true` value with a 200 OK response, useful for
automated health checks.
+#### Sample request
-`GET /status/properties`
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/status/properties"
+```
+<!--HTTP-->
+```http
+GET /status/properties HTTP/1.1
+Host: {domain}
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```json
+ {
+ "gopherProxySet": "false",
+ "awt.toolkit": "sun.lwawt.macosx.LWCToolkit",
+ "druid.monitoring.monitors":
"[\"org.apache.druid.java.util.metrics.JvmMonitor\"]",
+ "java.specification.version": "11",
+ "sun.cpu.isalist": "",
+ "druid.plaintextPort": "8888",
+ "sun.jnu.encoding": "UTF-8",
+ "druid.indexing.doubleStorage": "double",
+ "druid.metadata.storage.connector.port": "1527",
+ "java.class.path": "genericJavaClassPath",
+ "log4j.shutdownHookEnabled": "true",
+ "java.vm.vendor": "Homebrew",
+ "sun.arch.data.model": "64",
+ "druid.extensions.loadList": "[\"druid-hdfs-storage\",
\"druid-kafka-indexing-service\", \"druid-datasketches\",
\"druid-multi-stage-query\"]",
+ "java.vendor.url": "https://github.com/Homebrew/homebrew-core/issues";,
+ "druid.router.coordinatorServiceName": "druid/coordinator",
+ "user.timezone": "UTC",
+ "druid.global.http.eagerInitialization": "false",
+ "os.name": "Mac OS X",
+ "java.vm.specification.version": "11",
+ "sun.java.launcher": "SUN_STANDARD",
+ "user.country": "US",
+ "sun.boot.library.path":
"/opt/homebrew/Cellar/openjdk@11/11.0.19/libexec/openjdk.jdk/Contents/Home/lib",
+ "sun.java.command": "org.apache.druid.cli.Main server router",
+ "http.nonProxyHosts": "local|*.local|169.254/16|*.169.254/16",
+ "jdk.debug": "release",
+ "druid.metadata.storage.connector.host": "localhost",
+ "sun.cpu.endian": "little",
+ "druid.zk.paths.base": "/druid",
+ "user.home": "/Users/genericUser",
+ "user.language": "en",
+ "java.specification.vendor": "Oracle Corporation",
+ "java.version.date": "2023-04-18",
+ "java.home":
"/opt/homebrew/Cellar/openjdk@11/11.0.19/libexec/openjdk.jdk/Contents/Home",
+ "druid.service": "druid/router",
+ "druid.selectors.coordinator.serviceName": "druid/coordinator",
+ "druid.metadata.storage.connector.connectURI":
"jdbc:derby://localhost:1527/var/druid/metadata.db;create=true",
+ "file.separator": "/",
+ "druid.selectors.indexing.serviceName": "druid/overlord",
+ "java.vm.compressedOopsMode": "Zero based",
+ "druid.metadata.storage.type": "derby",
+ "line.separator": "\n",
+ "druid.log.path":
"/Users/genericUser/downloads/apache-druid-26.0.0/bin/../log",
+ "java.vm.specification.vendor": "Oracle Corporation",
+ "java.specification.name": "Java Platform API Specification",
+ "druid.indexer.logs.directory": "var/druid/indexing-logs",
+ "java.awt.graphicsenv": "sun.awt.CGraphicsEnvironment",
+ "druid.router.defaultBrokerServiceName": "druid/broker",
+ "druid.storage.storageDirectory": "var/druid/segments",
+ "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
+ "ftp.nonProxyHosts": "local|*.local|169.254/16|*.169.254/16",
+ "java.runtime.version": "11.0.19+0",
+ "user.name": "user",
+ "druid.indexer.logs.type": "file",
+ "druid.host": "localhost",
+ "log4j2.is.webapp": "false",
+ "path.separator": ":",
+ "os.version": "12.6.5",
+ "druid.lookup.enableLookupSyncOnStartup": "false",
+ "java.runtime.name": "OpenJDK Runtime Environment",
+ "druid.zk.service.host": "localhost",
+ "file.encoding": "UTF-8",
+ "druid.sql.planner.useGroupingSetForExactDistinct": "true",
+ "druid.router.managementProxy.enabled": "true",
+ "java.vm.name": "OpenJDK 64-Bit Server VM",
+ "java.vendor.version": "Homebrew",
+ "druid.startup.logging.logProperties": "true",
+ "java.vendor.url.bug": "https://github.com/Homebrew/homebrew-core/issues";,
+ "log4j.shutdownCallbackRegistry":
"org.apache.druid.common.config.Log4jShutdown",
+ "java.io.tmpdir": "var/tmp",
+ "druid.sql.enable": "true",
+ "druid.emitter.logging.logLevel": "info",
+ "java.version": "11.0.19",
+ "user.dir": "/Users/genericUser/Downloads/apache-druid-26.0.0",
+ "os.arch": "aarch64",
+ "java.vm.specification.name": "Java Virtual Machine Specification",
+ "druid.node.type": "router",
+ "java.awt.printerjob": "sun.lwawt.macosx.CPrinterJob",
+ "sun.os.patch.level": "unknown",
+ "java.util.logging.manager": "org.apache.logging.log4j.jul.LogManager",
+ "java.library.path":
"/Users/genericUser/Library/Java/Extensions:/Library/Java/Extensions:/Network/Library/Java/Extensions:/System/Library/Java/Extensions:/usr/lib/java:.",
+ "java.vendor": "Homebrew",
+ "java.vm.info": "mixed mode",
+ "java.vm.version": "11.0.19+0",
+ "druid.emitter": "noop",
+ "sun.io.unicode.encoding": "UnicodeBig",
+ "druid.storage.type": "local",
+ "druid.expressions.useStrictBooleans": "true",
+ "java.class.version": "55.0",
+ "socksNonProxyHosts": "local|*.local|169.254/16|*.169.254/16",
+ "druid.server.hiddenProperties":
"[\"druid.s3.accessKey\",\"druid.s3.secretKey\",\"druid.metadata.storage.connector.password\",
\"password\", \"key\", \"token\", \"pwd\"]"
+}
+```
+</details>
+
+
+### Get node discovery status and cluster integration confirmation
+
+#### URL
+<code class="getAPI">GET</code> `/status/selfDiscovered/status`
+
+Retrieves a JSON map of the form `{"selfDiscovered": true/false}`, indicating
whether the node has received a confirmation from the central node discovery
mechanism (currently ZooKeeper) of the Druid cluster that the node has been
added to the
+cluster.
+
+It is recommended to only consider a Druid node "healthy" or "ready" in
automated deployment/container management systems when it returns
`{"selfDiscovered": true}` from this endpoint. Nodes experiencing network
issues may become isolated and should not be considered "healthy." Nodes
utilizing Zookeeper segment discovery may be unusable until the Zookeeper
client is fully initialized and receives data from the Zookeeper cluster. The
presence of `{"selfDiscovered": true}` indicates that the node's Zookeeper
client has started receiving data, enabling timely discovery of segments and
other nodes.
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Node was successfully added to the cluster*
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/status/selfDiscovered/status"
+```
+<!--HTTP-->
+```http
+GET /status/selfDiscovered/status HTTP/1.1
+Host: {domain}
+```
-Returns the current configuration properties of the process.
+<!--END_DOCUSAURUS_CODE_TABS-->
-`GET /status/selfDiscovered/status`
+#### Sample response
+<details>
+ <summary>Click to show sample response</summary>
+ ```json
+ {
+ "selfDiscovered": true
+ }
+ ```
+</details>
-Returns a JSON map of the form `{"selfDiscovered": true/false}`, indicating
whether the node has received a confirmation
-from the central node discovery mechanism (currently ZooKeeper) of the Druid
cluster that the node has been added to the
-cluster. It is recommended to not consider a Druid node "healthy" or "ready"
in automated deployment/container
-management systems until it returns `{"selfDiscovered": true}` from this
endpoint. This is because a node may be
-isolated from the rest of the cluster due to network issues and it doesn't
make sense to consider nodes "healthy" in
-this case. Also, when nodes such as Brokers use ZooKeeper segment discovery
for building their view of the Druid cluster
-(as opposed to HTTP segment discovery), they may be unusable until the
ZooKeeper client is fully initialized and starts
-to receive data from the ZooKeeper cluster. `{"selfDiscovered": true}` is a
proxy event indicating that the ZooKeeper
-client on the node has started to receive data from the ZooKeeper cluster and
it's expected that all segments and other
-nodes will be discovered by this node timely from this point.
-`GET /status/selfDiscovered`
+### Get node self-discovery status
-Similar to `/status/selfDiscovered/status`, but returns 200 OK response with
empty body if the node has discovered itself
-and 503 SERVICE UNAVAILABLE if the node hasn't discovered itself yet. This
endpoint might be useful because some
-monitoring checks such as AWS load balancer health checks are not able to look
at the response body.
+#### URL
+<code class="getAPI">GET</code> `/status/selfDiscovered`
-## Master server
+Retrieves a status code to indicate if a node discovered itself within the
Druid cluster. This is similar to the `status/selfDiscovered/status` endpoint
but relies on HTTP status codes alone. This is useful for certain monitoring
checks such as AWS load balancer health checks that are unable to examine the
response body.
-### Coordinator
+#### Responses
-#### Leadership
+<!--DOCUSAURUS_CODE_TABS-->
-`GET /druid/coordinator/v1/leader`
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved node status*
-Returns the current leader Coordinator of the cluster.
+<!--503 SERVICE UNAVAILABLE-->
+<br/>
+*Unsuccessful node self-discovery*
+<!--END_DOCUSAURUS_CODE_TABS-->
-`GET /druid/coordinator/v1/isLeader`
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/status/selfDiscovered"
+```
+<!--HTTP-->
+```http
+GET /status/selfDiscovered HTTP/1.1
+Host: {domain}
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+A successful response to this endpoint results in an empty response body.
+
+## Coordinator
+
+### Get leader address
+
+#### URL
+
+<code class="getAPI">GET</code> `/druid/coordinator/v1/leader`
+
+Retrieves the address of the current leader Coordinator of the cluster.
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved leader Coordinator address*
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+---
+
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--cURL-->
+```shell
+curl "{domain}/druid/coordinator/v1/leader"
+```
+<!--HTTP-->
+```http
+GET /druid/coordinator/v1/leader HTTP/1.1
+Host: {domain}
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+<details>
+ <summary>Click to show sample response</summary>
+ ```json
+ http://localhost:8081
+ ```
+</details>
+
+### Get leader status
+
+#### URL
+<code class="getAPI">GET</code> `/druid/coordinator/v1/isLeader`
+
+Retrieves a JSON object with a `leader` key. The value can be `true` or
`false`, indicating if this server is the current leader Coordinator of the
cluster. This is suitable for use as a load balancer status check if you only
want the active leader to be considered in-service at the load balancer.
Review Comment:
I think with the /leader/ endpoint, there isn't a need to run it against all
coordinators since /leader/ will check all of them and /isLeader/ is for a
particular one.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
