[tinkerpop] 02/04: TINKERPOP-2447 Help users understand StackOverflowError

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git

commit 8b207721f46ad7837d95ba551ed528cb285d2b47
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Wed Dec 23 14:15:46 2020 -0500

    TINKERPOP-2447 Help users understand StackOverflowError
    
    For the Console present a detailed error message of what might be wrong and for the server add a "Tuning" bullet point that mentions -Xss. CTR
---
 docs/src/reference/gremlin-applications.asciidoc            |  5 +++++
 .../org/apache/tinkerpop/gremlin/console/Console.groovy     | 13 +++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc
index 1e2a037..d847140 100644
--- a/docs/src/reference/gremlin-applications.asciidoc
+++ b/docs/src/reference/gremlin-applications.asciidoc
@@ -1696,6 +1696,11 @@ image:gremlin-handdrawn.png[width=120,float=right] Tuning Gremlin Server for a p
 
 * Gremlin Server defaults to a very modest maximum heap size.  Consider increasing this value for non-trivial uses.
 Maximum heap size (`-Xmx`) is defined with the `JAVA_OPTIONS` setting in `gremlin-server.conf`.
+* TinkerPop tends to discourage the use of link:https://tinkerpop.apache.org/docs/x.y.z/recipes/#long-traversals[long traversals]
+as they can introduce performance problems in some cases and in others simply fail with a `StackOverflowError`. Aside
+from restructuring the traversal into multiple commands or stream based inserts, it may sometimes make sense to simply
+increase the stack size of the JVM for Gremlin Server by configuring an `-Xss` setting in `JAVA_OPTIONS` of
+`gremlin-server.conf`.
 * If Gremlin Server is processing scripts or lambdas in bytecode requests, consider fine tuning the JVM's handling of
 the metaspace size. Consider modifying the `-XX:MetaspaceSize`,`-XX:MaxMetaspaceSize`, and related settings given the
 expected workload. More discussion on this topic can be found in the <<parameterized-scripts,Parameterized Scripts>>
diff --git a/gremlin-console/src/main/groovy/org/apache/tinkerpop/gremlin/console/Console.groovy b/gremlin-console/src/main/groovy/org/apache/tinkerpop/gremlin/console/Console.groovy
index 3dd8e69..c47bbf3 100644
--- a/gremlin-console/src/main/groovy/org/apache/tinkerpop/gremlin/console/Console.groovy
+++ b/gremlin-console/src/main/groovy/org/apache/tinkerpop/gremlin/console/Console.groovy
@@ -354,6 +354,19 @@ class Console {
                     io.err.println(Colorizer.render(Preferences.errorColor,e))
                 }
 
+                // provide a hint in the case of a stackoverflow as it can be common when running large Gremlin
+                // scripts and it isn't immediately apparent what the error might mean in this context especially
+                // if the user isn't familiar with the JVM. it really can only be a hint since we can't be completely
+                // sure it arose as a result of a long Gremlin traversal.
+                if (err instanceof StackOverflowError) {
+                    io.err.println(Colorizer.render(Preferences.errorColor,
+                            "A StackOverflowError can indicate that the Gremlin traversal being executed is too long. If " +
+                                    "you have a single Gremlin statement that is \"long\", you may break it up into " +
+                                    "multiple separate commands, re-write the traversal to operate on a stream of " +
+                                    "input via inject() rather than literals, or attempt to increase the -Xss setting" +
+                                    "of the Gremlin Console by modifying gremlin.sh."));
+                }
+
                 if (interactive) {
                     io.err.println(Colorizer.render(Preferences.infoColor,"Type ':help' or ':h' for help."))
                     io.err.print(Colorizer.render(Preferences.errorColor, "Display stack trace? [yN]"))