From 1b9425bd609fa343b6bbdf7558016f248e5a91b1 Mon Sep 17 00:00:00 2001 From: Gordon Brown Date: Wed, 21 Nov 2018 14:07:20 -0700 Subject: [PATCH 1/2] Add HLRC docs for Explain LIfecycle Adds HLRC documentation for the Explain Lifecycle API. --- .../documentation/ILMDocumentationIT.java | 105 ++++++++++++++++++ .../high-level/ilm/explain_lifecycle.asciidoc | 45 ++++++++ .../high-level/supported-apis.asciidoc | 2 + 3 files changed, 152 insertions(+) create mode 100644 docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java index d3b36c8822ed9..b1a060aaceb97 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java @@ -31,8 +31,10 @@ import org.elasticsearch.client.indexlifecycle.DeleteAction; import org.elasticsearch.client.indexlifecycle.DeleteLifecyclePolicyRequest; import org.elasticsearch.client.indexlifecycle.ExplainLifecycleRequest; +import org.elasticsearch.client.indexlifecycle.ExplainLifecycleResponse; import org.elasticsearch.client.indexlifecycle.GetLifecyclePolicyRequest; import org.elasticsearch.client.indexlifecycle.GetLifecyclePolicyResponse; +import org.elasticsearch.client.indexlifecycle.IndexLifecycleExplainResponse; import org.elasticsearch.client.indexlifecycle.LifecycleAction; import org.elasticsearch.client.indexlifecycle.LifecycleManagementStatusRequest; import org.elasticsearch.client.indexlifecycle.LifecycleManagementStatusResponse; @@ -313,6 +315,109 @@ public void onFailure(Exception e) { assertTrue(latch.await(30L, TimeUnit.SECONDS)); } + public void testExplainLifecycle() throws Exception { + RestHighLevelClient client = highLevelClient(); + + // create a policy & index + { + Map phases = new HashMap<>(); + Map hotActions = new HashMap<>(); + hotActions.put(RolloverAction.NAME, new RolloverAction( + new ByteSizeValue(50, ByteSizeUnit.GB), null, null)); + phases.put("hot", new Phase("hot", TimeValue.ZERO, hotActions)); + + LifecyclePolicy policy = new LifecyclePolicy("my_policy", + phases); + PutLifecyclePolicyRequest putRequest = + new PutLifecyclePolicyRequest(policy); + client.indexLifecycle().putLifecyclePolicy(putRequest, RequestOptions.DEFAULT); + + CreateIndexRequest createIndexRequest = new CreateIndexRequest("my_index", + Settings.builder() + .put(IndexMetaData.SETTING_NUMBER_OF_SHARDS, 1) + .put("index.lifecycle.name", "my_policy") + .build()); + client.indices().create(createIndexRequest, RequestOptions.DEFAULT); + CreateIndexRequest createOtherIndexRequest = new CreateIndexRequest("other_index", + Settings.builder() + .put(IndexMetaData.SETTING_NUMBER_OF_SHARDS, 1) + .build()); + client.indices().create(createOtherIndexRequest, RequestOptions.DEFAULT); + + + // wait for the policy to become active + assertBusy(() -> assertNotNull(client.indexLifecycle() + .explainLifecycle(new ExplainLifecycleRequest("my_index"), RequestOptions.DEFAULT) + .getIndexResponses().get("my_index").getAction())); + } + + // tag::ilm-explain-lifecycle-request + ExplainLifecycleRequest request = + new ExplainLifecycleRequest("my_index", "other_index"); // <1> + // end::ilm-explain-lifecycle-request + + // tag::ilm-explain-lifecycle-execute + ExplainLifecycleResponse response = client.indexLifecycle() + .explainLifecycle(request, RequestOptions.DEFAULT); + // end::ilm-explain-lifecycle-execute + assertNotNull(response); + + // tag::ilm-explain-lifecycle-response + Map indices = + response.getIndexResponses(); + IndexLifecycleExplainResponse myIndex = indices.get("my_index"); + String policyName = myIndex.getPolicyName(); // <1> + boolean isManaged = myIndex.managedByILM(); // <2> + + String phase = myIndex.getPhase(); // <3> + long phaseTime = myIndex.getPhaseTime(); // <4> + String action = myIndex.getAction(); // <5> + long actionTime = myIndex.getActionTime(); + String step = myIndex.getStep(); // <6> + long stepTime = myIndex.getStepTime(); + + String failedStep = myIndex.getFailedStep(); // <7> + // end::ilm-explain-lifecycle-response + assertEquals("my_policy", policyName); + assertTrue(isManaged); + + assertEquals("hot", phase); + assertNotEquals(0, phaseTime); + assertEquals("rollover", action); + assertNotEquals(0, actionTime); + assertEquals("check-rollover-ready", step); + assertNotEquals(0, stepTime); + + assertNull(failedStep); + + assertFalse(indices.get("other_index").managedByILM()); + + // tag::ilm-explain-lifecycle-execute-listener + ActionListener listener = + new ActionListener() { + @Override + public void onResponse(ExplainLifecycleResponse response) + { + Map indices = + response.getIndexResponses(); // <1> + } + + @Override + public void onFailure(Exception e) { + // <2> + } + }; + // end::ilm-explain-lifecycle-execute-listener + final CountDownLatch latch = new CountDownLatch(1); + listener = new LatchedActionListener<>(listener, latch); + + // tag::ilm-explain-lifecycle-execute-async + client.indexLifecycle().explainLifecycleAsync(request, + RequestOptions.DEFAULT, listener); // <1> + // end::ilm-explain-lifecycle-execute-async + assertTrue(latch.await(30L, TimeUnit.SECONDS)); + } + public void testStartStopStatus() throws Exception { RestHighLevelClient client = highLevelClient(); diff --git a/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc b/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc new file mode 100644 index 0000000000000..f0c8d190aa320 --- /dev/null +++ b/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc @@ -0,0 +1,45 @@ +-- +:api: ilm-explain-lifecycle +:request: ExplainLifecycleRequest +:response: ExplainLifecycleResponse +-- + +[id="{upid}-{api}"] +=== Explain Lifecycle API + + +[id="{upid}-{api}-request"] +==== Request + +The Explain Lifecycle API allows you to retrieve information about the execution +of a Lifecycle Policy with respect to one or more indices. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-request] +-------------------------------------------------- +<1> Requests an explanation of policy execution for `my_index` and `other_index` + + +[id="{upid}-{api}-response"] +==== Response + +The returned +{response}+ contains a map of `LifecyclePolicyMetadata`, +accessible by the name of the policy, which contains data about each policy, +as well as the policy definition. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-response] +-------------------------------------------------- +<1> The name of the policy in use for this index, if any. +<2> Indicates whether this index is being managed by Index Lifecycle Management. +<3> The Phase (`hot`, `warm`, etc.) this index is currently in. +<4> The time this index entered this Phase of execution. +<5> The Action (`rollover`, `shrink`, etc.) this index is currently in. +<6> The Step this index is currently in. +<7> If this index is in the `ERROR` Step, this will indicate which Step failed. + +include::../execution.asciidoc[] + + diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index e23967bfe30d5..610037348f854 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -469,6 +469,7 @@ Management APIs: * <<{upid}-ilm-put-lifecycle-policy>> * <<{upid}-ilm-delete-lifecycle-policy>> * <<{upid}-ilm-get-lifecycle-policy>> +* <<{upid}-ilm-explain-lifecycle>> * <<{upid}-ilm-start-ilm>> * <<{upid}-ilm-stop-ilm>> * <<{upid}-ilm-status>> @@ -478,6 +479,7 @@ Management APIs: include::ilm/put_lifecycle_policy.asciidoc[] include::ilm/delete_lifecycle_policy.asciidoc[] include::ilm/get_lifecycle_policy.asciidoc[] +include::ilm/explain_lifecycle.asciidoc[] include::ilm/start_lifecycle_management.asciidoc[] include::ilm/stop_lifecycle_management.asciidoc[] include::ilm/lifecycle_management_status.asciidoc[] From 71cca2a26109a9ad98f39185e7770c36e3ddd602 Mon Sep 17 00:00:00 2001 From: Gordon Brown Date: Wed, 21 Nov 2018 16:15:17 -0700 Subject: [PATCH 2/2] Address review comments --- .../client/documentation/ILMDocumentationIT.java | 10 +++++++++- .../high-level/ilm/explain_lifecycle.asciidoc | 13 +++++++++---- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java index b1a060aaceb97..c647e7c01b946 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java @@ -390,7 +390,15 @@ public void testExplainLifecycle() throws Exception { assertNull(failedStep); - assertFalse(indices.get("other_index").managedByILM()); + IndexLifecycleExplainResponse otherIndex = indices.get("other_index"); + assertFalse(otherIndex.managedByILM()); + assertNull(otherIndex.getPolicyName()); + assertNull(otherIndex.getPhase()); + assertNull(otherIndex.getAction()); + assertNull(otherIndex.getStep()); + assertNull(otherIndex.getFailedStep()); + assertNull(otherIndex.getPhaseExecutionInfo()); + assertNull(otherIndex.getStepInfo()); // tag::ilm-explain-lifecycle-execute-listener ActionListener listener = diff --git a/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc b/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc index f0c8d190aa320..028f34793fef4 100644 --- a/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc +++ b/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc @@ -32,13 +32,18 @@ as well as the policy definition. -------------------------------------------------- include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- -<1> The name of the policy in use for this index, if any. +<1> The name of the policy in use for this index, if any. Will be `null` if the +index does not have an associated policy. <2> Indicates whether this index is being managed by Index Lifecycle Management. -<3> The Phase (`hot`, `warm`, etc.) this index is currently in. +<3> The Phase (`hot`, `warm`, etc.) this index is currently in. Will be `null` if +the index is not managed by Index Lifecycle Management. <4> The time this index entered this Phase of execution. -<5> The Action (`rollover`, `shrink`, etc.) this index is currently in. -<6> The Step this index is currently in. +<5> The Action (`rollover`, `shrink`, etc.) this index is currently in. Will be `null` if +the index is not managed by Index Lifecycle Management. +<6> The Step this index is currently in. Will be `null` if +the index is not managed by Index Lifecycle Management. <7> If this index is in the `ERROR` Step, this will indicate which Step failed. +Otherwise, it will be `null`. include::../execution.asciidoc[]