Seeking feedback on tinkerpop gremlin explain and profile from db providers

[andreachild]

Hello Everyone,

I have been looking at the Explain and Profile implementations in Tinkerpop gremlin-core and how to improve the flexibility of its output for Tinkerpop 4.0 for graph db providers.

My questions to the HugeGraph community are:

• is the default Explain and Profile output sufficient?
• have you had difficulty customizing the Explain or Profile implementations?
• can you provide an example of a customized Explain or Profile output that I could reference to help determine how I can improve the current implementation?

For Explain, I am thinking about modifying TraversalExplanation to allow providers to more easily group applied TraversalStrategies into intermediate traversals so that the output can contain the Original Traversal, X-Intermediate Traversals, and then Final Traversal based on how the provider decides to group the strategies.

For Profile, I am wondering if it would be useful to change Metrics from storing data in two maps into a single map, allowing db providers to specify custom metric aggregation logic via BinaryOperator (ie. sum, average, min, max, String concatenation), and then changing toString to dynamically determine the output table headers based on the keys of the metrics map. Or perhaps a more simpler approach would be better to allow injection of additional text before or after the default Profile output.

Thank you

[dosubot[bot]]

Hey @andreachild! 👋 I'm here to help you with any questions, bugs, or contributions while we wait for a human maintainer.

Hello @andreachild,

Here are some insights from the HugeGraph community regarding your questions on Tinkerpop Gremlin's Explain and Profile functionalities:

1. Default Explain and Profile Output Sufficiency:

   • The default Explain and Profile outputs provided by Tinkerpop are generally useful, but there are scenarios where more customization is needed to meet specific requirements.

2. Difficulty in Customizing Explain or Profile Implementations:

   • Customizing the Explain and Profile outputs can be challenging. HugeGraph has implemented its own mechanisms to handle these functionalities, which indicates that the default implementations may not be flexible enough for all use cases.

3. Example of Customized Explain or Profile Output:

   • HugeGraph uses the PerfUtil class to implement Explain and Profile functionalities. This class provides methods to start and end performance monitoring, profile packages and classes, and generate performance data in JSON and ECharts formats. Here is a snippet from the PerfUtil class:

   public Stopwatch start(String name) {
       long start = now();
       Stopwatch parent = this.callStack.empty() ? this.root : this.callStack.peek();
       Stopwatch watch = parent.child(name);
       if (watch == null) {
           watch = newStopwatch(name, parent);
           this.stopwatches.put(watch.id(), watch);
       }
       this.callStack.push(watch);
       watch.startTime(start);
       return watch;
   }
   
   public void end(String name) {
       long start = LIGHT_WATCH ? 0L : now();
       Stopwatch watch = this.callStack.pop();
       if (watch == null || watch.name() != name) {
           throw new IllegalArgumentException("Invalid watch name: " + name);
       }
       watch.endTime(start);
   }
   
   public void profilePackage(String... packages) throws Throwable {
       Set<String> loadedClasses = new HashSet<>();
       Function<String, Boolean> inPackage = (cls) -> {
           for (String pkg : packages) {
               if (cls.startsWith(pkg)) {
                   return true;
               }
           }
           return false;
       };
       ThrowableConsumer<String> profileClassIfPresent = (cls) -> {
           if (!loadedClasses.contains(cls)) {
               for (String s : ReflectionUtil.superClasses(cls)) {
                   if (!loadedClasses.contains(s) && inPackage.apply(s)) {
                       profileClass(s);
                       loadedClasses.add(s);
                   }
               }
               profileClass(cls);
               loadedClasses.add(cls);
           }
       };
       Iterator<ClassInfo> classes = ReflectionUtil.classes(packages);
       while (classes.hasNext()) {
           String cls = classes.next().getName();
           profileClassIfPresent.accept(cls);
           for (String s : ReflectionUtil.nestedClasses(cls)) {
               profileClassIfPresent.accept(s);
           }
       }
   }
   
   public void profileClass(String... classes) throws Throwable {
       ClassPool classPool = ClassPool.getDefault();
       for (String cls : classes) {
           CtClass ctClass = classPool.get(cls);
           List<CtMethod> methods = ReflectionUtil.getMethodsAnnotatedWith(ctClass, Watched.class, false);
           for (CtMethod method : methods) {
               profile(method);
           }
           if (!methods.isEmpty()) {
               ctClass.toClass();
           }
       }
   }
   
   private void profile(CtMethod ctMethod) throws CannotCompileException, ClassNotFoundException {
       final String START = "org.apache.hugegraph.perf.PerfUtil.instance().start(\"%s\");";
       final String END = "org.apache.hugegraph.perf.PerfUtil.instance().end(\"%s\");";
       Watched annotation = (Watched) ctMethod.getAnnotation(Watched.class);
       String name = annotation.value();
       if (name.isEmpty()) {
           name = ctMethod.getName();
       }
       if (!annotation.prefix().isEmpty()) {
           name = annotation.prefix() + "." + name;
       }
       ctMethod.insertBefore(String.format(START, name));
       ctMethod.insertAfter(String.format(END, name), true);
       LOG.debug("Profiled for: '{}' [{}]", name, ctMethod.getLongName());
   }

   This implementation allows for detailed performance monitoring and profiling, which can be customized as needed ^[1].

Your proposed changes to TraversalExplanation and Metrics sound promising and could indeed provide more flexibility for graph database providers. Allowing providers to group applied TraversalStrategies and specify custom metric aggregation logic would likely be beneficial.

Hope this helps!

To continue talking to Dosu, mention @dosu.

[andreachild]

Do you have a sample of output from the Profile or Explain step?

[dosubot[bot]]

Yes, HugeGraph provides examples of profiling and explaining steps in the PerfUtilTest class. Here are some snippets that demonstrate the output of the Profile step:

@Test
public void testPerfUtil() throws Throwable {
    perf.profileClass("org.apache.hugegraph.TestClass$Foo");

    TestClass.Foo obj = new TestClass.Foo();
    obj.foo();

    String json = perf.toJson();

    assertContains(json, "foo.foo#times", 1);
    assertContains(json, "foo.foo#name", "foo.foo");
    // ... other assertions ...
}

@Test
public void testPerfUtilWithSingleThread() throws Throwable {
    perf.profileClass("org.apache.hugegraph.TestClass$Bar");
    PerfUtil.profileSingleThread(true);

    TestClass.Bar obj = new TestClass.Bar();
    obj.foo();
    String json = perf.toJson();

    assertContains(json, "bar_foo#times", 1);
    // ... other assertions ...
}

These tests show how profiling information is collected and verified, providing concrete examples of the output in JSON format ^[1].

Additionally, the ProcessBasicSuite class includes test cases for both the Explain and Profile steps, specifically in the ExplainTest.Traversals and ProfileTest.Traversals classes ^[2].

To continue talking to Dosu, mention @dosu.