honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/docs/reference/modules/scripting/painless-debugging.asciidoc

97 lines
3.8 KiB
Plaintext
Raw Normal View History

Add Debug.explain to painless You can use `Debug.explain(someObject)` in painless to throw an `Error` that can't be caught by painless code and contains an object's class. This is useful because painless's sandbox doesn't allow you to call `someObject.getClass()`. Closes #20263
2016-11-21 14:38:41 -05:00
[[modules-scripting-painless-debugging]]
=== Painless Debugging
experimental[The Painless scripting language is new and is still marked as experimental. The syntax or API may be changed in the future in non-backwards compatible ways if required.]
==== Debug.Explain
Painless doesn't have a
https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop[REPL]
and while it'd be nice for it to have one one day, it wouldn't tell you the
whole story around debugging painless scripts embedded in Elasticsearch because
the data that the scripts have access to or "context" is so important. For now
the best way to debug embedded scripts is by throwing exceptions at choice
places. While you can throw your own exceptions
(`throw new Exception('whatever')`), Painless's sandbox prevents you from
accessing useful information like the type of an object. So Painless has a
utility method, `Debug.explain` which throws the exception for you. For
example, you can use the <<search-explain>> to explore the context available to
a <<query-dsl-script-query>>.
[source,js]
---------------------------------------------------------
PUT /hockey/player/1?refresh
{"first":"johnny","last":"gaudreau","goals":[9,27,1],"assists":[17,46,0],"gp":[26,82,1]}
POST /hockey/player/1/_explain
{
"query": {
"script": {
"script": "Debug.explain(doc.goals)"
}
}
}
---------------------------------------------------------
// CONSOLE
Send error_trace by default when testing (#22195) Sends the `error_trace` parameter with all requests sent by the yaml test framework, including the doc snippet tests. This can be overridden by settings `error_trace: false`. While this drift's core's handling of the yaml tests from the client's slightly this should only be a problem for tests that rely on the default value, both of which I've fixed by setting the value explicitly. This also escapes `\n` and `\t` in the `Stash dump on failure` so the `stack_trace` is more readable. Also fixes `RestUpdateSettingsAction` to not think of the `error_trace` parameter as a setting.
2016-12-15 13:35:14 -05:00
// TEST[s/_explain/_explain?error_trace=false/ catch:/painless_explain_error/]
// The test system sends error_trace=true by default for easier debugging so
// we have to override it to get a normal shaped response
Add Debug.explain to painless You can use `Debug.explain(someObject)` in painless to throw an `Error` that can't be caught by painless code and contains an object's class. This is useful because painless's sandbox doesn't allow you to call `someObject.getClass()`. Closes #20263
2016-11-21 14:38:41 -05:00
Which shows that the class of `doc.first` is
Generate reference links for painless API (#22775) Adds "Appending B. Painless API Reference", a reference of all classes and methods available from Painless. Removes links to java packages because they contain methods that we don't expose and don't contain methods that we do expose (the ones in Augmentation). Instead this generates a list of every class and every exposed method using the same type information available to the interpreter/compiler/whatever-we-call-it. From there you can jump to the relevant docs. Right now you build all the asciidoc files by running ``` gradle generatePainlessApi ``` These files are expected to be committed because we build the docs without running `gradle`. Also changes the output of `Debug.explain` so that it is easy to search for the class in the generated reference documentation. You can also run it in an IDE safely if you pass the path to the directory in which to generate the docs as the first parameter. It'll blow away the entire directory an recreate it from scratch so be careful. And then you can build the docs by running something like: ``` ../docs/build_docs.pl --out ../built_docs/ --doc docs/reference/index.asciidoc --open ``` That is, if you have checked out https://github.com/elastic/docs in `../docs`. Wait a minute or two and your browser will pop open in with all of Elasticsearch's reference documentation. If you go to `http://localhost:8000/painless-api-reference.html` you can see this list. Or you can get there by following the links to `Modules` and `Scripting` and `Painless` and then clicking the link in the paragraphs below titled `Appendix B. Painless API Reference`. I like having these in asciidoc because we can deep link to them from the rest of the guide with constructs like `<<painless-api-reference-Object-hashCode-0>>` and `<<painless-api-reference->>` and we get link checking. Then the only brittle link maintenance bit is the link generation for javadoc. Which sucks. But I think it is important that we link to the methods directly so they are easy to find. Relates to #22720
2017-01-26 10:39:19 -05:00
`org.elasticsearch.index.fielddata.ScriptDocValues.Longs` by responding with:
Add Debug.explain to painless You can use `Debug.explain(someObject)` in painless to throw an `Error` that can't be caught by painless code and contains an object's class. This is useful because painless's sandbox doesn't allow you to call `someObject.getClass()`. Closes #20263
2016-11-21 14:38:41 -05:00
[source,js]
---------------------------------------------------------
{
"error": {
"type": "script_exception",
"to_string": "[1, 9, 27]",
Generate reference links for painless API (#22775) Adds "Appending B. Painless API Reference", a reference of all classes and methods available from Painless. Removes links to java packages because they contain methods that we don't expose and don't contain methods that we do expose (the ones in Augmentation). Instead this generates a list of every class and every exposed method using the same type information available to the interpreter/compiler/whatever-we-call-it. From there you can jump to the relevant docs. Right now you build all the asciidoc files by running ``` gradle generatePainlessApi ``` These files are expected to be committed because we build the docs without running `gradle`. Also changes the output of `Debug.explain` so that it is easy to search for the class in the generated reference documentation. You can also run it in an IDE safely if you pass the path to the directory in which to generate the docs as the first parameter. It'll blow away the entire directory an recreate it from scratch so be careful. And then you can build the docs by running something like: ``` ../docs/build_docs.pl --out ../built_docs/ --doc docs/reference/index.asciidoc --open ``` That is, if you have checked out https://github.com/elastic/docs in `../docs`. Wait a minute or two and your browser will pop open in with all of Elasticsearch's reference documentation. If you go to `http://localhost:8000/painless-api-reference.html` you can see this list. Or you can get there by following the links to `Modules` and `Scripting` and `Painless` and then clicking the link in the paragraphs below titled `Appendix B. Painless API Reference`. I like having these in asciidoc because we can deep link to them from the rest of the guide with constructs like `<<painless-api-reference-Object-hashCode-0>>` and `<<painless-api-reference->>` and we get link checking. Then the only brittle link maintenance bit is the link generation for javadoc. Which sucks. But I think it is important that we link to the methods directly so they are easy to find. Relates to #22720
2017-01-26 10:39:19 -05:00
"painless_class": "org.elasticsearch.index.fielddata.ScriptDocValues.Longs",
"java_class": "org.elasticsearch.index.fielddata.ScriptDocValues$Longs",
Add Debug.explain to painless You can use `Debug.explain(someObject)` in painless to throw an `Error` that can't be caught by painless code and contains an object's class. This is useful because painless's sandbox doesn't allow you to call `someObject.getClass()`. Closes #20263
2016-11-21 14:38:41 -05:00
...
},
"status": 500
}
---------------------------------------------------------
// TESTRESPONSE[s/\.\.\./"script_stack": $body.error.script_stack, "script": $body.error.script, "lang": $body.error.lang, "caused_by": $body.error.caused_by, "root_cause": $body.error.root_cause, "reason": $body.error.reason/]
Generate reference links for painless API (#22775) Adds "Appending B. Painless API Reference", a reference of all classes and methods available from Painless. Removes links to java packages because they contain methods that we don't expose and don't contain methods that we do expose (the ones in Augmentation). Instead this generates a list of every class and every exposed method using the same type information available to the interpreter/compiler/whatever-we-call-it. From there you can jump to the relevant docs. Right now you build all the asciidoc files by running ``` gradle generatePainlessApi ``` These files are expected to be committed because we build the docs without running `gradle`. Also changes the output of `Debug.explain` so that it is easy to search for the class in the generated reference documentation. You can also run it in an IDE safely if you pass the path to the directory in which to generate the docs as the first parameter. It'll blow away the entire directory an recreate it from scratch so be careful. And then you can build the docs by running something like: ``` ../docs/build_docs.pl --out ../built_docs/ --doc docs/reference/index.asciidoc --open ``` That is, if you have checked out https://github.com/elastic/docs in `../docs`. Wait a minute or two and your browser will pop open in with all of Elasticsearch's reference documentation. If you go to `http://localhost:8000/painless-api-reference.html` you can see this list. Or you can get there by following the links to `Modules` and `Scripting` and `Painless` and then clicking the link in the paragraphs below titled `Appendix B. Painless API Reference`. I like having these in asciidoc because we can deep link to them from the rest of the guide with constructs like `<<painless-api-reference-Object-hashCode-0>>` and `<<painless-api-reference->>` and we get link checking. Then the only brittle link maintenance bit is the link generation for javadoc. Which sucks. But I think it is important that we link to the methods directly so they are easy to find. Relates to #22720
2017-01-26 10:39:19 -05:00
You can use the same trick to see that `_source` is a `LinkedHashMap`
Add Debug.explain to painless You can use `Debug.explain(someObject)` in painless to throw an `Error` that can't be caught by painless code and contains an object's class. This is useful because painless's sandbox doesn't allow you to call `someObject.getClass()`. Closes #20263
2016-11-21 14:38:41 -05:00
in the `_update` API:
[source,js]
---------------------------------------------------------
POST /hockey/player/1/_update
{
"script": "Debug.explain(ctx._source)"
}
---------------------------------------------------------
// CONSOLE
Send error_trace by default when testing (#22195) Sends the `error_trace` parameter with all requests sent by the yaml test framework, including the doc snippet tests. This can be overridden by settings `error_trace: false`. While this drift's core's handling of the yaml tests from the client's slightly this should only be a problem for tests that rely on the default value, both of which I've fixed by setting the value explicitly. This also escapes `\n` and `\t` in the `Stash dump on failure` so the `stack_trace` is more readable. Also fixes `RestUpdateSettingsAction` to not think of the `error_trace` parameter as a setting.
2016-12-15 13:35:14 -05:00
// TEST[continued s/_update/_update?error_trace=false/ catch:/painless_explain_error/]
Add Debug.explain to painless You can use `Debug.explain(someObject)` in painless to throw an `Error` that can't be caught by painless code and contains an object's class. This is useful because painless's sandbox doesn't allow you to call `someObject.getClass()`. Closes #20263
2016-11-21 14:38:41 -05:00
The response looks like:
[source,js]
---------------------------------------------------------
{
"error" : {
"root_cause": ...,
"type": "illegal_argument_exception",
"reason": "failed to execute script",
"caused_by": {
"type": "script_exception",
"to_string": "{gp=[26, 82, 1], last=gaudreau, assists=[17, 46, 0], first=johnny, goals=[9, 27, 1]}",
Generate reference links for painless API (#22775) Adds "Appending B. Painless API Reference", a reference of all classes and methods available from Painless. Removes links to java packages because they contain methods that we don't expose and don't contain methods that we do expose (the ones in Augmentation). Instead this generates a list of every class and every exposed method using the same type information available to the interpreter/compiler/whatever-we-call-it. From there you can jump to the relevant docs. Right now you build all the asciidoc files by running ``` gradle generatePainlessApi ``` These files are expected to be committed because we build the docs without running `gradle`. Also changes the output of `Debug.explain` so that it is easy to search for the class in the generated reference documentation. You can also run it in an IDE safely if you pass the path to the directory in which to generate the docs as the first parameter. It'll blow away the entire directory an recreate it from scratch so be careful. And then you can build the docs by running something like: ``` ../docs/build_docs.pl --out ../built_docs/ --doc docs/reference/index.asciidoc --open ``` That is, if you have checked out https://github.com/elastic/docs in `../docs`. Wait a minute or two and your browser will pop open in with all of Elasticsearch's reference documentation. If you go to `http://localhost:8000/painless-api-reference.html` you can see this list. Or you can get there by following the links to `Modules` and `Scripting` and `Painless` and then clicking the link in the paragraphs below titled `Appendix B. Painless API Reference`. I like having these in asciidoc because we can deep link to them from the rest of the guide with constructs like `<<painless-api-reference-Object-hashCode-0>>` and `<<painless-api-reference->>` and we get link checking. Then the only brittle link maintenance bit is the link generation for javadoc. Which sucks. But I think it is important that we link to the methods directly so they are easy to find. Relates to #22720
2017-01-26 10:39:19 -05:00
"painless_class": "LinkedHashMap",
"java_class": "java.util.LinkedHashMap",
Add Debug.explain to painless You can use `Debug.explain(someObject)` in painless to throw an `Error` that can't be caught by painless code and contains an object's class. This is useful because painless's sandbox doesn't allow you to call `someObject.getClass()`. Closes #20263
2016-11-21 14:38:41 -05:00
...
}
},
"status": 400
}
---------------------------------------------------------
// TESTRESPONSE[s/"root_cause": \.\.\./"root_cause": $body.error.root_cause/]
// TESTRESPONSE[s/\.\.\./"script_stack": $body.error.caused_by.script_stack, "script": $body.error.caused_by.script, "lang": $body.error.caused_by.lang, "caused_by": $body.error.caused_by.caused_by, "reason": $body.error.caused_by.reason/]
// TESTRESPONSE[s/"to_string": ".+"/"to_string": $body.error.caused_by.to_string/]
Generate reference links for painless API (#22775) Adds "Appending B. Painless API Reference", a reference of all classes and methods available from Painless. Removes links to java packages because they contain methods that we don't expose and don't contain methods that we do expose (the ones in Augmentation). Instead this generates a list of every class and every exposed method using the same type information available to the interpreter/compiler/whatever-we-call-it. From there you can jump to the relevant docs. Right now you build all the asciidoc files by running ``` gradle generatePainlessApi ``` These files are expected to be committed because we build the docs without running `gradle`. Also changes the output of `Debug.explain` so that it is easy to search for the class in the generated reference documentation. You can also run it in an IDE safely if you pass the path to the directory in which to generate the docs as the first parameter. It'll blow away the entire directory an recreate it from scratch so be careful. And then you can build the docs by running something like: ``` ../docs/build_docs.pl --out ../built_docs/ --doc docs/reference/index.asciidoc --open ``` That is, if you have checked out https://github.com/elastic/docs in `../docs`. Wait a minute or two and your browser will pop open in with all of Elasticsearch's reference documentation. If you go to `http://localhost:8000/painless-api-reference.html` you can see this list. Or you can get there by following the links to `Modules` and `Scripting` and `Painless` and then clicking the link in the paragraphs below titled `Appendix B. Painless API Reference`. I like having these in asciidoc because we can deep link to them from the rest of the guide with constructs like `<<painless-api-reference-Object-hashCode-0>>` and `<<painless-api-reference->>` and we get link checking. Then the only brittle link maintenance bit is the link generation for javadoc. Which sucks. But I think it is important that we link to the methods directly so they are easy to find. Relates to #22720
2017-01-26 10:39:19 -05:00
Once you have a class you can go to <<painless-api-reference>> to see a list of
available methods.