From 17916237005f0eedc4de8587b3927731be215d6f Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Tue, 22 Nov 2016 18:50:29 -0500 Subject: [PATCH] Document `error_trace` The `error_trace` parameter turns on the `stack_trace` field in errors which returns stack traces. Removes documentation for `camelCase` because it hasn't worked in a while.... Documents the internal parameters used to render stack traces as internal only. Closes #21708 --- .../elasticsearch/ElasticsearchException.java | 12 ++- docs/reference/api-conventions.asciidoc | 80 +++++++++++++++++-- .../rest/yaml/section/MatchAssertion.java | 8 ++ 3 files changed, 94 insertions(+), 6 deletions(-) diff --git a/core/src/main/java/org/elasticsearch/ElasticsearchException.java b/core/src/main/java/org/elasticsearch/ElasticsearchException.java index 3db28cb3567..095e0ec2b30 100644 --- a/core/src/main/java/org/elasticsearch/ElasticsearchException.java +++ b/core/src/main/java/org/elasticsearch/ElasticsearchException.java @@ -52,7 +52,17 @@ public class ElasticsearchException extends RuntimeException implements ToXConte public static final Version V_5_1_0_UNRELEASED = Version.fromId(5010099); public static final Version V_5_0_2_UNRELEASED = Version.fromId(5000299); public static final Version UNKNOWN_VERSION_ADDED = Version.fromId(0); + /** + * Passed in the {@link Params} of {@link #toXContent(XContentBuilder, org.elasticsearch.common.xcontent.ToXContent.Params, Throwable)} + * to control if the {@code caused_by} element should render. Unlike most parameters to {@code toXContent} methods this parameter is + * internal only and not available as a URL parameter. + */ public static final String REST_EXCEPTION_SKIP_CAUSE = "rest.exception.cause.skip"; + /** + * Passed in the {@link Params} of {@link #toXContent(XContentBuilder, org.elasticsearch.common.xcontent.ToXContent.Params, Throwable)} + * to control if the {@code stack_trace} element should render. Unlike most parameters to {@code toXContent} methods this parameter is + * internal only and not available as a URL parameter. Use the {@code error_trace} parameter instead. + */ public static final String REST_EXCEPTION_SKIP_STACK_TRACE = "rest.exception.stacktrace.skip"; public static final boolean REST_EXCEPTION_SKIP_STACK_TRACE_DEFAULT = true; public static final boolean REST_EXCEPTION_SKIP_CAUSE_DEFAULT = false; @@ -308,7 +318,7 @@ public class ElasticsearchException extends RuntimeException implements ToXConte } /** - * Statis toXContent helper method that also renders non {@link org.elasticsearch.ElasticsearchException} instances as XContent. + * Static toXContent helper method that also renders non {@link org.elasticsearch.ElasticsearchException} instances as XContent. */ public static void toXContent(XContentBuilder builder, Params params, Throwable ex) throws IOException { ex = ExceptionsHelper.unwrapCause(ex); diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index 119bcdfd95c..6404f6ebf13 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -586,12 +586,82 @@ generates an edit distance based on the length of the term. For lengths: -- [float] -=== Result Casing +[[common-options-error-options]] +=== Enabling stack traces -All REST APIs accept the `case` parameter. When set to `camelCase`, all -field names in the result will be returned in camel casing, otherwise, -underscore casing will be used. Note, this does not apply to the source -document indexed. +By default when a request returns an error Elasticsearch doesn't include the +stack trace of the error. You can enable that behavior by setting the +`error_trace` url parameter to `true`. For example, by default when you send an +invalid `size` parameter to the `_search` API: + +[source,js] +---------------------------------------------------------------------- +POST /twitter/_search?size=surprise_me +---------------------------------------------------------------------- +// CONSOLE +// TEST[catch:request] + +The response looks like: + +[source,js] +---------------------------------------------------------------------- +{ + "error" : { + "root_cause" : [ + { + "type" : "illegal_argument_exception", + "reason" : "Failed to parse int parameter [size] with value [surprise_me]" + } + ], + "type" : "illegal_argument_exception", + "reason" : "Failed to parse int parameter [size] with value [surprise_me]", + "caused_by" : { + "type" : "number_format_exception", + "reason" : "For input string: \"surprise_me\"" + } + }, + "status" : 400 +} +---------------------------------------------------------------------- +// TESTRESPONSE + +But if you set `error_trace=true`: + +[source,js] +---------------------------------------------------------------------- +POST /twitter/_search?size=surprise_me&error_trace=true +---------------------------------------------------------------------- +// CONSOLE +// TEST[catch:request] + +The response looks like: + +[source,js] +---------------------------------------------------------------------- +{ + "error": { + "root_cause": [ + { + "type": "illegal_argument_exception", + "reason": "Failed to parse int parameter [size] with value [surprise_me]", + "stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..." + } + ], + "type": "illegal_argument_exception", + "reason": "Failed to parse int parameter [size] with value [surprise_me]", + "stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...", + "caused_by": { + "type": "number_format_exception", + "reason": "For input string: \"surprise_me\"", + "stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..." + } + }, + "status": 400 +} +---------------------------------------------------------------------- +// TESTRESPONSE[s/"stack_trace": "Failed to parse int parameter.+\.\.\."/"stack_trace": $body.error.root_cause.0.stack_trace/] +// TESTRESPONSE[s/"stack_trace": "java.lang.IllegalArgum.+\.\.\."/"stack_trace": $body.error.stack_trace/] +// TESTRESPONSE[s/"stack_trace": "java.lang.Number.+\.\.\."/"stack_trace": $body.error.caused_by.stack_trace/] [float] === Request body in query string diff --git a/test/framework/src/main/java/org/elasticsearch/test/rest/yaml/section/MatchAssertion.java b/test/framework/src/main/java/org/elasticsearch/test/rest/yaml/section/MatchAssertion.java index 2bfb94e6584..60e34247044 100644 --- a/test/framework/src/main/java/org/elasticsearch/test/rest/yaml/section/MatchAssertion.java +++ b/test/framework/src/main/java/org/elasticsearch/test/rest/yaml/section/MatchAssertion.java @@ -173,6 +173,14 @@ public class MatchAssertion extends Assertion { return; } if (Objects.equals(expected, actual)) { + if (expected instanceof String) { + String expectedString = (String) expected; + if (expectedString.length() > 50) { + expectedString = expectedString.substring(0, 50) + "..."; + } + field(field, "same [" + expectedString + "]"); + return; + } field(field, "same [" + expected + "]"); return; }