diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 52b77e1d432..9c8d6f5c460 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -631,6 +631,48 @@ Store task logs in HDFS. Note that the `druid-hdfs-storage` extension must be lo |`druid.indexer.logs.kill.initialDelay`| Optional. Number of milliseconds after Overlord start when first auto kill is run. |random value less than 300000 (5 mins)| |`druid.indexer.logs.kill.delay`|Optional. Number of milliseconds of delay between successive executions of auto kill run. |21600000 (6 hours)| +### API error response + +You can configure Druid API error responses to hide internal information like the Druid class name, stack trace, thread name, servlet name, code, line/column number, host, or IP address. + +|Property|Description|Default| +|--------|-----------|-------| +|`druid.server.http.showDetailedJettyErrors`|When set to true, any error from the Jetty layer / Jetty filter includes the following fields in the JSON response: `servlet`, `message`, `url`, `status`, and `cause`, if it exists. When set to false, the JSON response only includes `message`, `url`, and `status`. The field values remain unchanged.|true| +|`druid.server.http.errorResponseTransformStrategy.strategy`|Error response transform strategy. The strategy controls how Druid transforms error responses from Druid services. When unset or set to `none`, Druid leaves error responses unchanged.|`none`| + +##### Error response transform strategy + +You can use an error response transform strategy to transform error responses from within Druid services to hide internal information. +When you specify an error response transform strategy other than `none`, Druid transforms the error responses from Druid services as follows: + - For any query API that fails in the Router service, Druid sets the fields `errorClass` and `host` to null. Druid applies the transformation strategy to the `errorMessage` field. + - For any SQL query API that fails, for example `POST /druid/v2/sql/...`, Druid sets the fields `errorClass` and `host` to null. Druid applies the transformation strategy to the `errorMessage` field. + +###### No error response transform strategy + +In this mode, Druid leaves error responses from underlying services unchanged and returns the unchanged errors to the API client. +This is the default Druid error response mode. To explicitly enable this strategy, set `druid.server.http.errorResponseTransformStrategy.strategy` to "none". + +###### Allowed regular expression error response transform strategy + +In this mode, Druid validates the error responses from underlying services against a list of regular expressions. Only error messages that match a configured regular expression are returned. To enable this strategy, set `druid.server.http.errorResponseTransformStrategy.strategy` to `allowedRegex`. + +|Property|Description|Default| +|--------|-----------|-------| +|`druid.server.http.errorResponseTransformStrategy.allowedRegex`|The list of regular expressions Druid uses to validate error messages. If the error message matches any of the regular expressions, then Druid includes it in the response unchanged. If the error message does not match any of the regular expressions, Druid replaces the error message with null or with a default message depending on the type of underlying Exception. |`[]`| + +For example, consider the following error response: +``` +{"error":"Plan validation failed","errorMessage":"org.apache.calcite.runtime.CalciteContextException: From line 1, column 15 to line 1, column 38: Object 'nonexistent-datasource' not found","errorClass":"org.apache.calcite.tools.ValidationException","host":null} +``` +If `druid.server.http.errorResponseTransformStrategy.allowedRegex` is set to `[]`, Druid transforms the query error response to the following: +``` +{"error":"Plan validation failed","errorMessage":null,"errorClass":null,"host":null} +``` +On the other hand, if `druid.server.http.errorResponseTransformStrategy.allowedRegex` is set to `[".*CalciteContextException.*"]` then Druid transforms the query error response to the following: +``` +{"error":"Plan validation failed","errorMessage":"org.apache.calcite.runtime.CalciteContextException: From line 1, column 15 to line 1, column 38: Object 'nonexistent-datasource' not found","errorClass":null,"host":null} +``` + ### Overlord Discovery This config is used to find the [Overlord](../design/overlord.md) using Curator service discovery. Only required if you are actually running an Overlord.