Painless Debugging

Painless doesn’t have a 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 Explain API to explore the context available to a Script Query.

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)"
    }
  }
}

Which shows that the class of doc.first is org.elasticsearch.index.fielddata.ScriptDocValues$Longs by responding with:

{
   "error": {
      "type": "script_exception",
      "class": "org.elasticsearch.index.fielddata.ScriptDocValues$Longs",
      "to_string": "[1, 9, 27]",
      ...
   },
   "status": 500
}

You can use the same trick to see that _source is a java.util.LinkedHashMap in the _update API:

POST /hockey/player/1/_update
{
  "script": "Debug.explain(ctx._source)"
}

The response looks like:

{
  "error" : {
    "root_cause": ...,
    "type": "illegal_argument_exception",
    "reason": "failed to execute script",
    "caused_by": {
      "type": "script_exception",
      "class": "java.util.LinkedHashMap",
      "to_string": "{gp=[26, 82, 1], last=gaudreau, assists=[17, 46, 0], first=johnny, goals=[9, 27, 1]}",
      ...
    }
  },
  "status": 400
}

Once you have the class of an object you can go here and check the available methods. Painless uses a strict whitelist to prevent scripts that don’t work well with Elasticsearch and all whitelisted methods are listed in a file named after the package of the object (everything before the last .). So java.util.Map is listed in a file named java.util.txt starting on the line that looks like class Map -> java.util.Map {.

With the list of whitelisted methods in hand you can turn to either Javadoc, Elasticsearch’s source tree or, for whitelisted methods ending in *, the Augmentation class.