From 7e8db3b2ca84a7b9d58daacc25295d8e64852dc8 Mon Sep 17 00:00:00 2001 From: Gordon Brown Date: Mon, 26 Nov 2018 15:25:56 -0700 Subject: [PATCH] Add HLRC docs for Explain Lifecycle (#35803) Adds HLRC documentation for the Explain Lifecycle API. --- .../documentation/ILMDocumentationIT.java | 113 ++++++++++++++++++ .../high-level/ilm/explain_lifecycle.asciidoc | 50 ++++++++ .../high-level/supported-apis.asciidoc | 2 + 3 files changed, 165 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..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 @@ -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,117 @@ 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); + + 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 = + 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..028f34793fef4 --- /dev/null +++ b/docs/java-rest/high-level/ilm/explain_lifecycle.asciidoc @@ -0,0 +1,50 @@ +-- +: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. 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. 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. 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[] + + diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index d7c8de6838b40..ac5b92db61120 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -474,6 +474,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>> @@ -483,6 +484,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[]