From 621645039396c2bc751a7afb25ed4df030d08fc0 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Wed, 28 Jun 2023 10:44:10 -0700
Subject: [PATCH 01/18] update code blocks and change toggle to click
---
docs/api-reference/service-status-api.md | 1089 +++++++++++++++++++++-
1 file changed, 1044 insertions(+), 45 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 614d216ca0dd..5650f248d94d 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -23,31 +23,351 @@ 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.
## Common
All processes support the following endpoints.
-### Process information
+### Get process information
-`GET /status`
+#### URL
+`GET` `/status`
Returns the Druid version, loaded extensions, memory used, total memory, and other useful information about the process.
-`GET /status/health`
+#### Responses
+
+
+
+
+
+*Successfully retrieved service information*
+
+
+#### Sample request
+
+
+
+
+```shell
+curl "{domain}/status"
+```
+
+```python
+import requests
+
+url = "{domain}/status"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```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
+ }
+ }
+ ```
+
+
+### Get process health
+
+#### URL
+`GET` `/status/health`
Always returns a boolean `true` value with a 200 OK response, useful for automated health checks.
-`GET /status/properties`
+#### Responses
+
+
+
+
+
+*Successfully retrieved service health*
+
+
+#### Sample request
+
+
+
+
+```shell
+curl "{domain}/status/health"
+```
+
+```python
+import requests
+
+url = "{domain}/status/health"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+
+#### Sample response
+
+ Click to show sample response
+ ```json
+ true
+ ```
+
+
+
+### Get configuration properties
+
+#### URL
+`GET` `/status/properties`
Returns the current configuration properties of the process.
-`GET /status/selfDiscovered/status`
+#### Responses
+
+
+
+
+
+*Successfully retrieved process configuration properties*
+
+
+#### Sample request
+
+
+
+
+```shell
+curl "{domain}/status/properties"
+```
+
+```python
+import requests
+
+url = "{domain}/status/properties"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```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\"]"
+}
+```
+
+
+
+### Get node discovery status and cluster integration confirmation
+
+#### URL
+`GET` `/status/selfDiscovered/status`
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
+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
@@ -56,50 +376,309 @@ to receive data from the ZooKeeper cluster. `{"selfDiscovered": true}` is a prox
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`
+#### Responses
+
+
+
+
+
+*Node was successfully added to the cluster*
+
+
+#### Sample request
-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
+
+
+
+```shell
+curl "{domain}/status/selfDiscovered/status"
+```
+
+```python
+import requests
+
+url = "{domain}/status/selfDiscovered/status"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+
+#### Sample response
+
+ Click to show sample response
+ ```json
+ {
+ "selfDiscovered": true
+ }
+ ```
+
+
+
+### Get node self-discovery status
+
+#### URL
+`GET` `/status/selfDiscovered`
+
+Similar to `/status/selfDiscovered/status`, but returns status codes. 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.
-## Master server
+#### Responses
+
+
+
+
+
+*Successfully retrieved node status*
+
+
+
+*Unsuccessful node self-discovery*
+
+
+#### Sample request
+
+
+
+
+```shell
+curl "{domain}/status/selfDiscovered"
+```
+
+```python
+import requests
+
+url = "{domain}/status/selfDiscovered"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+
+#### Sample response
+A successful response to this endpoint results in an empty response body.
+
-### Coordinator
-#### Leadership
+## Coordinator
-`GET /druid/coordinator/v1/leader`
+### Get leader coordinator
+
+#### URL
+
+`GET` `/druid/coordinator/v1/leader`
Returns the current leader Coordinator of the cluster.
-`GET /druid/coordinator/v1/isLeader`
+#### Responses
+
+
+
+
+
+*Successfully retrieved leader coordinator*
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/coordinator/v1/leader"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/coordinator/v1/leader"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+ ```json
+ http://localhost:8081
+ ```
+
+
+### Get leader status
+
+#### URL
+`GET` `/druid/coordinator/v1/isLeader`
Returns a JSON object with `leader` parameter, either true or false, indicating if this server is the current leader
Coordinator of the cluster. In addition, returns HTTP 200 if the server is the current leader and HTTP 404 if not.
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.
+#### Responses
+
+
+
+
+
+*Current server is the leader*
+
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/coordinator/v1/isLeader"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/coordinator/v1/isLeader"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+ ```json
+ {
+ "leader":true
+ }
+ ```
+
+
+
-### Overlord
+## Overlord
-#### Leadership
+### Get leader overlord
-`GET /druid/indexer/v1/leader`
+#### URL
+
+`GET` `/druid/indexer/v1/leader`
Returns the current leader Overlord of the cluster. If you have multiple Overlords, just one is leading at any given time. The others are on standby.
-`GET /druid/indexer/v1/isLeader`
+#### Responses
+
+
+
+
+
+*Current server is the leader*
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/indexer/v1/leader"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/indexer/v1/leader"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ http://localhost:8081
+ ```
+
+
+
+
+### Get leader status
+
+#### URL
+`GET` `/druid/indexer/v1/isLeader`
This returns a JSON object with field `leader`, either true or false. In addition, this call returns HTTP 200 if the
server is the current leader and HTTP 404 if not. 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.
-## Data server
+#### Responses
+
+
+
+
+
+*Current server is the leader*
+
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/indexer/v1/isLeader"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/indexer/v1/isLeader"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ {
+ "leader":true
+ }
+ ```
+
+
-### MiddleManager
+## MiddleManager
-`GET /druid/worker/v1/enabled`
+### Get state status
+
+#### URL
+
+`GET` `/druid/worker/v1/enabled`
Check whether a MiddleManager is in an enabled or disabled state. Returns JSON object keyed by the combined `druid.host`
and `druid.port` with the boolean state as the value.
@@ -107,8 +686,55 @@ and `druid.port` with the boolean state as the value.
```json
{"localhost:8091":true}
```
+#### Responses
+
+
+
+
+
+*Successfully retrieved MiddleManager state*
+
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/worker/v1/enabled"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/worker/v1/enabled"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
-`GET /druid/worker/v1/tasks`
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ {
+ "localhost:8091": true
+ }
+ ```
+
+
+### Get active tasks
+
+#### URL
+`GET` `/druid/worker/v1/tasks`
Retrieve a list of active tasks being run on MiddleManager. Returns JSON list of taskid strings. Normal usage should
prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one of it's task state specific variants instead.
@@ -117,60 +743,433 @@ prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one o
["index_wikiticker_2019-02-11T02:20:15.316Z"]
```
-`GET /druid/worker/v1/task/{taskid}/log`
+#### Responses
+
+
+
+
+
+*Successfully retrieved active tasks*
+
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/worker/v1/tasks"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/worker/v1/tasks"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ [
+ "index_parallel_wikipedia_mgchefio_2023-06-13T22:18:05.360Z"
+ ]
+ ```
+
+
+### Get task log
+
+#### URL
+`GET` `/druid/worker/v1/task/{taskid}/log`
Retrieve task log output stream by task id. Normal usage should prefer to use the `/druid/indexer/v1/task/{taskId}/log`
[Tasks API](./tasks-api.md) instead.
-`POST /druid/worker/v1/disable`
+#### Parameters
+* `taskid`: String
+ * The id value of the task. Required.
-Disable a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns JSON object
-keyed by the combined `druid.host` and `druid.port`:
+#### Responses
+
-```json
-{"localhost:8091":"disabled"}
+
+
+*Successfully retrieved task log*
+
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/worker/v1/task/{taskid}/log"
```
+
+```python
+import requests
-`POST /druid/worker/v1/enable`
+url = "{domain}/druid/worker/v1/task/{taskid}/log"
-Enable a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns JSON object
-keyed by the combined `druid.host` and `druid.port`:
+response = requests.get(url)
-```json
-{"localhost:8091":"enabled"}
+print(response.text)
```
+
-`POST /druid/worker/v1/task/{taskid}/shutdown`
+#### Sample response
+
+ Click to show sample response
+
+
+
+### Shutdown running task
+
+#### URL
+`POST` `/druid/worker/v1/task/{taskid}/shutdown`
Shutdown a running task by `taskid`. Normal usage should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
[Tasks API](./tasks-api.md) instead. Returns JSON:
-```json
-{"task":"index_kafka_wikiticker_f7011f8ffba384b_fpeclode"}
+#### Parameters
+* `taskid`: String
+ * The id value of the task. Required.
+
+#### Responses
+
+
+
+
+*Successfully shut down a task*
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/worker/v1/task/{taskid}/shutdown"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/worker/v1/task/{taskid}/shutdown"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ {
+ "task":"index_kafka_wikiticker_f7011f8ffba384b_fpeclode"
+ }
+ ```
+
+
+
+### Disable MiddleManager
+
+#### URL
+`POST` `/druid/worker/v1/disable`
+
+Disable a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns JSON object
+keyed by the combined `druid.host` and `druid.port`.
+
+#### Responses
+
+
+
+
+*Successfully disabled MiddleManager*
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/worker/v1/disable"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/worker/v1/disable"
+
+response = requests.get(url)
+
+print(response.text)
```
+
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ {
+ "localhost:8091":"disabled"
+ }
+ ```
+
+
+
+### Enable MiddleManager
+
+#### URL
+
+`POST` `/druid/worker/v1/enable`
+
+Enable a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns JSON object
+keyed by the combined `druid.host` and `druid.port`.
+
+#### Responses
+
+
+
+
+*Successfully enabled MiddleManager*
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/worker/v1/enable"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/worker/v1/enable"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ {
+ "localhost:8091":"enabled"
+ }
+ ```
+
+
## Historical
-### Segment loading
-`GET /druid/historical/v1/loadstatus`
+### Get segment load status
+
+#### URL
+
+`GET` `/druid/historical/v1/loadstatus`
Returns JSON of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all
segments in the local cache have been loaded. This can be used to know when a Historical process is ready
to be queried after a restart.
-`GET /druid/historical/v1/readiness`
+#### Responses
+
+
+
+
+*Successfully retrieved status*
+
+
+*Resource not found or request was sent to an incorrect node*
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/historical/v1/loadstatus"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/historical/v1/loadstatus"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+
+ ```json
+ {
+ "cacheInitialized": true
+ }
+ ```
+
+
+### Get segment readiness status
+
+#### URL
+`GET` `/druid/historical/v1/readiness`
+
+Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
+
+#### Responses
+
+
+
+
+*Segments in local cache successfully loaded*
+
+
+*Segments in local cache have not been loaded*
-Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, responses 200 OK if segments
-in the local cache have been loaded, and 503 SERVICE UNAVAILABLE, if they haven't.
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/historical/v1/readiness"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/historical/v1/readiness"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+A successful response to this endpoint results in an empty response body.
## Load Status
-`GET /druid/broker/v1/loadstatus`
+### Get Broker query load status
+
+#### URL
+
+`GET` `/druid/broker/v1/loadstatus`
Returns a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker process is ready to be queried after a restart.
-`GET /druid/broker/v1/readiness`
+#### Responses
+
+
+
+
+*Segments successfully loaded*
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/broker/v1/loadstatus"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/broker/v1/loadstatus"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
+
+#### Sample response
+
+ Click to show sample response
+ ```json
+ {
+ "inventoryInitialized": true
+ }
+ ```
+
+
+### Get Broker query readiness status
+
+#### URL
+`GET` `/druid/broker/v1/readiness`
+
+Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
+
+#### Responses
+
+
+
+
+*Segments successfully loaded*
+
+
+
+*Segments have not been loaded*
+
+
+
+#### Sample request
+
+
+
+```shell
+curl "{domain}/druid/broker/v1/readiness"
+```
+
+```python
+import requests
+
+url = "{domain}/druid/broker/v1/readiness"
+
+response = requests.get(url)
+
+print(response.text)
+```
+
-Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, responses 200 OK if its ready and otherwise 503 SERVICE UNAVAILABLE.
+#### Sample response
+A successful response to this endpoint results in an empty response body.
\ No newline at end of file
From edc9159d8cee75193597add0dc14d1ce4602cd02 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Thu, 29 Jun 2023 09:20:04 -0700
Subject: [PATCH 02/18] some updates
---
docs/api-reference/service-status-api.md | 110 ++++++++++-------------
1 file changed, 48 insertions(+), 62 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 5650f248d94d..619aedc06fa1 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -23,10 +23,6 @@ sidebar_label: Service status
~ under the License.
-->
-
This document describes the API endpoints to retrieve service (process) status, cluster information for Apache Druid.
@@ -39,10 +35,14 @@ All processes support the following endpoints.
### Get process information
#### URL
-`GET` `/status`
+`GET` `/status`
Returns the Druid version, loaded extensions, memory used, total memory, and other useful information about the process.
+#### Query parameter
+
+No query parameters.
+
#### Responses
@@ -60,15 +60,10 @@ Returns the Druid version, loaded extensions, memory used, total memory, and oth
```shell
curl "{domain}/status"
```
-
-```python
-import requests
-
-url = "{domain}/status"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /status HTTP/1.1
+Host: {domain}
```
@@ -176,9 +171,14 @@ print(response.text)
### Get process health
#### URL
+
`GET` `/status/health`
-Always returns a boolean `true` value with a 200 OK response, useful for automated health checks.
+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. It is useful for automated health checks.
+
+#### Query parameter
+
+No query parameters.
#### Responses
@@ -197,15 +197,10 @@ Always returns a boolean `true` value with a 200 OK response, useful for automat
```shell
curl "{domain}/status/health"
```
-
-```python
-import requests
-
-url = "{domain}/status/health"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /status/health HTTP/1.1
+Host: {domain}
```
@@ -226,6 +221,10 @@ print(response.text)
Returns the current configuration properties of the process.
+#### Query parameter
+
+No query parameters.
+
#### Responses
@@ -243,15 +242,10 @@ Returns the current configuration properties of the process.
```shell
curl "{domain}/status/properties"
```
-
-```python
-import requests
-
-url = "{domain}/status/properties"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /status/properties HTTP/1.1
+Host: {domain}
```
@@ -367,14 +361,11 @@ Returns a JSON map of the form `{"selfDiscovered": true/false}`, indicating whet
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.
+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.
+
+#### Query parameters
+
+No query parameters.
#### Responses
@@ -393,15 +384,10 @@ nodes will be discovered by this node timely from this point.
```shell
curl "{domain}/status/selfDiscovered/status"
```
-
-```python
-import requests
-
-url = "{domain}/status/selfDiscovered/status"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /status/selfDiscovered/status HTTP/1.1
+Host: {domain}
```
@@ -422,8 +408,11 @@ print(response.text)
#### URL
`GET` `/status/selfDiscovered`
-Similar to `/status/selfDiscovered/status`, but returns status codes. 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.
+Returns status codes 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 which are unable to examine the response body.
+
+#### Query parameters
+
+No query parameters.
#### Responses
@@ -446,15 +435,10 @@ monitoring checks such as AWS load balancer health checks are not able to look a
```shell
curl "{domain}/status/selfDiscovered"
```
-
-```python
-import requests
-
-url = "{domain}/status/selfDiscovered"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /status/selfDiscovered HTTP/1.1
+Host: {domain}
```
@@ -1172,4 +1156,6 @@ print(response.text)
#### Sample response
-A successful response to this endpoint results in an empty response body.
\ No newline at end of file
+A successful response to this endpoint results in an empty response body.
+
+
From 6451557532585fbe72c3a7ac535d556fc68459bb Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Fri, 30 Jun 2023 13:39:56 -0700
Subject: [PATCH 03/18] basic info, missing log
---
docs/api-reference/service-status-api.md | 373 ++++++++---------------
1 file changed, 124 insertions(+), 249 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 619aedc06fa1..d67e2791f84d 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -26,7 +26,7 @@ sidebar_label: Service status
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.
+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
@@ -39,10 +39,6 @@ All processes support the following endpoints.
Returns the Druid version, loaded extensions, memory used, total memory, and other useful information about the process.
-#### Query parameter
-
-No query parameters.
-
#### Responses
@@ -52,6 +48,8 @@ No query parameters.
*Successfully retrieved service information*
+---
+
#### Sample request
@@ -172,14 +170,10 @@ Host: {domain}
#### URL
-`GET` `/status/health`
+`GET` `/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. It is useful for automated health checks.
-#### Query parameter
-
-No query parameters.
-
#### Responses
@@ -217,14 +211,10 @@ Host: {domain}
### Get configuration properties
#### URL
-`GET` `/status/properties`
+`GET` `/status/properties`
Returns the current configuration properties of the process.
-#### Query parameter
-
-No query parameters.
-
#### Responses
@@ -355,18 +345,13 @@ Host: {domain}
### Get node discovery status and cluster integration confirmation
#### URL
-`GET` `/status/selfDiscovered/status`
+`GET` `/status/selfDiscovered/status`
-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
+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.
-#### Query parameters
-
-No query parameters.
-
#### Responses
@@ -406,13 +391,9 @@ Host: {domain}
### Get node self-discovery status
#### URL
-`GET` `/status/selfDiscovered`
+`GET` `/status/selfDiscovered`
-Returns status codes 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 which are unable to examine the response body.
-
-#### Query parameters
-
-No query parameters.
+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.
#### Responses
@@ -446,17 +427,15 @@ Host: {domain}
#### Sample response
A successful response to this endpoint results in an empty response body.
-
-
## Coordinator
### Get leader coordinator
#### URL
-`GET` `/druid/coordinator/v1/leader`
+`GET` `/druid/coordinator/v1/leader`
-Returns the current leader Coordinator of the cluster.
+Retrieves the address of the current leader Coordinator of the cluster.
#### Responses
@@ -467,6 +446,8 @@ Returns the current leader Coordinator of the cluster.
*Successfully retrieved leader coordinator*
+---
+
#### Sample request
@@ -474,15 +455,10 @@ Returns the current leader Coordinator of the cluster.
```shell
curl "{domain}/druid/coordinator/v1/leader"
```
-
-```python
-import requests
-
-url = "{domain}/druid/coordinator/v1/leader"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/coordinator/v1/leader HTTP/1.1
+Host: {domain}
```
@@ -497,12 +473,9 @@ print(response.text)
### Get leader status
#### URL
-`GET` `/druid/coordinator/v1/isLeader`
+`GET` `/druid/coordinator/v1/isLeader`
-Returns a JSON object with `leader` parameter, either true or false, indicating if this server is the current leader
-Coordinator of the cluster. In addition, returns HTTP 200 if the server is the current leader and HTTP 404 if not.
-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.
+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. In addition to the response object, it returns HTTP 200 if the server is the current leader and HTTP 404 if not. 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.
#### Responses
@@ -512,13 +485,14 @@ at the load balancer.
*Current server is the leader*
-
+---
+
#### Sample request
@@ -526,15 +500,10 @@ at the load balancer.
```shell
curl "{domain}/druid/coordinator/v1/isLeader"
```
-
-```python
-import requests
-
-url = "{domain}/druid/coordinator/v1/isLeader"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/coordinator/v1/isLeader HTTP/1.1
+Host: {domain}
```
@@ -543,7 +512,7 @@ print(response.text)
Click to show sample response
```json
{
- "leader":true
+ "leader": true
}
```
@@ -557,9 +526,9 @@ print(response.text)
#### URL
-`GET` `/druid/indexer/v1/leader`
+`GET` `/druid/indexer/v1/leader`
-Returns the current leader Overlord of the cluster. If you have multiple Overlords, just one is leading at any given time. The others are on standby.
+Retrieves the address of the current leader Overlord of the cluster. If you have multiple Overlords, just one is leading at any given time. The others are on standby.
#### Responses
@@ -571,6 +540,8 @@ Returns the current leader Overlord of the cluster. If you have multiple Overlor
+---
+
#### Sample request
@@ -578,15 +549,10 @@ Returns the current leader Overlord of the cluster. If you have multiple Overlor
```shell
curl "{domain}/druid/indexer/v1/leader"
```
-
-```python
-import requests
-
-url = "{domain}/druid/indexer/v1/leader"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/indexer/v1/leader HTTP/1.1
+Host: {domain}
```
@@ -604,11 +570,9 @@ print(response.text)
### Get leader status
#### URL
-`GET` `/druid/indexer/v1/isLeader`
+`GET` `/druid/indexer/v1/isLeader`
-This returns a JSON object with field `leader`, either true or false. In addition, this call returns HTTP 200 if the
-server is the current leader and HTTP 404 if not. 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.
+Retrieves a JSON object with a `leader` key. The value can be `true` or `false`, indicating if this server is the current leader Overlord of the cluster. In addition to the response object, it returns HTTP 200 if the server is the current leader and HTTP 404 if not. 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.
#### Responses
@@ -617,14 +581,14 @@ only want the active leader to be considered in-service at the load balancer.
*Current server is the leader*
-
-
+---
+
#### Sample request
@@ -632,15 +596,10 @@ only want the active leader to be considered in-service at the load balancer.
```shell
curl "{domain}/druid/indexer/v1/isLeader"
```
-
-```python
-import requests
-
-url = "{domain}/druid/indexer/v1/isLeader"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/indexer/v1/isLeader HTTP/1.1
+Host: {domain}
```
@@ -650,7 +609,7 @@ print(response.text)
```json
{
- "leader":true
+ "leader": true
}
```
@@ -662,14 +621,12 @@ print(response.text)
#### URL
-`GET` `/druid/worker/v1/enabled`
+`GET` `/druid/worker/v1/enabled`
-Check whether a MiddleManager is in an enabled or disabled state. Returns JSON object keyed by the combined `druid.host`
-and `druid.port` with the boolean state as the value.
+Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by the combined `druid.host` and `druid.port` with a boolean `true` or `false` state as the value.
+
+To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
-```json
-{"localhost:8091":true}
-```
#### Responses
@@ -678,13 +635,14 @@ and `druid.port` with the boolean state as the value.
*Successfully retrieved MiddleManager state*
-
+---
+
#### Sample request
@@ -692,15 +650,10 @@ and `druid.port` with the boolean state as the value.
```shell
curl "{domain}/druid/worker/v1/enabled"
```
-
-```python
-import requests
-
-url = "{domain}/druid/worker/v1/enabled"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/worker/v1/enabled HTTP/1.1
+Host: {domain}
```
@@ -718,14 +671,11 @@ print(response.text)
### Get active tasks
#### URL
-`GET` `/druid/worker/v1/tasks`
+`GET` `/druid/worker/v1/tasks`
-Retrieve a list of active tasks being run on MiddleManager. Returns JSON list of taskid strings. Normal usage should
-prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one of it's task state specific variants instead.
+Retrieves a list of active tasks being run on MiddleManager. Returns JSON list of task ID strings. Normal usage should prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one of it's task state specific variants instead.
-```json
-["index_wikiticker_2019-02-11T02:20:15.316Z"]
-```
+To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
#### Responses
@@ -734,14 +684,14 @@ prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one o
*Successfully retrieved active tasks*
-
-
+---
+
#### Sample request
@@ -749,15 +699,10 @@ prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one o
```shell
curl "{domain}/druid/worker/v1/tasks"
```
-
-```python
-import requests
-
-url = "{domain}/druid/worker/v1/tasks"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/worker/v1/enabled HTTP/1.1
+Host: {domain}
```
@@ -775,65 +720,18 @@ print(response.text)
### Get task log
#### URL
-`GET` `/druid/worker/v1/task/{taskid}/log`
+`GET` `/druid/worker/v1/task/{taskid}/log`
-Retrieve task log output stream by task id. Normal usage should prefer to use the `/druid/indexer/v1/task/{taskId}/log`
+Retrieves task log output stream by task ID. It is highly recommended that for normal usage, you should use the `/druid/indexer/v1/task/{taskId}/log`
[Tasks API](./tasks-api.md) instead.
-#### Parameters
-* `taskid`: String
- * The id value of the task. Required.
-
-#### Responses
-
-
-
-
-*Successfully retrieved task log*
-
-
-
-
-#### Sample request
-
-
-
-```shell
-curl "{domain}/druid/worker/v1/task/{taskid}/log"
-```
-
-```python
-import requests
-
-url = "{domain}/druid/worker/v1/task/{taskid}/log"
-
-response = requests.get(url)
-
-print(response.text)
-```
-
-
-#### Sample response
-
- Click to show sample response
-
-
-
-### Shutdown running task
+### Shut down running task
#### URL
`POST` `/druid/worker/v1/task/{taskid}/shutdown`
-Shutdown a running task by `taskid`. Normal usage should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
-[Tasks API](./tasks-api.md) instead. Returns JSON:
-
-#### Parameters
-* `taskid`: String
- * The id value of the task. Required.
+Shuts down a running task by `taskid`. For normal usage, you should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
+[Tasks API](./tasks-api.md) instead.
#### Responses
@@ -844,6 +742,8 @@ Shutdown a running task by `taskid`. Normal usage should prefer to use the `/dru
+---
+
#### Sample request
@@ -851,15 +751,10 @@ Shutdown a running task by `taskid`. Normal usage should prefer to use the `/dru
```shell
curl "{domain}/druid/worker/v1/task/{taskid}/shutdown"
```
-
-```python
-import requests
-
-url = "{domain}/druid/worker/v1/task/{taskid}/shutdown"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+POST /druid/worker/v1/task/index_parallel_wikipedia_auto_eglhheik_2023-06-27T21:05:23.603Z/shutdown HTTP/1.1
+Host: {domain}
```
@@ -878,11 +773,13 @@ print(response.text)
### Disable MiddleManager
#### URL
-`POST` `/druid/worker/v1/disable`
+`POST` `/druid/worker/v1/disable`
-Disable a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns JSON object
+Disables a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
+To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
+
#### Responses
@@ -899,15 +796,10 @@ keyed by the combined `druid.host` and `druid.port`.
```shell
curl "{domain}/druid/worker/v1/disable"
```
-
-```python
-import requests
-
-url = "{domain}/druid/worker/v1/disable"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+POST /druid/worker/v1/disable HTTP/1.1
+Host: {domain}
```
@@ -927,11 +819,13 @@ print(response.text)
#### URL
-`POST` `/druid/worker/v1/enable`
+`POST` `/druid/worker/v1/enable`
-Enable a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns JSON object
+Enables a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
+To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
+
#### Responses
@@ -948,15 +842,10 @@ keyed by the combined `druid.host` and `druid.port`.
```shell
curl "{domain}/druid/worker/v1/enable"
```
-
-```python
-import requests
-
-url = "{domain}/druid/worker/v1/enable"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+POST /druid/worker/v1/enable HTTP/1.1
+Host: {domain}
```
@@ -978,11 +867,11 @@ print(response.text)
#### URL
-`GET` `/druid/historical/v1/loadstatus`
+`GET` `/druid/historical/v1/loadstatus`
+
+Retrieves a JSON object of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded. This can be used to know when a Historical process is ready to be queried after a restart.
-Returns JSON of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all
-segments in the local cache have been loaded. This can be used to know when a Historical process is ready
-to be queried after a restart.
+To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8093`.
#### Responses
@@ -1003,15 +892,10 @@ to be queried after a restart.
```shell
curl "{domain}/druid/historical/v1/loadstatus"
```
-
-```python
-import requests
-
-url = "{domain}/druid/historical/v1/loadstatus"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/historical/v1/loadstatus HTTP/1.1
+Host: {domain}
```
@@ -1029,9 +913,11 @@ print(response.text)
### Get segment readiness status
#### URL
-`GET` `/druid/historical/v1/readiness`
+`GET` `/druid/historical/v1/readiness`
+
+Retrieves a status code to indicate if all segments in the local cache have been loaded. Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
-Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
+To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8093`.
#### Responses
@@ -1052,31 +938,27 @@ Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with
```shell
curl "{domain}/druid/historical/v1/readiness"
```
-
-```python
-import requests
-
-url = "{domain}/druid/historical/v1/readiness"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/historical/v1/readiness HTTP/1.1
+Host: {domain}
```
#### Sample response
A successful response to this endpoint results in an empty response body.
-
## Load Status
### Get Broker query load status
#### URL
-`GET` `/druid/broker/v1/loadstatus`
+`GET` `/druid/broker/v1/loadstatus`
+
+Retrieves a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker process is ready to be queried after a restart.
-Returns a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker process is ready to be queried after a restart.
+To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8092`.
#### Responses
@@ -1094,15 +976,10 @@ Returns a flag indicating if the Broker knows about all segments in the cluster.
```shell
curl "{domain}/druid/broker/v1/loadstatus"
```
-
-```python
-import requests
-
-url = "{domain}/druid/broker/v1/loadstatus"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/broker/v1/loadstatus HTTP/1.1
+Host: {domain}
```
@@ -1119,9 +996,12 @@ print(response.text)
### Get Broker query readiness status
#### URL
-`GET` `/druid/broker/v1/readiness`
-Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
+`GET` `/druid/broker/v1/readiness`
+
+Retrieves a status code indicating if the Broker knows about all segments in the cluster and is ready to be queried after a restart. Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
+
+To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8092`.
#### Responses
@@ -1143,15 +1023,10 @@ Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it re
```shell
curl "{domain}/druid/broker/v1/readiness"
```
-
-```python
-import requests
-
-url = "{domain}/druid/broker/v1/readiness"
-
-response = requests.get(url)
-
-print(response.text)
+
+```http
+GET /druid/broker/v1/readiness HTTP/1.1
+Host: {domain}
```
From 8cce18be4db44bb4113b188941d8c2280d20e701 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Wed, 5 Jul 2023 12:09:09 -0700
Subject: [PATCH 04/18] Fix some errors, update description
---
docs/api-reference/service-status-api.md | 50 +++++++++---------------
1 file changed, 19 insertions(+), 31 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index d67e2791f84d..da0681210a71 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -37,7 +37,7 @@ All processes support the following endpoints.
#### URL
`GET` `/status`
-Returns the Druid version, loaded extensions, memory used, total memory, and other useful information about the process.
+Retrieves the Druid version, loaded extensions, memory used, total memory, and other useful information about the process.
#### Responses
@@ -45,7 +45,7 @@ Returns the Druid version, loaded extensions, memory used, total memory, and oth
-*Successfully retrieved service information*
+*Successfully retrieved process information*
---
@@ -172,7 +172,7 @@ Host: {domain}
`GET` `/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. It is useful for automated health checks.
+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
@@ -180,7 +180,7 @@ Retrieves the health of the Druid service. If online, it will always return a JS
-*Successfully retrieved service health*
+*Successfully retrieved process health*
#### Sample request
@@ -213,7 +213,7 @@ Host: {domain}
#### URL
`GET` `/status/properties`
-Returns the current configuration properties of the process.
+Retrieves the current configuration properties of the process.
#### Responses
@@ -429,7 +429,7 @@ A successful response to this endpoint results in an empty response body.
## Coordinator
-### Get leader coordinator
+### Get leader address
#### URL
@@ -443,7 +443,7 @@ Retrieves the address of the current leader Coordinator of the cluster.
-*Successfully retrieved leader coordinator*
+*Successfully retrieved leader Coordinator address*
---
@@ -475,7 +475,7 @@ Host: {domain}
#### URL
`GET` `/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. In addition to the response object, it returns HTTP 200 if the server is the current leader and HTTP 404 if not. 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.
+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.
#### Responses
@@ -522,13 +522,13 @@ Host: {domain}
## Overlord
-### Get leader overlord
+### Get leader address
#### URL
`GET` `/druid/indexer/v1/leader`
-Retrieves the address of the current leader Overlord of the cluster. If you have multiple Overlords, just one is leading at any given time. The others are on standby.
+Retrieves the address of the current leader Overlord of the cluster. In a cluster of multiple Overlords, only one Overlord assumes the leading role, while the remaining Overlords remain on standby.
#### Responses
@@ -536,8 +536,7 @@ Retrieves the address of the current leader Overlord of the cluster. If you have
-*Current server is the leader*
-
+*Successfully retrieved leader Overlord address*
---
@@ -572,7 +571,7 @@ Host: {domain}
#### URL
`GET` `/druid/indexer/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 Overlord of the cluster. In addition to the response object, it returns HTTP 200 if the server is the current leader and HTTP 404 if not. 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.
+Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord 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.
#### Responses
@@ -635,10 +634,6 @@ To use this endpoint, `{domain}` should be the address of the MiddleManager serv
*Successfully retrieved MiddleManager state*
-
---
@@ -684,10 +679,6 @@ To use this endpoint, `{domain}` should be the address of the MiddleManager serv
*Successfully retrieved active tasks*
-
---
@@ -701,7 +692,7 @@ curl "{domain}/druid/worker/v1/tasks"
```
```http
-GET /druid/worker/v1/enabled HTTP/1.1
+GET /druid/worker/v1/tasks HTTP/1.1
Host: {domain}
```
@@ -722,7 +713,7 @@ Host: {domain}
#### URL
`GET` `/druid/worker/v1/task/{taskid}/log`
-Retrieves task log output stream by task ID. It is highly recommended that for normal usage, you should use the `/druid/indexer/v1/task/{taskId}/log`
+Retrieves task log output stream by task ID. It is strongly advised that, for normal usage, you should use the `/druid/indexer/v1/task/{taskId}/log`
[Tasks API](./tasks-api.md) instead.
### Shut down running task
@@ -730,7 +721,7 @@ Retrieves task log output stream by task ID. It is highly recommended that for n
#### URL
`POST` `/druid/worker/v1/task/{taskid}/shutdown`
-Shuts down a running task by `taskid`. For normal usage, you should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
+Shuts down a running task by ID. For normal usage, you should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
[Tasks API](./tasks-api.md) instead.
#### Responses
@@ -749,11 +740,11 @@ Shuts down a running task by `taskid`. For normal usage, you should prefer to us
```shell
-curl "{domain}/druid/worker/v1/task/{taskid}/shutdown"
+curl "{domain}/druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown"
```
```http
-POST /druid/worker/v1/task/index_parallel_wikipedia_auto_eglhheik_2023-06-27T21:05:23.603Z/shutdown HTTP/1.1
+POST /druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown HTTP/1.1
Host: {domain}
```
@@ -879,9 +870,6 @@ To use this endpoint, `{domain}` should be the address of the Historical service
*Successfully retrieved status*
-
-
-*Resource not found or request was sent to an incorrect node*
@@ -910,7 +898,7 @@ Host: {domain}
```
-### Get segment readiness status
+### Get segment readiness
#### URL
`GET` `/druid/historical/v1/readiness`
@@ -993,7 +981,7 @@ Host: {domain}
```
-### Get Broker query readiness status
+### Get Broker query readiness
#### URL
From ce16f3243d5d49db8c219209a5865b0cfb4a8e91 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Wed, 5 Jul 2023 12:29:20 -0700
Subject: [PATCH 05/18] Apply styling to REST verb
---
docs/api-reference/service-status-api.md | 38 ++++++++++++------------
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index da0681210a71..a542ba56bb64 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -35,7 +35,7 @@ All processes support the following endpoints.
### Get process information
#### URL
-`GET` `/status`
+GET `/status`
Retrieves the Druid version, loaded extensions, memory used, total memory, and other useful information about the process.
@@ -170,7 +170,7 @@ Host: {domain}
#### URL
-`GET` `/status/health`
+GET `/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.
@@ -211,7 +211,7 @@ Host: {domain}
### Get configuration properties
#### URL
-`GET` `/status/properties`
+GET `/status/properties`
Retrieves the current configuration properties of the process.
@@ -345,7 +345,7 @@ Host: {domain}
### Get node discovery status and cluster integration confirmation
#### URL
-`GET` `/status/selfDiscovered/status`
+GET `/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.
@@ -391,7 +391,7 @@ Host: {domain}
### Get node self-discovery status
#### URL
-`GET` `/status/selfDiscovered`
+GET `/status/selfDiscovered`
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.
@@ -433,7 +433,7 @@ A successful response to this endpoint results in an empty response body.
#### URL
-`GET` `/druid/coordinator/v1/leader`
+GET `/druid/coordinator/v1/leader`
Retrieves the address of the current leader Coordinator of the cluster.
@@ -473,7 +473,7 @@ Host: {domain}
### Get leader status
#### URL
-`GET` `/druid/coordinator/v1/isLeader`
+GET `/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.
@@ -526,7 +526,7 @@ Host: {domain}
#### URL
-`GET` `/druid/indexer/v1/leader`
+GET `/druid/indexer/v1/leader`
Retrieves the address of the current leader Overlord of the cluster. In a cluster of multiple Overlords, only one Overlord assumes the leading role, while the remaining Overlords remain on standby.
@@ -569,7 +569,7 @@ Host: {domain}
### Get leader status
#### URL
-`GET` `/druid/indexer/v1/isLeader`
+GET `/druid/indexer/v1/isLeader`
Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord 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.
@@ -620,7 +620,7 @@ Host: {domain}
#### URL
-`GET` `/druid/worker/v1/enabled`
+GET `/druid/worker/v1/enabled`
Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by the combined `druid.host` and `druid.port` with a boolean `true` or `false` state as the value.
@@ -666,7 +666,7 @@ Host: {domain}
### Get active tasks
#### URL
-`GET` `/druid/worker/v1/tasks`
+GET `/druid/worker/v1/tasks`
Retrieves a list of active tasks being run on MiddleManager. Returns JSON list of task ID strings. Normal usage should prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one of it's task state specific variants instead.
@@ -711,7 +711,7 @@ Host: {domain}
### Get task log
#### URL
-`GET` `/druid/worker/v1/task/{taskid}/log`
+GET `/druid/worker/v1/task/{taskid}/log`
Retrieves task log output stream by task ID. It is strongly advised that, for normal usage, you should use the `/druid/indexer/v1/task/{taskId}/log`
[Tasks API](./tasks-api.md) instead.
@@ -719,7 +719,7 @@ Retrieves task log output stream by task ID. It is strongly advised that, for no
### Shut down running task
#### URL
-`POST` `/druid/worker/v1/task/{taskid}/shutdown`
+POST `/druid/worker/v1/task/{taskid}/shutdown`
Shuts down a running task by ID. For normal usage, you should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
[Tasks API](./tasks-api.md) instead.
@@ -764,7 +764,7 @@ Host: {domain}
### Disable MiddleManager
#### URL
-`POST` `/druid/worker/v1/disable`
+POST `/druid/worker/v1/disable`
Disables a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
@@ -810,7 +810,7 @@ Host: {domain}
#### URL
-`POST` `/druid/worker/v1/enable`
+POST `/druid/worker/v1/enable`
Enables a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
@@ -858,7 +858,7 @@ Host: {domain}
#### URL
-`GET` `/druid/historical/v1/loadstatus`
+GET `/druid/historical/v1/loadstatus`
Retrieves a JSON object of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded. This can be used to know when a Historical process is ready to be queried after a restart.
@@ -901,7 +901,7 @@ Host: {domain}
### Get segment readiness
#### URL
-`GET` `/druid/historical/v1/readiness`
+GET `/druid/historical/v1/readiness`
Retrieves a status code to indicate if all segments in the local cache have been loaded. Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
@@ -942,7 +942,7 @@ A successful response to this endpoint results in an empty response body.
#### URL
-`GET` `/druid/broker/v1/loadstatus`
+GET `/druid/broker/v1/loadstatus`
Retrieves a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker process is ready to be queried after a restart.
@@ -985,7 +985,7 @@ Host: {domain}
#### URL
-`GET` `/druid/broker/v1/readiness`
+GET `/druid/broker/v1/readiness`
Retrieves a status code indicating if the Broker knows about all segments in the cluster and is ready to be queried after a restart. Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
From be0669d6c0c47788a1c605e69f21e9b5686cd165 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Mon, 10 Jul 2023 15:15:25 -0700
Subject: [PATCH 06/18] light incorp of feedback
---
docs/api-reference/service-status-api.md | 63 +++++++++++++++---------
1 file changed, 39 insertions(+), 24 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index a542ba56bb64..2ddc2eefd8de 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -24,20 +24,31 @@ sidebar_label: Service status
-->
-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 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.
+All services support the following endpoints.
-### Get process information
+Each endpoint can be used with the ports for each type of service. The following table contains port addresses for a local configuration:
+
+|Service|Port address|
+| ----------- | ----------- |
+| Coordinator|8081|
+| Overlord |8081|
+| Router |8888|
+| Broker |8082|
+| Historical|8083|
+| MiddleManager|8091|
+
+### Get service information
#### URL
GET `/status`
-Retrieves the Druid version, loaded extensions, memory used, total memory, and other useful information about the process.
+Retrieves the Druid version, loaded extensions, memory used, total memory, and other useful information about the individual service.
#### Responses
@@ -45,7 +56,7 @@ Retrieves the Druid version, loaded extensions, memory used, total memory, and o
-*Successfully retrieved process information*
+*Successfully retrieved service information*
---
@@ -56,12 +67,12 @@ Retrieves the Druid version, loaded extensions, memory used, total memory, and o
```shell
-curl "{domain}/status"
+curl "{coordinator_domain}/status"
```
```http
GET /status HTTP/1.1
-Host: {domain}
+Host: {coordinator_domain}
```
@@ -166,13 +177,13 @@ Host: {domain}
```
-### Get process health
+### Get service health
#### URL
GET `/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.
+Retrieves the health of the individual Druid service. If online, it will always return a boolean `true` value, indicating that the service can receive API calls. This endpoint is suitable for automated health checks.
#### Responses
@@ -180,7 +191,7 @@ Retrieves the health of the Druid service. If online, it will always return a JS
-*Successfully retrieved process health*
+*Successfully retrieved service health*
#### Sample request
@@ -189,12 +200,12 @@ Retrieves the health of the Druid service. If online, it will always return a JS
```shell
-curl "{domain}/status/health"
+curl "{router_domain}/status/health"
```
```http
GET /status/health HTTP/1.1
-Host: {domain}
+Host: {router_domain}
```
@@ -213,7 +224,7 @@ Host: {domain}
#### URL
GET `/status/properties`
-Retrieves the current configuration properties of the process.
+Retrieves the current configuration properties of the individual service queried.
#### Responses
@@ -221,7 +232,7 @@ Retrieves the current configuration properties of the process.
-*Successfully retrieved process configuration properties*
+*Successfully retrieved service configuration properties*
#### Sample request
@@ -230,12 +241,12 @@ Retrieves the current configuration properties of the process.
```shell
-curl "{domain}/status/properties"
+curl "{coordinator_domain}/status/properties"
```
```http
GET /status/properties HTTP/1.1
-Host: {domain}
+Host: {coordinator_domain}
```
@@ -350,7 +361,8 @@ Host: {domain}
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.
+Only consider a Druid node "healthy" or "ready" in automated deployment/container management systems when this endpoint returns `{"selfDiscovered": true}`. Nodes experiencing network issues may become isolated and are not healthy.
+For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered": true}` indicates that the node's Zookeeper client has started receiving data from the Zookeeper cluster, enabling timely discovery of segments and other nodes.
#### Responses
@@ -367,12 +379,12 @@ It is recommended to only consider a Druid node "healthy" or "ready" in automate
```shell
-curl "{domain}/status/selfDiscovered/status"
+curl "{router_domain}/status/selfDiscovered/status"
```
```http
GET /status/selfDiscovered/status HTTP/1.1
-Host: {domain}
+Host: {router_domain}
```
@@ -393,7 +405,8 @@ Host: {domain}
#### URL
GET `/status/selfDiscovered`
-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.
+Returns an HTTP status code to indicate node discovery within the Druid cluster. This endpoint is similar to the `status/selfDiscovered/status` endpoint, but relies on HTTP status codes alone.
+Use this endpoint for monitoring checks that are unable to examine the response body. For example, AWS load balancer health checks.
#### Responses
@@ -414,12 +427,12 @@ Retrieves a status code to indicate if a node discovered itself within the Druid
```shell
-curl "{domain}/status/selfDiscovered"
+curl "{router_domain}/status/selfDiscovered"
```
```http
GET /status/selfDiscovered HTTP/1.1
-Host: {domain}
+Host: {router_domain}
```
@@ -475,7 +488,9 @@ Host: {domain}
#### URL
GET `/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.
+Retrieves a JSON object with a `leader` key. Returns `true` if this server is the current leader Coordinator of the cluster. To get the individual address of the leader Coordinator node, see the [leader endpoint](#get-leader-address).
+
+Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
#### Responses
@@ -944,7 +959,7 @@ A successful response to this endpoint results in an empty response body.
GET `/druid/broker/v1/loadstatus`
-Retrieves a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker process is ready to be queried after a restart.
+Retrieves a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker service is ready to be queried after a restart.
To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8092`.
From 64458e33a81574804b2ed143c9dfb26a0a646fa8 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Tue, 11 Jul 2023 12:38:39 -0700
Subject: [PATCH 07/18] Update {domain} to explicit port and IP
---
docs/api-reference/service-status-api.md | 113 +++++++++++------------
1 file changed, 55 insertions(+), 58 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 2ddc2eefd8de..b0401fd2bf8b 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -26,7 +26,7 @@ sidebar_label: Service status
This document describes the API endpoints to retrieve service 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`.
+In this document, `http://:` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://:` with `http://localhost:8888`.
## Common
@@ -50,6 +50,8 @@ Each endpoint can be used with the ports for each type of service. The followin
Retrieves the Druid version, loaded extensions, memory used, total memory, and other useful information about the individual service.
+To retrieve the service information of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+
#### Responses
@@ -67,12 +69,12 @@ Retrieves the Druid version, loaded extensions, memory used, total memory, and o
```shell
-curl "{coordinator_domain}/status"
+curl "http://:/status"
```
```http
GET /status HTTP/1.1
-Host: {coordinator_domain}
+Host: http://:
```
@@ -185,6 +187,8 @@ Host: {coordinator_domain}
Retrieves the health of the individual Druid service. If online, it will always return a boolean `true` value, indicating that the service can receive API calls. This endpoint is suitable for automated health checks.
+To retrieve the service health of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+
#### Responses
@@ -200,12 +204,12 @@ Retrieves the health of the individual Druid service. If online, it will always
```shell
-curl "{router_domain}/status/health"
+curl "http://:/status/health"
```
```http
GET /status/health HTTP/1.1
-Host: {router_domain}
+Host: http://:
```
@@ -226,6 +230,8 @@ Host: {router_domain}
Retrieves the current configuration properties of the individual service queried.
+To retrieve the service configuration property of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+
#### Responses
@@ -241,12 +247,12 @@ Retrieves the current configuration properties of the individual service queried
```shell
-curl "{coordinator_domain}/status/properties"
+curl "http://:/status/properties"
```
```http
GET /status/properties HTTP/1.1
-Host: {coordinator_domain}
+Host: http://:
```
@@ -257,6 +263,7 @@ Host: {coordinator_domain}
```json
{
+{
"gopherProxySet": "false",
"awt.toolkit": "sun.lwawt.macosx.LWCToolkit",
"druid.monitoring.monitors": "[\"org.apache.druid.java.util.metrics.JvmMonitor\"]",
@@ -266,7 +273,7 @@ Host: {coordinator_domain}
"sun.jnu.encoding": "UTF-8",
"druid.indexing.doubleStorage": "double",
"druid.metadata.storage.connector.port": "1527",
- "java.class.path": "genericJavaClassPath",
+ "java.class.path": "/Users/genericUserPath",
"log4j.shutdownHookEnabled": "true",
"java.vm.vendor": "Homebrew",
"sun.arch.data.model": "64",
@@ -299,7 +306,7 @@ Host: {coordinator_domain}
"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",
+ "druid.log.path": "/Users/genericUserPath",
"java.vm.specification.vendor": "Oracle Corporation",
"java.specification.name": "Java Platform API Specification",
"druid.indexer.logs.directory": "var/druid/indexing-logs",
@@ -309,7 +316,7 @@ Host: {coordinator_domain}
"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",
+ "user.name": "genericUser",
"druid.indexer.logs.type": "file",
"druid.host": "localhost",
"log4j2.is.webapp": "false",
@@ -337,7 +344,7 @@ Host: {coordinator_domain}
"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.library.path": "/Users/genericUserPath",
"java.vendor": "Homebrew",
"java.vm.info": "mixed mode",
"java.vm.version": "11.0.19+0",
@@ -364,6 +371,8 @@ cluster.
Only consider a Druid node "healthy" or "ready" in automated deployment/container management systems when this endpoint returns `{"selfDiscovered": true}`. Nodes experiencing network issues may become isolated and are not healthy.
For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered": true}` indicates that the node's Zookeeper client has started receiving data from the Zookeeper cluster, enabling timely discovery of segments and other nodes.
+To retrieve the discovery status of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+
#### Responses
@@ -408,6 +417,8 @@ Host: {router_domain}
Returns an HTTP status code to indicate node discovery within the Druid cluster. This endpoint is similar to the `status/selfDiscovered/status` endpoint, but relies on HTTP status codes alone.
Use this endpoint for monitoring checks that are unable to examine the response body. For example, AWS load balancer health checks.
+To retrieve the self-discovery status of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+
#### Responses
@@ -442,7 +453,7 @@ A successful response to this endpoint results in an empty response body.
## Coordinator
-### Get leader address
+### Get Coordinator leader address
#### URL
@@ -466,12 +477,12 @@ Retrieves the address of the current leader Coordinator of the cluster.
```shell
-curl "{domain}/druid/coordinator/v1/leader"
+curl "http://:/druid/coordinator/v1/leader"
```
```http
GET /druid/coordinator/v1/leader HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -483,12 +494,12 @@ Host: {domain}
```
-### Get leader status
+### Get Coordinator leader status
#### URL
GET `/druid/coordinator/v1/isLeader`
-Retrieves a JSON object with a `leader` key. Returns `true` if this server is the current leader Coordinator of the cluster. To get the individual address of the leader Coordinator node, see the [leader endpoint](#get-leader-address).
+Retrieves a JSON object with a `leader` key. Returns `true` if this server is the current leader Coordinator of the cluster. To get the individual address of the leader Coordinator node, see the [leader endpoint](#get-coordinator-leader-address).
Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
@@ -513,12 +524,12 @@ Use this endpoint as a load balancer status check when you only want the active
```shell
-curl "{domain}/druid/coordinator/v1/isLeader"
+curl "http://:/druid/coordinator/v1/isLeader"
```
```http
GET /druid/coordinator/v1/isLeader HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -537,7 +548,7 @@ Host: {domain}
## Overlord
-### Get leader address
+### Get Overlord leader address
#### URL
@@ -561,12 +572,12 @@ Retrieves the address of the current leader Overlord of the cluster. In a cluste
```shell
-curl "{domain}/druid/indexer/v1/leader"
+curl "http://:/druid/indexer/v1/leader"
```
```http
GET /druid/indexer/v1/leader HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -581,13 +592,15 @@ Host: {domain}
-### Get leader status
+### Get Overlord leader status
#### URL
GET `/druid/indexer/v1/isLeader`
Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord 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.
+To get the individual address of the leader Overlord node, see the [leader endpoint](#get-overlord-leader-address).
+
#### Responses
@@ -608,12 +621,12 @@ Retrieves a JSON object with a `leader` property. The value can be `true` or `fa
```shell
-curl "{domain}/druid/indexer/v1/isLeader"
+curl "http://:/druid/indexer/v1/isLeader"
```
```http
GET /druid/indexer/v1/isLeader HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -639,8 +652,6 @@ Host: {domain}
Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by the combined `druid.host` and `druid.port` with a boolean `true` or `false` state as the value.
-To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
-
#### Responses
@@ -658,12 +669,12 @@ To use this endpoint, `{domain}` should be the address of the MiddleManager serv
```shell
-curl "{domain}/druid/worker/v1/enabled"
+curl "http://:/druid/worker/v1/enabled"
```
```http
GET /druid/worker/v1/enabled HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -685,8 +696,6 @@ Host: {domain}
Retrieves a list of active tasks being run on MiddleManager. Returns JSON list of task ID strings. Normal usage should prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one of it's task state specific variants instead.
-To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
-
#### Responses
@@ -703,12 +712,12 @@ To use this endpoint, `{domain}` should be the address of the MiddleManager serv
```shell
-curl "{domain}/druid/worker/v1/tasks"
+curl "http://:/druid/worker/v1/tasks"
```
```http
GET /druid/worker/v1/tasks HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -755,12 +764,12 @@ Shuts down a running task by ID. For normal usage, you should prefer to use the
```shell
-curl "{domain}/druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown"
+curl "http://:/druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown"
```
```http
POST /druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -784,8 +793,6 @@ Host: {domain}
Disables a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
-To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
-
#### Responses
@@ -800,12 +807,12 @@ To use this endpoint, `{domain}` should be the address of the MiddleManager serv
```shell
-curl "{domain}/druid/worker/v1/disable"
+curl "http://:/druid/worker/v1/disable"
```
```http
POST /druid/worker/v1/disable HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -830,8 +837,6 @@ Host: {domain}
Enables a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
-To use this endpoint, `{domain}` should be the address of the MiddleManager service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8091`.
-
#### Responses
@@ -846,12 +851,12 @@ To use this endpoint, `{domain}` should be the address of the MiddleManager serv
```shell
-curl "{domain}/druid/worker/v1/enable"
+curl "http://:/druid/worker/v1/enable"
```
```http
POST /druid/worker/v1/enable HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -877,8 +882,6 @@ Host: {domain}
Retrieves a JSON object of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded. This can be used to know when a Historical process is ready to be queried after a restart.
-To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8093`.
-
#### Responses
@@ -893,12 +896,12 @@ To use this endpoint, `{domain}` should be the address of the Historical service
```shell
-curl "{domain}/druid/historical/v1/loadstatus"
+curl "http://:/druid/historical/v1/loadstatus"
```
```http
GET /druid/historical/v1/loadstatus HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -920,8 +923,6 @@ Host: {domain}
Retrieves a status code to indicate if all segments in the local cache have been loaded. Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
-To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8093`.
-
#### Responses
@@ -939,12 +940,12 @@ To use this endpoint, `{domain}` should be the address of the Historical service
```shell
-curl "{domain}/druid/historical/v1/readiness"
+curl "http://:/druid/historical/v1/readiness"
```
```http
GET /druid/historical/v1/readiness HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -961,8 +962,6 @@ A successful response to this endpoint results in an empty response body.
Retrieves a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker service is ready to be queried after a restart.
-To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8092`.
-
#### Responses
@@ -977,12 +976,12 @@ To use this endpoint, `{domain}` should be the address of the Historical service
```shell
-curl "{domain}/druid/broker/v1/loadstatus"
+curl "http://:/druid/broker/v1/loadstatus"
```
```http
GET /druid/broker/v1/loadstatus HTTP/1.1
-Host: {domain}
+Host: http://:
```
@@ -1004,8 +1003,6 @@ Host: {domain}
Retrieves a status code indicating if the Broker knows about all segments in the cluster and is ready to be queried after a restart. Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
-To use this endpoint, `{domain}` should be the address of the Historical service. For example, on the quickstart configuration, `{domain}` should be replaced with `http://localhost:8092`.
-
#### Responses
@@ -1024,12 +1021,12 @@ To use this endpoint, `{domain}` should be the address of the Historical service
```shell
-curl "{domain}/druid/broker/v1/readiness"
+curl "http://:/druid/broker/v1/readiness"
```
```http
GET /druid/broker/v1/readiness HTTP/1.1
-Host: {domain}
+Host: http://:
```
From 2b4fa4faf3e3e94f89f0ef7e7f768cc5961d4f6c Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Tue, 11 Jul 2023 14:24:14 -0700
Subject: [PATCH 08/18] Style update
---
docs/api-reference/service-status-api.md | 35 ++++++++++++------------
1 file changed, 18 insertions(+), 17 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index b0401fd2bf8b..760d0f5a1d3d 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -365,14 +365,11 @@ Host: http://:
#### URL
GET `/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.
+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.
Only consider a Druid node "healthy" or "ready" in automated deployment/container management systems when this endpoint returns `{"selfDiscovered": true}`. Nodes experiencing network issues may become isolated and are not healthy.
For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered": true}` indicates that the node's Zookeeper client has started receiving data from the Zookeeper cluster, enabling timely discovery of segments and other nodes.
-To retrieve the discovery status of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
-
#### Responses
@@ -417,8 +414,6 @@ Host: {router_domain}
Returns an HTTP status code to indicate node discovery within the Druid cluster. This endpoint is similar to the `status/selfDiscovered/status` endpoint, but relies on HTTP status codes alone.
Use this endpoint for monitoring checks that are unable to examine the response body. For example, AWS load balancer health checks.
-To retrieve the self-discovery status of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
-
#### Responses
@@ -459,7 +454,7 @@ A successful response to this endpoint results in an empty response body.
GET `/druid/coordinator/v1/leader`
-Retrieves the address of the current leader Coordinator of the cluster.
+Retrieves the address of the current leader Coordinator of the cluster. If any request is sent to a non-leader Coordinator, the request is automatically redirected to the leader Coordinator.
#### Responses
@@ -501,7 +496,7 @@ Host: http://:
Retrieves a JSON object with a `leader` key. Returns `true` if this server is the current leader Coordinator of the cluster. To get the individual address of the leader Coordinator node, see the [leader endpoint](#get-coordinator-leader-address).
-Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
+Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
#### Responses
@@ -597,7 +592,9 @@ Host: http://:
#### URL
GET `/druid/indexer/v1/isLeader`
-Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord 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.
+Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord of the cluster.
+
+Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
To get the individual address of the leader Overlord node, see the [leader endpoint](#get-overlord-leader-address).
@@ -644,7 +641,7 @@ Host: http://:
## MiddleManager
-### Get state status
+### Get MiddleManager state status
#### URL
@@ -694,7 +691,7 @@ Host: http://:
#### URL
GET `/druid/worker/v1/tasks`
-Retrieves a list of active tasks being run on MiddleManager. Returns JSON list of task ID strings. Normal usage should prefer to use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) or one of it's task state specific variants instead.
+Retrieves a list of active tasks being run on MiddleManager. Returns JSON list of task ID strings. Note that for normal usage, you should use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) endpoint or one of the task state specific variants instead.
#### Responses
@@ -737,16 +734,16 @@ Host: http://:
#### URL
GET `/druid/worker/v1/task/{taskid}/log`
-Retrieves task log output stream by task ID. It is strongly advised that, for normal usage, you should use the `/druid/indexer/v1/task/{taskId}/log`
-[Tasks API](./tasks-api.md) instead.
+Retrieves task log output stream by task ID. For normal usage, you should use the `/druid/indexer/v1/task/{taskId}/log`
+[Tasks API](./tasks-api.md) endpoint instead.
### Shut down running task
#### URL
POST `/druid/worker/v1/task/{taskid}/shutdown`
-Shuts down a running task by ID. For normal usage, you should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
-[Tasks API](./tasks-api.md) instead.
+Shuts down a running task by ID. For normal usage, you should use the `/druid/indexer/v1/task/{taskId}/shutdown`
+[Tasks API](./tasks-api.md) endpoint instead.
#### Responses
@@ -880,7 +877,9 @@ Host: http://:
GET `/druid/historical/v1/loadstatus`
-Retrieves a JSON object of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded. This can be used to know when a Historical process is ready to be queried after a restart.
+Retrieves a JSON object of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded.
+
+Use this endpoint to know when a Historical process is ready to be queried after a restart.
#### Responses
@@ -960,7 +959,9 @@ A successful response to this endpoint results in an empty response body.
GET `/druid/broker/v1/loadstatus`
-Retrieves a flag indicating if the Broker knows about all segments in the cluster. This can be used to know when a Broker service is ready to be queried after a restart.
+Retrieves a flag indicating if the Broker knows about all segments in the cluster.
+
+Use this endpoint to know when a Broker service is ready to be queried after a restart.
#### Responses
From 81d0e74ed35293982edc848767833bab1fde98f6 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Tue, 11 Jul 2023 16:02:08 -0700
Subject: [PATCH 09/18] Add notes for health status endpoint
---
docs/api-reference/service-status-api.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 760d0f5a1d3d..b96ceddd4251 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -185,10 +185,12 @@ Host: http://:
GET `/status/health`
-Retrieves the health of the individual Druid service. If online, it will always return a boolean `true` value, indicating that the service can receive API calls. This endpoint is suitable for automated health checks.
+Retrieves the online status of the individual Druid service. It is a simple health check to determine if the service is running and accessible. If online, it will always return a boolean `true` value, indicating that the service can receive API calls. This endpoint is suitable for automated health checks.
To retrieve the service health of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+Additional checks for readiness should use the [Historical segment readiness](#get-segment-readiness) and [Broker query readiness](#get-broker-query-readiness) endpoints.
+
#### Responses
@@ -496,7 +498,7 @@ Host: http://:
Retrieves a JSON object with a `leader` key. Returns `true` if this server is the current leader Coordinator of the cluster. To get the individual address of the leader Coordinator node, see the [leader endpoint](#get-coordinator-leader-address).
-Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
+Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer. /coo
#### Responses
@@ -592,12 +594,10 @@ Host: http://:
#### URL
GET `/druid/indexer/v1/isLeader`
-Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord of the cluster.
+Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord of the cluster. To get the individual address of the leader Overlord node, see the [leader endpoint](#get-overlord-leader-address).
Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
-To get the individual address of the leader Overlord node, see the [leader endpoint](#get-overlord-leader-address).
-
#### Responses
From f16cb6d6c562c4d83e5e5f7c3d0956ef7377fbf7 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Thu, 13 Jul 2023 12:36:34 -0700
Subject: [PATCH 10/18] Word change
---
docs/api-reference/service-status-api.md | 20 ++++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index b96ceddd4251..71897ac85540 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -32,7 +32,7 @@ In this document, `http://:` is a placeholder for the
All services support the following endpoints.
-Each endpoint can be used with the ports for each type of service. The following table contains port addresses for a local configuration:
+You can use each endpoint with the ports for each type of service. The following table contains port addresses for a local configuration:
|Service|Port address|
| ----------- | ----------- |
@@ -387,12 +387,12 @@ For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered"
```shell
-curl "{router_domain}/status/selfDiscovered/status"
+curl "http://:/status/selfDiscovered/status"
```
```http
GET /status/selfDiscovered/status HTTP/1.1
-Host: {router_domain}
+Host: http://:
```
@@ -435,12 +435,12 @@ Use this endpoint for monitoring checks that are unable to examine the response
```shell
-curl "{router_domain}/status/selfDiscovered"
+curl "http://:/status/selfDiscovered"
```
```http
GET /status/selfDiscovered HTTP/1.1
-Host: {router_domain}
+Host: http://:
```
@@ -521,12 +521,12 @@ Use this endpoint as a load balancer status check when you only want the active
```shell
-curl "http://:/druid/coordinator/v1/isLeader"
+curl "http://:/druid/coordinator/v1/isLeader"
```
```http
GET /druid/coordinator/v1/isLeader HTTP/1.1
-Host: http://:
+Host: http://:
```
@@ -879,7 +879,7 @@ Host: http://:
Retrieves a JSON object of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded.
-Use this endpoint to know when a Historical process is ready to be queried after a restart.
+Use this endpoint to know when a Broker service is ready to accept queries after a restart.
#### Responses
@@ -961,7 +961,7 @@ A successful response to this endpoint results in an empty response body.
Retrieves a flag indicating if the Broker knows about all segments in the cluster.
-Use this endpoint to know when a Broker service is ready to be queried after a restart.
+Use this endpoint to know when a Broker service is ready to accept queries after a restart.
#### Responses
@@ -1002,7 +1002,7 @@ Host: http://:
GET `/druid/broker/v1/readiness`
-Retrieves a status code indicating if the Broker knows about all segments in the cluster and is ready to be queried after a restart. Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
+Retrieves a status code to indicate Broker readiness. Readiness signifies the Broker knows about all segments in the cluster and is ready to accept queries after a restart. Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
#### Responses
From 512e897c5d2abd1f2fd6c25f3c66d87df253b4ea Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Mon, 17 Jul 2023 16:38:48 -0700
Subject: [PATCH 11/18] Style update
---
docs/api-reference/service-status-api.md | 184 ++++++++++++-----------
1 file changed, 96 insertions(+), 88 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 71897ac85540..97761dcd369b 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -26,7 +26,7 @@ sidebar_label: Service status
This document describes the API endpoints to retrieve service status, cluster information for Apache Druid.
-In this document, `http://:` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://:` with `http://localhost:8888`.
+In this document, `http://SERVICE_IP:SERVICE_PORT` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://ROUTER_IP:ROUTER_PORT` with `http://localhost:8888`.
## Common
@@ -45,13 +45,14 @@ You can use each endpoint with the ports for each type of service. The followin
### Get service information
-#### URL
-GET `/status`
-
Retrieves the Druid version, loaded extensions, memory used, total memory, and other useful information about the individual service.
To retrieve the service information of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+#### URL
+
+GET `/status`
+
#### Responses
@@ -69,12 +70,12 @@ To retrieve the service information of other services, query the individual port
```shell
-curl "http://:/status"
+curl "http://ROUTER_IP:ROUTER_PORT/status"
```
```http
GET /status HTTP/1.1
-Host: http://:
+Host: http://ROUTER_IP:ROUTER_PORT
```
@@ -181,16 +182,16 @@ Host: http://:
### Get service health
-#### URL
-
-GET `/status/health`
-
Retrieves the online status of the individual Druid service. It is a simple health check to determine if the service is running and accessible. If online, it will always return a boolean `true` value, indicating that the service can receive API calls. This endpoint is suitable for automated health checks.
To retrieve the service health of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
Additional checks for readiness should use the [Historical segment readiness](#get-segment-readiness) and [Broker query readiness](#get-broker-query-readiness) endpoints.
+#### URL
+
+GET `/status/health`
+
#### Responses
@@ -206,12 +207,12 @@ Additional checks for readiness should use the [Historical segment readiness](#g
```shell
-curl "http://:/status/health"
+curl "http://ROUTER_IP:ROUTER_PORT/status/health"
```
```http
GET /status/health HTTP/1.1
-Host: http://:
+Host: http://ROUTER_IP:ROUTER_PORT
```
@@ -227,13 +228,14 @@ Host: http://:
### Get configuration properties
-#### URL
-GET `/status/properties`
-
Retrieves the current configuration properties of the individual service queried.
To retrieve the service configuration property of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+#### URL
+
+GET `/status/properties`
+
#### Responses
@@ -249,12 +251,12 @@ To retrieve the service configuration property of other services, query the indi
```shell
-curl "http://:/status/properties"
+curl "http://ROUTER_IP:ROUTER_PORT/status/properties"
```
```http
GET /status/properties HTTP/1.1
-Host: http://:
+Host: http://ROUTER_IP:ROUTER_PORT
```
@@ -364,14 +366,15 @@ Host: http://:
### Get node discovery status and cluster integration confirmation
-#### URL
-GET `/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.
Only consider a Druid node "healthy" or "ready" in automated deployment/container management systems when this endpoint returns `{"selfDiscovered": true}`. Nodes experiencing network issues may become isolated and are not healthy.
For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered": true}` indicates that the node's Zookeeper client has started receiving data from the Zookeeper cluster, enabling timely discovery of segments and other nodes.
+#### URL
+
+GET `/status/selfDiscovered/status`
+
#### Responses
@@ -387,12 +390,12 @@ For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered"
```shell
-curl "http://:/status/selfDiscovered/status"
+curl "http://ROUTER_IP:ROUTER_PORT/status/selfDiscovered/status"
```
```http
GET /status/selfDiscovered/status HTTP/1.1
-Host: http://:
+Host: http://ROUTER_IP:ROUTER_PORT
```
@@ -410,12 +413,13 @@ Host: http://:
### Get node self-discovery status
-#### URL
-GET `/status/selfDiscovered`
-
Returns an HTTP status code to indicate node discovery within the Druid cluster. This endpoint is similar to the `status/selfDiscovered/status` endpoint, but relies on HTTP status codes alone.
Use this endpoint for monitoring checks that are unable to examine the response body. For example, AWS load balancer health checks.
+#### URL
+
+GET `/status/selfDiscovered`
+
#### Responses
@@ -435,12 +439,12 @@ Use this endpoint for monitoring checks that are unable to examine the response
```shell
-curl "http://:/status/selfDiscovered"
+curl "http://ROUTER_IP:ROUTER_PORT/status/selfDiscovered"
```
```http
GET /status/selfDiscovered HTTP/1.1
-Host: http://:
+Host: http://ROUTER_IP:ROUTER_PORT
```
@@ -452,12 +456,12 @@ A successful response to this endpoint results in an empty response body.
### Get Coordinator leader address
+Retrieves the address of the current leader Coordinator of the cluster. If any request is sent to a non-leader Coordinator, the request is automatically redirected to the leader Coordinator.
+
#### URL
GET `/druid/coordinator/v1/leader`
-Retrieves the address of the current leader Coordinator of the cluster. If any request is sent to a non-leader Coordinator, the request is automatically redirected to the leader Coordinator.
-
#### Responses
@@ -474,12 +478,12 @@ Retrieves the address of the current leader Coordinator of the cluster. If any r
```shell
-curl "http://:/druid/coordinator/v1/leader"
+curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/leader"
```
```http
GET /druid/coordinator/v1/leader HTTP/1.1
-Host: http://:
+Host: http://ROUTER_IP:ROUTER_PORT
```
@@ -493,12 +497,13 @@ Host: http://:
### Get Coordinator leader status
-#### URL
-GET `/druid/coordinator/v1/isLeader`
-
Retrieves a JSON object with a `leader` key. Returns `true` if this server is the current leader Coordinator of the cluster. To get the individual address of the leader Coordinator node, see the [leader endpoint](#get-coordinator-leader-address).
-Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer. /coo
+Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
+
+#### URL
+
+GET `/druid/coordinator/v1/isLeader`
#### Responses
@@ -521,12 +526,12 @@ Use this endpoint as a load balancer status check when you only want the active
```shell
-curl "http://:/druid/coordinator/v1/isLeader"
+curl "http://COORDINATOR_IP:COORDINATOR_PORT/druid/coordinator/v1/isLeader"
```
```http
GET /druid/coordinator/v1/isLeader HTTP/1.1
-Host: http://:
+Host: http://COORDINATOR_IP:COORDINATOR_PORT
```
@@ -547,12 +552,12 @@ Host: http://:
### Get Overlord leader address
+Retrieves the address of the current leader Overlord of the cluster. In a cluster of multiple Overlords, only one Overlord assumes the leading role, while the remaining Overlords remain on standby.
+
#### URL
GET `/druid/indexer/v1/leader`
-Retrieves the address of the current leader Overlord of the cluster. In a cluster of multiple Overlords, only one Overlord assumes the leading role, while the remaining Overlords remain on standby.
-
#### Responses
@@ -569,12 +574,12 @@ Retrieves the address of the current leader Overlord of the cluster. In a cluste
```shell
-curl "http://:/druid/indexer/v1/leader"
+curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/leader"
```
```http
GET /druid/indexer/v1/leader HTTP/1.1
-Host: http://:
+Host: http://ROUTER_IP:ROUTER_PORT
```
@@ -591,13 +596,14 @@ Host: http://:
### Get Overlord leader status
-#### URL
-GET `/druid/indexer/v1/isLeader`
-
Retrieves a JSON object with a `leader` property. The value can be `true` or `false`, indicating if this server is the current leader Overlord of the cluster. To get the individual address of the leader Overlord node, see the [leader endpoint](#get-overlord-leader-address).
Use this endpoint as a load balancer status check when you only want the active leader to be considered in-service at the load balancer.
+#### URL
+
+GET `/druid/indexer/v1/isLeader`
+
#### Responses
@@ -618,12 +624,12 @@ Use this endpoint as a load balancer status check when you only want the active
```shell
-curl "http://:/druid/indexer/v1/isLeader"
+curl "http://OVERLORD_IP:OVERLORD_PORT/druid/indexer/v1/isLeader"
```
```http
GET /druid/indexer/v1/isLeader HTTP/1.1
-Host: http://:
+Host: http://OVERLORD_IP:OVERLORD_PORT
```
@@ -643,12 +649,12 @@ Host: http://:
### Get MiddleManager state status
+Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by the combined `druid.host` and `druid.port` with a boolean `true` or `false` state as the value.
+
#### URL
GET `/druid/worker/v1/enabled`
-Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by the combined `druid.host` and `druid.port` with a boolean `true` or `false` state as the value.
-
#### Responses
@@ -666,12 +672,12 @@ Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by t
```shell
-curl "http://:/druid/worker/v1/enabled"
+curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/enabled"
```
```http
GET /druid/worker/v1/enabled HTTP/1.1
-Host: http://:
+Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
@@ -688,10 +694,11 @@ Host: http://:
### Get active tasks
+Retrieves a list of active tasks being run on MiddleManager. Returns JSON list of task ID strings. Note that for normal usage, you should use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) endpoint or one of the task state specific variants instead.
+
#### URL
-GET `/druid/worker/v1/tasks`
-Retrieves a list of active tasks being run on MiddleManager. Returns JSON list of task ID strings. Note that for normal usage, you should use the `/druid/indexer/v1/tasks` [Tasks API](./tasks-api.md) endpoint or one of the task state specific variants instead.
+GET `/druid/worker/v1/tasks`
#### Responses
@@ -709,12 +716,12 @@ Retrieves a list of active tasks being run on MiddleManager. Returns JSON list o
```shell
-curl "http://:/druid/worker/v1/tasks"
+curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/tasks"
```
```http
GET /druid/worker/v1/tasks HTTP/1.1
-Host: http://:
+Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
@@ -731,20 +738,22 @@ Host: http://:
### Get task log
-#### URL
-GET `/druid/worker/v1/task/{taskid}/log`
-
Retrieves task log output stream by task ID. For normal usage, you should use the `/druid/indexer/v1/task/{taskId}/log`
[Tasks API](./tasks-api.md) endpoint instead.
-### Shut down running task
-
#### URL
-POST `/druid/worker/v1/task/{taskid}/shutdown`
+
+GET `/druid/worker/v1/task/{taskid}/log`
+
+### Shut down running task
Shuts down a running task by ID. For normal usage, you should use the `/druid/indexer/v1/task/{taskId}/shutdown`
[Tasks API](./tasks-api.md) endpoint instead.
+#### URL
+
+POST `/druid/worker/v1/task/{taskid}/shutdown`
+
#### Responses
@@ -761,12 +770,12 @@ Shuts down a running task by ID. For normal usage, you should use the `/druid/in
```shell
-curl "http://:/druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown"
+curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown"
```
```http
POST /druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown HTTP/1.1
-Host: http://:
+Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
@@ -784,12 +793,13 @@ Host: http://:
### Disable MiddleManager
-#### URL
-POST `/druid/worker/v1/disable`
-
Disables a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
+#### URL
+
+POST `/druid/worker/v1/disable`
+
#### Responses
@@ -804,12 +814,12 @@ keyed by the combined `druid.host` and `druid.port`.
```shell
-curl "http://:/druid/worker/v1/disable"
+curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/disable"
```
```http
POST /druid/worker/v1/disable HTTP/1.1
-Host: http://:
+Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
@@ -827,13 +837,13 @@ Host: http://:
### Enable MiddleManager
+Enables a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns a JSON object
+keyed by the combined `druid.host` and `druid.port`.
+
#### URL
POST `/druid/worker/v1/enable`
-Enables a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns a JSON object
-keyed by the combined `druid.host` and `druid.port`.
-
#### Responses
@@ -848,12 +858,12 @@ keyed by the combined `druid.host` and `druid.port`.
```shell
-curl "http://:/druid/worker/v1/enable"
+curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/enable"
```
```http
POST /druid/worker/v1/enable HTTP/1.1
-Host: http://:
+Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
@@ -873,13 +883,13 @@ Host: http://:
### Get segment load status
-#### URL
+Retrieves a JSON object of the form `{"cacheInitialized":value}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded.
-GET `/druid/historical/v1/loadstatus`
+Use this endpoint to know when a Broker service is ready to accept queries after a restart.
-Retrieves a JSON object of the form `{"cacheInitialized":}`, where value is either `true` or `false` indicating if all segments in the local cache have been loaded.
+#### URL
-Use this endpoint to know when a Broker service is ready to accept queries after a restart.
+GET `/druid/historical/v1/loadstatus`
#### Responses
@@ -895,12 +905,12 @@ Use this endpoint to know when a Broker service is ready to accept queries after
```shell
-curl "http://:/druid/historical/v1/loadstatus"
+curl "http://HISTORICAL_IP:HISTORICAL_PORT/druid/historical/v1/loadstatus"
```
```http
GET /druid/historical/v1/loadstatus HTTP/1.1
-Host: http://:
+Host: http://HISTORICAL_IP:HISTORICAL_PORT
```
@@ -917,11 +927,11 @@ Host: http://:
### Get segment readiness
+Retrieves a status code to indicate if all segments in the local cache have been loaded. Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
+
#### URL
GET `/druid/historical/v1/readiness`
-Retrieves a status code to indicate if all segments in the local cache have been loaded. Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
-
#### Responses
@@ -939,12 +949,12 @@ Retrieves a status code to indicate if all segments in the local cache have been
```shell
-curl "http://:/druid/historical/v1/readiness"
+curl "http://HISTORICAL_IP:HISTORICAL_PORT/druid/historical/v1/readiness"
```
```http
GET /druid/historical/v1/readiness HTTP/1.1
-Host: http://:
+Host: http://HISTORICAL_IP:HISTORICAL_PORT
```
@@ -955,14 +965,12 @@ A successful response to this endpoint results in an empty response body.
### Get Broker query load status
+Retrieves a flag indicating if the Broker knows about all segments in the cluster. Use this endpoint to know when a Broker service is ready to accept queries after a restart.
+
#### URL
GET `/druid/broker/v1/loadstatus`
-Retrieves a flag indicating if the Broker knows about all segments in the cluster.
-
-Use this endpoint to know when a Broker service is ready to accept queries after a restart.
-
#### Responses
@@ -998,12 +1006,12 @@ Host: http://:
### Get Broker query readiness
+Retrieves a status code to indicate Broker readiness. Readiness signifies the Broker knows about all segments in the cluster and is ready to accept queries after a restart. Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
+
#### URL
GET `/druid/broker/v1/readiness`
-Retrieves a status code to indicate Broker readiness. Readiness signifies the Broker knows about all segments in the cluster and is ready to accept queries after a restart. Similar to `/druid/broker/v1/loadstatus`, but instead of returning a JSON, it returns status codes.
-
#### Responses
From 869e4574579a0571af9b1bab89cf43b17fc4545f Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Wed, 19 Jul 2023 11:09:06 -0700
Subject: [PATCH 12/18] Double check style
---
docs/api-reference/service-status-api.md | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 97761dcd369b..59d5ab205460 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -767,6 +767,8 @@ Shuts down a running task by ID. For normal usage, you should use the `/druid/in
#### Sample request
+The following example shuts down a task with specified ID `index_kafka_wikiticker_f7011f8ffba384b_fpeclode`.
+
```shell
@@ -985,7 +987,7 @@ Retrieves a flag indicating if the Broker knows about all segments in the cluste
```shell
-curl "http://:/druid/broker/v1/loadstatus"
+curl "http://BROKER_IP:BROKER_PORT/druid/broker/v1/loadstatus"
```
```http
@@ -1030,12 +1032,12 @@ Retrieves a status code to indicate Broker readiness. Readiness signifies the Br
```shell
-curl "http://:/druid/broker/v1/readiness"
+curl "http://BROKER_IP:BROKER_PORT/druid/broker/v1/readiness"
```
```http
GET /druid/broker/v1/readiness HTTP/1.1
-Host: http://:
+Host: http://BROKER_IP:BROKER_PORT
```
From e3360889c4d0d5b4fd1ff760b2af753fccc6e01d Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Thu, 20 Jul 2023 15:55:37 -0700
Subject: [PATCH 13/18] style update
---
docs/api-reference/service-status-api.md | 153 ++++++++++++++++++++---
1 file changed, 133 insertions(+), 20 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 59d5ab205460..f6df387b34ab 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -37,9 +37,9 @@ You can use each endpoint with the ports for each type of service. The followin
|Service|Port address|
| ----------- | ----------- |
| Coordinator|8081|
-| Overlord |8081|
-| Router |8888|
-| Broker |8082|
+| Overlord|8081|
+| Router|8888|
+| Broker|8082|
| Historical|8083|
| MiddleManager|8091|
@@ -51,15 +51,18 @@ To retrieve the service information of other services, query the individual port
#### URL
-GET `/status`
+GET /status
#### Responses
+
+
*Successfully retrieved service information*
+
---
@@ -69,10 +72,13 @@ To retrieve the service information of other services, query the individual port
+
```shell
curl "http://ROUTER_IP:ROUTER_PORT/status"
```
+
+
```http
GET /status HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
@@ -81,6 +87,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
+
Click to show sample response
@@ -190,15 +197,18 @@ Additional checks for readiness should use the [Historical segment readiness](#g
#### URL
-GET `/status/health`
+GET /status/health
#### Responses
+
+
*Successfully retrieved service health*
+
#### Sample request
@@ -206,10 +216,13 @@ Additional checks for readiness should use the [Historical segment readiness](#g
+
```shell
curl "http://ROUTER_IP:ROUTER_PORT/status/health"
```
+
+
```http
GET /status/health HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
@@ -218,11 +231,14 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
+
Click to show sample response
+
```json
true
```
+
@@ -234,15 +250,18 @@ To retrieve the service configuration property of other services, query the indi
#### URL
-GET `/status/properties`
+GET /status/properties
#### Responses
+
-*Successfully retrieved service configuration properties*
+
+*Successfully retrieved service configuration properties*
+
#### Sample request
@@ -250,10 +269,13 @@ To retrieve the service configuration property of other services, query the indi
+
```shell
curl "http://ROUTER_IP:ROUTER_PORT/status/properties"
```
+
+
```http
GET /status/properties HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
@@ -262,6 +284,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
+
Click to show sample response
@@ -361,6 +384,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
"druid.server.hiddenProperties": "[\"druid.s3.accessKey\",\"druid.s3.secretKey\",\"druid.metadata.storage.connector.password\", \"password\", \"key\", \"token\", \"pwd\"]"
}
```
+
@@ -373,15 +397,18 @@ For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered"
#### URL
-GET `/status/selfDiscovered/status`
+GET /status/selfDiscovered/status
#### Responses
+
+
*Node was successfully added to the cluster*
+
#### Sample request
@@ -389,10 +416,13 @@ For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered"
+
```shell
curl "http://ROUTER_IP:ROUTER_PORT/status/selfDiscovered/status"
```
+
+
```http
GET /status/selfDiscovered/status HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
@@ -401,13 +431,16 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
+
Click to show sample response
+
```json
{
"selfDiscovered": true
}
```
+
@@ -418,19 +451,24 @@ Use this endpoint for monitoring checks that are unable to examine the response
#### URL
-GET `/status/selfDiscovered`
+GET /status/selfDiscovered
#### Responses
+
+
*Successfully retrieved node status*
+
+
*Unsuccessful node self-discovery*
+
#### Sample request
@@ -438,10 +476,13 @@ Use this endpoint for monitoring checks that are unable to examine the response
+
```shell
curl "http://ROUTER_IP:ROUTER_PORT/status/selfDiscovered"
```
+
+
```http
GET /status/selfDiscovered HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
@@ -450,6 +491,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
+
A successful response to this endpoint results in an empty response body.
## Coordinator
@@ -460,15 +502,18 @@ Retrieves the address of the current leader Coordinator of the cluster. If any r
#### URL
-GET `/druid/coordinator/v1/leader`
+GET /druid/coordinator/v1/leader
#### Responses
+
-*Successfully retrieved leader Coordinator address*
+
+*Successfully retrieved leader Coordinator address*
+
---
@@ -476,23 +521,31 @@ Retrieves the address of the current leader Coordinator of the cluster. If any r
#### Sample request
+
+
```shell
curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/leader"
```
+
+
```http
GET /druid/coordinator/v1/leader HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
```
+
#### Sample response
+
Click to show sample response
+
```json
http://localhost:8081
```
+
### Get Coordinator leader status
@@ -503,18 +556,22 @@ Use this endpoint as a load balancer status check when you only want the active
#### URL
-GET `/druid/coordinator/v1/isLeader`
+GET /druid/coordinator/v1/isLeader
#### Responses
+
+
*Current server is the leader*
@@ -524,25 +581,33 @@ Use this endpoint as a load balancer status check when you only want the active
#### Sample request
+
+
```shell
curl "http://COORDINATOR_IP:COORDINATOR_PORT/druid/coordinator/v1/isLeader"
```
+
+
```http
GET /druid/coordinator/v1/isLeader HTTP/1.1
Host: http://COORDINATOR_IP:COORDINATOR_PORT
```
+
#### Sample response
+
Click to show sample response
+
```json
{
"leader": true
}
```
+
@@ -556,15 +621,18 @@ Retrieves the address of the current leader Overlord of the cluster. In a cluste
#### URL
-GET `/druid/indexer/v1/leader`
+GET /druid/indexer/v1/leader
#### Responses
+
+
*Successfully retrieved leader Overlord address*
+
---
@@ -572,18 +640,24 @@ Retrieves the address of the current leader Overlord of the cluster. In a cluste
#### Sample request
+
+
```shell
curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/leader"
```
+
+
```http
GET /druid/indexer/v1/leader HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
```
+
#### Sample response
+
Click to show sample response
@@ -602,17 +676,22 @@ Use this endpoint as a load balancer status check when you only want the active
#### URL
-GET `/druid/indexer/v1/isLeader`
+GET /druid/indexer/v1/isLeader
#### Responses
+
+
*Current server is the leader*
-
+
+
*Current server is not the leader*
@@ -622,18 +701,24 @@ Use this endpoint as a load balancer status check when you only want the active
#### Sample request
+
+
```shell
curl "http://OVERLORD_IP:OVERLORD_PORT/druid/indexer/v1/isLeader"
```
+
+
```http
GET /druid/indexer/v1/isLeader HTTP/1.1
Host: http://OVERLORD_IP:OVERLORD_PORT
```
+
#### Sample response
+
Click to show sample response
@@ -642,6 +727,7 @@ Host: http://OVERLORD_IP:OVERLORD_PORT
"leader": true
}
```
+
@@ -653,14 +739,16 @@ Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by t
#### URL
-GET `/druid/worker/v1/enabled`
+GET /druid/worker/v1/enabled
#### Responses
+
+
*Successfully retrieved MiddleManager state*
@@ -670,18 +758,24 @@ Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by t
#### Sample request
+
+
```shell
curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/enabled"
```
+
+
```http
GET /druid/worker/v1/enabled HTTP/1.1
Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
+
#### Sample response
+
Click to show sample response
@@ -690,6 +784,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
"localhost:8091": true
}
```
+
### Get active tasks
@@ -698,15 +793,18 @@ Retrieves a list of active tasks being run on MiddleManager. Returns JSON list o
#### URL
-GET `/druid/worker/v1/tasks`
+GET /druid/worker/v1/tasks
#### Responses
+
+
*Successfully retrieved active tasks*
+
---
@@ -714,18 +812,24 @@ Retrieves a list of active tasks being run on MiddleManager. Returns JSON list o
#### Sample request
+
+
```shell
curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/tasks"
```
+
+
```http
GET /druid/worker/v1/tasks HTTP/1.1
Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
+
#### Sample response
+
Click to show sample response
@@ -734,6 +838,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
"index_parallel_wikipedia_mgchefio_2023-06-13T22:18:05.360Z"
]
```
+
### Get task log
@@ -743,22 +848,24 @@ Retrieves task log output stream by task ID. For normal usage, you should use th
#### URL
-GET `/druid/worker/v1/task/{taskid}/log`
+GET /druid/worker/v1/task/:taskId/log
### Shut down running task
-Shuts down a running task by ID. For normal usage, you should use the `/druid/indexer/v1/task/{taskId}/shutdown`
+Shuts down a running task by ID. For normal usage, you should use the `/druid/indexer/v1/task/:taskId/shutdown`
[Tasks API](./tasks-api.md) endpoint instead.
#### URL
-POST `/druid/worker/v1/task/{taskid}/shutdown`
+POST /druid/worker/v1/task/:taskId/shutdown
#### Responses
+
+
*Successfully shut down a task*
@@ -770,18 +877,24 @@ Shuts down a running task by ID. For normal usage, you should use the `/druid/in
The following example shuts down a task with specified ID `index_kafka_wikiticker_f7011f8ffba384b_fpeclode`.
+
+
```shell
curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown"
```
+
+
```http
POST /druid/worker/v1/task/index_kafka_wikiticker_f7011f8ffba384b_fpeclode/shutdown HTTP/1.1
Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
+
#### Sample response
+
Click to show sample response
From 1a50b910b71dbffdf553d2435ac2faddfd3de25d Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Fri, 21 Jul 2023 09:07:08 -0700
Subject: [PATCH 14/18] docusaurus 2 spacing
---
docs/api-reference/service-status-api.md | 75 ++++++++++++++++++++++--
1 file changed, 69 insertions(+), 6 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index f6df387b34ab..36f6bfa1b200 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -913,13 +913,16 @@ keyed by the combined `druid.host` and `druid.port`.
#### URL
-POST `/druid/worker/v1/disable`
+POST /druid/worker/v1/disable
#### Responses
+
+
+
*Successfully disabled MiddleManager*
@@ -927,18 +930,24 @@ keyed by the combined `druid.host` and `druid.port`.
#### Sample request
+
+
```shell
curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/disable"
```
+
+
```http
POST /druid/worker/v1/disable HTTP/1.1
Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
+
#### Sample response
+
Click to show sample response
@@ -957,13 +966,16 @@ keyed by the combined `druid.host` and `druid.port`.
#### URL
-POST `/druid/worker/v1/enable`
+POST /druid/worker/v1/enable
#### Responses
+
+
+
*Successfully enabled MiddleManager*
@@ -971,18 +983,24 @@ keyed by the combined `druid.host` and `druid.port`.
#### Sample request
+
+
```shell
curl "http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT/druid/worker/v1/enable"
```
+
+
```http
POST /druid/worker/v1/enable HTTP/1.1
Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
```
+
#### Sample response
+
Click to show sample response
@@ -1004,13 +1022,16 @@ Use this endpoint to know when a Broker service is ready to accept queries after
#### URL
-GET `/druid/historical/v1/loadstatus`
+GET /druid/historical/v1/loadstatus
#### Responses
+
+
+
*Successfully retrieved status*
@@ -1018,18 +1039,24 @@ Use this endpoint to know when a Broker service is ready to accept queries after
#### Sample request
+
+
```shell
curl "http://HISTORICAL_IP:HISTORICAL_PORT/druid/historical/v1/loadstatus"
```
+
+
```http
GET /druid/historical/v1/loadstatus HTTP/1.1
Host: http://HISTORICAL_IP:HISTORICAL_PORT
```
+
#### Sample response
+
Click to show sample response
@@ -1038,6 +1065,7 @@ Host: http://HISTORICAL_IP:HISTORICAL_PORT
"cacheInitialized": true
}
```
+
### Get segment readiness
@@ -1045,16 +1073,23 @@ Host: http://HISTORICAL_IP:HISTORICAL_PORT
Retrieves a status code to indicate if all segments in the local cache have been loaded. Similar to `/druid/historical/v1/loadstatus`, but instead of returning JSON with a flag, it returns status codes.
#### URL
-GET `/druid/historical/v1/readiness`
+
+GET /druid/historical/v1/readiness
#### Responses
+
+
+
*Segments in local cache successfully loaded*
+
+
+
*Segments in local cache have not been loaded*
@@ -1062,18 +1097,24 @@ Retrieves a status code to indicate if all segments in the local cache have been
#### Sample request
+
+
```shell
curl "http://HISTORICAL_IP:HISTORICAL_PORT/druid/historical/v1/readiness"
```
+
+
```http
GET /druid/historical/v1/readiness HTTP/1.1
Host: http://HISTORICAL_IP:HISTORICAL_PORT
```
+
#### Sample response
+
A successful response to this endpoint results in an empty response body.
## Load Status
@@ -1084,13 +1125,16 @@ Retrieves a flag indicating if the Broker knows about all segments in the cluste
#### URL
-GET `/druid/broker/v1/loadstatus`
+GET /druid/broker/v1/loadstatus
#### Responses
+
+
+
*Segments successfully loaded*
@@ -1098,25 +1142,33 @@ Retrieves a flag indicating if the Broker knows about all segments in the cluste
#### Sample request
+
+
```shell
curl "http://BROKER_IP:BROKER_PORT/druid/broker/v1/loadstatus"
```
+
+
```http
GET /druid/broker/v1/loadstatus HTTP/1.1
Host: http://:
```
+
#### Sample response
+
Click to show sample response
+
```json
{
"inventoryInitialized": true
}
```
+
### Get Broker query readiness
@@ -1125,17 +1177,22 @@ Retrieves a status code to indicate Broker readiness. Readiness signifies the Br
#### URL
-GET `/druid/broker/v1/readiness`
+GET /druid/broker/v1/readiness
#### Responses
+
+
+
*Segments successfully loaded*
+
+
*Segments have not been loaded*
@@ -1143,18 +1200,24 @@ Retrieves a status code to indicate Broker readiness. Readiness signifies the Br
#### Sample request
+
+
```shell
curl "http://BROKER_IP:BROKER_PORT/druid/broker/v1/readiness"
```
+
+
```http
GET /druid/broker/v1/readiness HTTP/1.1
Host: http://BROKER_IP:BROKER_PORT
```
+
#### Sample response
+
A successful response to this endpoint results in an empty response body.
From 4df1e68056e90c39b856e7be8d2d9773e057de71 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Fri, 21 Jul 2023 09:13:54 -0700
Subject: [PATCH 15/18] Add spelling exception for endpoints
---
website/.spelling | 3 +++
1 file changed, 3 insertions(+)
diff --git a/website/.spelling b/website/.spelling
index 997d387c7626..93e7bdc7aca3 100644
--- a/website/.spelling
+++ b/website/.spelling
@@ -2275,3 +2275,6 @@ prometheus-emitter
kubernetes-overlord-extensions
UCS
ISO646-US
+selfDiscovered
+isLeader
+loadstatus
\ No newline at end of file
From 5145e3eeaad451d54436553f8158f170cd340990 Mon Sep 17 00:00:00 2001
From: Nhi Pham <56242907+demo-kratia@users.noreply.github.com>
Date: Fri, 21 Jul 2023 09:58:45 -0700
Subject: [PATCH 16/18] Update docs/api-reference/service-status-api.md
Co-authored-by: Katya Macedo <38017980+ektravel@users.noreply.github.com>
---
docs/api-reference/service-status-api.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 36f6bfa1b200..8033cc11ccb0 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -35,7 +35,7 @@ All services support the following endpoints.
You can use each endpoint with the ports for each type of service. The following table contains port addresses for a local configuration:
|Service|Port address|
-| ----------- | ----------- |
+| ------ | ------------ |
| Coordinator|8081|
| Overlord|8081|
| Router|8888|
From 5957e6cf78af6ec1f300f1bea14c5176b98eab64 Mon Sep 17 00:00:00 2001
From: demo-kratia <56242907+demo-kratia@users.noreply.github.com>
Date: Mon, 24 Jul 2023 15:37:46 -0700
Subject: [PATCH 17/18] remove anchor
---
docs/api-reference/service-status-api.md | 3 ---
1 file changed, 3 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 8033cc11ccb0..53a51d7f65e2 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -610,9 +610,6 @@ Host: http://COORDINATOR_IP:COORDINATOR_PORT
-
-
-
## Overlord
### Get Overlord leader address
From 86b6e0f40310afd1de9c3a039300fb848c5ed5fa Mon Sep 17 00:00:00 2001
From: Charles Smith
Date: Tue, 25 Jul 2023 11:40:44 -0700
Subject: [PATCH 18/18] Apply suggestions from code review
refine instruction regarding default host/port
---
docs/api-reference/service-status-api.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md
index 53a51d7f65e2..88059b1450a3 100644
--- a/docs/api-reference/service-status-api.md
+++ b/docs/api-reference/service-status-api.md
@@ -47,7 +47,7 @@ You can use each endpoint with the ports for each type of service. The followin
Retrieves the Druid version, loaded extensions, memory used, total memory, and other useful information about the individual service.
-To retrieve the service information of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+Modify the host and port for the endpoint to match the service to query. Refer to the [default service ports](#common) for the port numbers.
#### URL
@@ -191,7 +191,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
Retrieves the online status of the individual Druid service. It is a simple health check to determine if the service is running and accessible. If online, it will always return a boolean `true` value, indicating that the service can receive API calls. This endpoint is suitable for automated health checks.
-To retrieve the service health of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+Modify the host and port for the endpoint to match the service to query. Refer to the [default service ports](#common) for the port numbers.
Additional checks for readiness should use the [Historical segment readiness](#get-segment-readiness) and [Broker query readiness](#get-broker-query-readiness) endpoints.
@@ -246,7 +246,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
Retrieves the current configuration properties of the individual service queried.
-To retrieve the service configuration property of other services, query the individual port of each service. On a local configuration, refer to this [table](#common) for the port numbers.
+Modify the host and port for the endpoint to match the service to query. Refer to the [default service ports](#common) for the port numbers.
#### URL