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

Author: nik9000

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 @@ private void xContentHeader(XContentBuilder builder, String key, List<String> va
     }
 
     /**
-     * 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);

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

test/framework/src/main/java/org/elasticsearch/test/rest/yaml/section/MatchAssertion.java

@@ -173,6 +173,14 @@ private void compare(String field, @Nullable Object actual, Object expected) {
                 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;
             }