Adds traceMode evaluator setting to support trace() pretty printing (#1100)

bench/src/jmh/java/org/pkl/core/ListSort.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -51,7 +51,8 @@ public class ListSort {
           null,
           IoUtils.getCurrentWorkingDir(),
           StackFrameTransformers.defaultTransformer,
-          false);
+          false,
+          null);
   private static final List<Object> list = new ArrayList<>(100000);
 
   static {

docs/src/test/kotlin/DocSnippetTests.kt

@@ -97,6 +97,7 @@ class DocSnippetTestsEngine : HierarchicalTestEngine<DocSnippetTestsEngine.Execu
       IoUtils.getCurrentWorkingDir(),
       StackFrameTransformers.defaultTransformer,
       false,
+      null
     )
     return ExecutionContext(replServer)
   }

pkl-cli/src/main/kotlin/org/pkl/cli/CliRepl.kt

@@ -68,6 +68,7 @@ internal class CliRepl(private val options: CliEvaluatorOptions) : CliCommand(op
           options.base.normalizedWorkingDir,
           stackFrameTransformer,
           options.base.color?.hasColor() ?: false,
+          options.base.traceMode,
         )
       Repl(options.base.normalizedWorkingDir, server).run()
     }

pkl-cli/src/test/kotlin/org/pkl/cli/repl/ReplMessagesTest.kt

@@ -43,6 +43,7 @@ class ReplMessagesTest {
       "/".toPath(),
       StackFrameTransformers.defaultTransformer,
       false,
+      null,
     )
 
   @Test

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliBaseOptions.kt

@@ -22,6 +22,7 @@ import java.time.Duration
 import java.util.regex.Pattern
 import org.pkl.core.evaluatorSettings.Color
 import org.pkl.core.evaluatorSettings.PklEvaluatorSettings.ExternalReader
+import org.pkl.core.evaluatorSettings.TraceMode
 import org.pkl.core.module.ProjectDependenciesManager
 import org.pkl.core.util.IoUtils
 
@@ -148,6 +149,9 @@ data class CliBaseOptions(
 
   /** External resource reader process specs */
   val externalResourceReaders: Map<String, ExternalReader> = mapOf(),
+
+  /** Defines options for the formatting of calls to the trace() method. */
+  val traceMode: TraceMode? = null,
 ) {
 
   companion object {

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/BaseOptions.kt

@@ -33,6 +33,7 @@ import org.pkl.commons.cli.CliException
 import org.pkl.commons.shlex
 import org.pkl.core.evaluatorSettings.Color
 import org.pkl.core.evaluatorSettings.PklEvaluatorSettings.ExternalReader
+import org.pkl.core.evaluatorSettings.TraceMode
 import org.pkl.core.runtime.VmUtils
 import org.pkl.core.util.IoUtils
 
@@ -294,6 +295,17 @@ class BaseOptions : OptionGroup() {
       .multiple()
       .toMap()
 
+  val traceMode: TraceMode by
+    option(
+        names = arrayOf("--trace-mode"),
+        metavar = "when",
+        help =
+          "Specifies how calls to trace() are formatted. Possible values of <when> are 'default', 'pretty' and 'hidden'.",
+      )
+      .enum<TraceMode> { it.name.lowercase() }
+      .single()
+      .default(TraceMode.DEFAULT)
+
   // hidden option used by native tests
   private val testPort: Int by
     option(names = arrayOf("--test-port"), help = "Internal test option", hidden = true)
@@ -331,6 +343,7 @@ class BaseOptions : OptionGroup() {
       httpRewrites = httpRewrites.ifEmpty { null },
       externalModuleReaders = externalModuleReaders,
       externalResourceReaders = externalResourceReaders,
+      traceMode = traceMode,
     )
   }
 }

pkl-core/src/main/java/org/pkl/core/Analyzer.java

@@ -22,6 +22,7 @@ import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 import org.graalvm.polyglot.Context;
+import org.pkl.core.evaluatorSettings.TraceMode;
 import org.pkl.core.http.HttpClient;
 import org.pkl.core.http.HttpClientInitException;
 import org.pkl.core.module.ModuleKeyFactory;
@@ -46,6 +47,7 @@ public class Analyzer {
   private final @Nullable DeclaredDependencies projectDependencies;
   private final ModuleResolver moduleResolver;
   private final HttpClient httpClient;
+  private final TraceMode traceMode;
 
   public Analyzer(
       StackFrameTransformer transformer,
@@ -54,7 +56,8 @@ public class Analyzer {
       Collection<ModuleKeyFactory> moduleKeyFactories,
       @Nullable Path moduleCacheDir,
       @Nullable DeclaredDependencies projectDependencies,
-      HttpClient httpClient) {
+      HttpClient httpClient,
+      @Nullable TraceMode traceMode) {
     this.transformer = transformer;
     this.color = color;
     this.securityManager = securityManager;
@@ -62,6 +65,7 @@ public class Analyzer {
     this.projectDependencies = projectDependencies;
     this.moduleResolver = new ModuleResolver(moduleKeyFactories);
     this.httpClient = httpClient;
+    this.traceMode = traceMode;
   }
 
   /**
@@ -115,7 +119,8 @@ public class Analyzer {
                   projectDependencies == null
                       ? null
                       : new ProjectDependenciesManager(
-                          projectDependencies, moduleResolver, securityManager)));
+                          projectDependencies, moduleResolver, securityManager),
+                  traceMode));
         });
   }
 }

pkl-core/src/main/java/org/pkl/core/EvaluatorBuilder.java

@@ -21,6 +21,7 @@ import java.util.*;
 import java.util.regex.Pattern;
 import org.pkl.core.SecurityManagers.StandardBuilder;
 import org.pkl.core.evaluatorSettings.PklEvaluatorSettings.ExternalReader;
+import org.pkl.core.evaluatorSettings.TraceMode;
 import org.pkl.core.externalreader.ExternalReaderProcess;
 import org.pkl.core.http.HttpClient;
 import org.pkl.core.module.ModuleKeyFactories;
@@ -67,6 +68,8 @@ public final class EvaluatorBuilder {
 
   private @Nullable DeclaredDependencies dependencies;
 
+  private @Nullable TraceMode traceMode;
+
   private EvaluatorBuilder() {}
 
   /**
@@ -454,6 +457,17 @@ public final class EvaluatorBuilder {
     return this.dependencies;
   }
 
+  /** Sets whether calls to trace() produce indented, multi-line output. */
+  public EvaluatorBuilder setTraceMode(TraceMode traceMode) {
+    this.traceMode = traceMode;
+    return this;
+  }
+
+  /** Returns whether calls to trace() produce indented, multi-line output. */
+  public TraceMode getTraceMode() {
+    return this.traceMode;
+  }
+
   /**
    * Given a project, sets its dependencies, and also applies any evaluator settings if set.
    *
@@ -517,6 +531,7 @@ public final class EvaluatorBuilder {
                 procs.computeIfAbsent(entry.getValue(), ExternalReaderProcess::of)));
       }
     }
+
     if (settings.http() != null) {
       var httpClientBuilder = HttpClient.builder();
       if (settings.http().proxy() != null) {
@@ -531,6 +546,11 @@ public final class EvaluatorBuilder {
       }
       setHttpClient(httpClientBuilder.buildLazily());
     }
+
+    if (settings.traceMode() != null) {
+      setTraceMode(settings.traceMode());
+    }
+
     return this;
   }
 
@@ -557,6 +577,7 @@ public final class EvaluatorBuilder {
         timeout,
         moduleCacheDir,
         dependencies,
-        outputFormat);
+        outputFormat,
+        traceMode);
   }
 }

pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java

@@ -30,6 +30,7 @@ import java.util.function.Supplier;
 import org.graalvm.polyglot.Context;
 import org.pkl.core.ast.ConstantValueNode;
 import org.pkl.core.ast.internal.ToStringNodeGen;
+import org.pkl.core.evaluatorSettings.TraceMode;
 import org.pkl.core.http.HttpClient;
 import org.pkl.core.module.ModuleKeyFactory;
 import org.pkl.core.module.ProjectDependenciesManager;
@@ -80,7 +81,8 @@ public class EvaluatorImpl implements Evaluator {
       @Nullable Duration timeout,
       @Nullable Path moduleCacheDir,
       @Nullable DeclaredDependencies projectDependencies,
-      @Nullable String outputFormat) {
+      @Nullable String outputFormat,
+      @Nullable TraceMode traceMode) {
 
     securityManager = manager;
     frameTransformer = transformer;
@@ -108,7 +110,8 @@ public class EvaluatorImpl implements Evaluator {
                       projectDependencies == null
                           ? null
                           : new ProjectDependenciesManager(
-                              projectDependencies, moduleResolver, securityManager)));
+                              projectDependencies, moduleResolver, securityManager),
+                      traceMode));
             });
     this.timeout = timeout;
     // NOTE: would probably make sense to share executor between evaluators

pkl-core/src/main/java/org/pkl/core/ast/expression/unary/TraceNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,12 +19,17 @@ import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.source.SourceSection;
 import org.pkl.core.ast.ExpressionNode;
+import org.pkl.core.evaluatorSettings.TraceMode;
 import org.pkl.core.runtime.*;
 
 public final class TraceNode extends ExpressionNode {
   @Child private ExpressionNode valueNode;
 
-  private final VmValueRenderer renderer = VmValueRenderer.singleLine(1000000);
+  private static final int MAX_RENDERER_LENGTH = 1000000;
+
+  private final VmValueRenderer singleLineRenderer =
+      VmValueRenderer.singleLine(MAX_RENDERER_LENGTH);
+  private final VmValueRenderer multiLineRenderer = VmValueRenderer.multiLine(MAX_RENDERER_LENGTH);
 
   public TraceNode(SourceSection sourceSection, ExpressionNode valueNode) {
     super(sourceSection);
@@ -40,6 +45,10 @@ public final class TraceNode extends ExpressionNode {
 
   @TruffleBoundary
   private void doTrace(Object value, VmContext context) {
+    // If traces are disabled, returns early.
+    if (context.getTraceMode() == TraceMode.HIDDEN) {
+      return;
+    }
     if (value instanceof VmObjectLike objectLike) {
       try {
         objectLike.force(true, true);
@@ -48,7 +57,12 @@ public final class TraceNode extends ExpressionNode {
     }
 
     var sourceSection = valueNode.getSourceSection();
-    var renderedValue = renderer.render(value);
+    String renderedValue;
+    if (context.getTraceMode() == TraceMode.PRETTY) {
+      renderedValue = multiLineRenderer.render(value);
+    } else {
+      renderedValue = singleLineRenderer.render(value);
+    }
     var message =
         (sourceSection.isAvailable() ? sourceSection.getCharacters() : "<value")
             + " = "

pkl-core/src/main/java/org/pkl/core/evaluatorSettings/PklEvaluatorSettings.java

@@ -50,7 +50,8 @@ public record PklEvaluatorSettings(
     @Nullable Path rootDir,
     @Nullable Http http,
     @Nullable Map<String, ExternalReader> externalModuleReaders,
-    @Nullable Map<String, ExternalReader> externalResourceReaders) {
+    @Nullable Map<String, ExternalReader> externalResourceReaders,
+    @Nullable TraceMode traceMode) {
 
   /** Initializes a {@link PklEvaluatorSettings} from a raw object representation. */
   @SuppressWarnings("unchecked")
@@ -106,6 +107,7 @@ public record PklEvaluatorSettings(
                         Entry::getKey, entry -> ExternalReader.parse(entry.getValue())));
 
     var color = (String) pSettings.get("color");
+    var traceMode = (String) pSettings.get("traceMode");
 
     return new PklEvaluatorSettings(
         (Map<String, String>) pSettings.get("externalProperties"),
@@ -120,7 +122,8 @@ public record PklEvaluatorSettings(
         rootDir,
         Http.parse((Value) pSettings.get("http")),
         externalModuleReaders,
-        externalResourceReaders);
+        externalResourceReaders,
+        traceMode == null ? null : TraceMode.valueOf(traceMode.toUpperCase()));
   }
 
   public record Http(@Nullable Proxy proxy, @Nullable Map<URI, URI> rewrites) {
@@ -231,7 +234,8 @@ public record PklEvaluatorSettings(
         && Objects.equals(moduleCacheDir, that.moduleCacheDir)
         && Objects.equals(timeout, that.timeout)
         && Objects.equals(rootDir, that.rootDir)
-        && Objects.equals(http, that.http);
+        && Objects.equals(http, that.http)
+        && Objects.equals(traceMode, that.traceMode);
   }
 
   private int hashPatterns(@Nullable List<Pattern> patterns) {
@@ -249,7 +253,15 @@ public record PklEvaluatorSettings(
   public int hashCode() {
     var result =
         Objects.hash(
-            externalProperties, env, color, noCache, moduleCacheDir, timeout, rootDir, http);
+            externalProperties,
+            env,
+            color,
+            noCache,
+            moduleCacheDir,
+            timeout,
+            rootDir,
+            http,
+            traceMode);
     result = 31 * result + hashPatterns(allowedModules);
     result = 31 * result + hashPatterns(allowedResources);
     return result;

pkl-core/src/main/java/org/pkl/core/evaluatorSettings/TraceMode.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core.evaluatorSettings;
+
+/** Dictates the rendering of calls to the trace() method within Pkl. */
+public enum TraceMode {
+  /** All trace() calls will not be emitted to stderr. */
+  HIDDEN,
+  /** All structures passed to trace() will be emitted on a single line. */
+  DEFAULT,
+  /** All structures passed to trace() will be indented and emitted across multiple lines. */
+  PRETTY
+}

pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackEncoder.java

@@ -79,7 +79,8 @@ public abstract class AbstractMessagePackEncoder implements MessageEncoder {
       @Nullable Object valueC,
       @Nullable Object valueD,
       @Nullable Object valueE,
-      @Nullable Object valueF)
+      @Nullable Object valueF,
+      @Nullable Object valueG)
       throws IOException {
     packer.packMapHeader(
         size
@@ -97,7 +98,8 @@ public abstract class AbstractMessagePackEncoder implements MessageEncoder {
             + (valueC != null ? 1 : 0)
             + (valueD != null ? 1 : 0)
             + (valueE != null ? 1 : 0)
-            + (valueF != null ? 1 : 0));
+            + (valueF != null ? 1 : 0)
+            + (valueG != null ? 1 : 0));
   }
 
   protected void packKeyValue(String name, @Nullable Integer value) throws IOException {

pkl-core/src/main/java/org/pkl/core/project/Project.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,6 +43,7 @@ import org.pkl.core.StackFrameTransformers;
 import org.pkl.core.Value;
 import org.pkl.core.Version;
 import org.pkl.core.evaluatorSettings.PklEvaluatorSettings;
+import org.pkl.core.evaluatorSettings.TraceMode;
 import org.pkl.core.module.ModuleKeyFactories;
 import org.pkl.core.packages.Checksums;
 import org.pkl.core.packages.Dependency.RemoteDependency;
@@ -197,7 +198,8 @@ public final class Project {
             builder.getModuleKeyFactories(),
             builder.getModuleCacheDir(),
             builder.getProjectDependencies(),
-            builder.getHttpClient());
+            builder.getHttpClient(),
+            builder.getTraceMode());
     var importGraph = analyzer.importGraph(moduleSource.getUri());
     var ret = ImportGraphUtils.findImportCycles(importGraph);
     // we only care about cycles in the same scheme as `moduleSource`
@@ -511,7 +513,8 @@ public final class Project {
         @Nullable Path moduleCacheDir,
         @Nullable List<Path> modulePath,
         @Nullable Duration timeout,
-        @Nullable Path rootDir) {
+        @Nullable Path rootDir,
+        @Nullable TraceMode traceMode) {
       this.delegate =
           new PklEvaluatorSettings(
               externalProperties,
@@ -526,7 +529,8 @@ public final class Project {
               rootDir,
               null,
               null,
-              null);
+              null,
+              traceMode);
     }
 
     @Deprecated(forRemoval = true)
@@ -610,6 +614,8 @@ public final class Project {
           + delegate.timeout()
           + ", rootDir="
           + delegate.rootDir()
+          + ", traceMode="
+          + delegate.traceMode()
           + '}';
     }
   }

pkl-core/src/main/java/org/pkl/core/repl/ReplServer.java

@@ -32,6 +32,7 @@ import org.pkl.core.ast.builder.AstBuilder;
 import org.pkl.core.ast.member.*;
 import org.pkl.core.ast.repl.ResolveClassMemberNode;
 import org.pkl.core.ast.type.TypeNode;
+import org.pkl.core.evaluatorSettings.TraceMode;
 import org.pkl.core.http.HttpClient;
 import org.pkl.core.module.*;
 import org.pkl.core.packages.PackageResolver;
@@ -82,7 +83,8 @@ public class ReplServer implements AutoCloseable {
       @Nullable String outputFormat,
       Path workingDir,
       StackFrameTransformer frameTransformer,
-      boolean color) {
+      boolean color,
+      @Nullable TraceMode traceMode) {
 
     this.workingDir = workingDir;
     this.securityManager = securityManager;
@@ -114,7 +116,8 @@ public class ReplServer implements AutoCloseable {
                       moduleCacheDir,
                       outputFormat,
                       packageResolver,
-                      projectDependenciesManager));
+                      projectDependenciesManager,
+                      traceMode));
             });
     language = languageRef.get();
   }

pkl-core/src/main/java/org/pkl/core/runtime/StdLibModule.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -49,6 +49,7 @@ public abstract class StdLibModule {
                       null,
                       null,
                       null,
+                      null,
                       null));
               var language = VmLanguage.get(null);
               var moduleKey = ModuleKeys.standardLibrary(uri);

pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@ import java.util.Map;
 import org.pkl.core.Logger;
 import org.pkl.core.SecurityManager;
 import org.pkl.core.StackFrameTransformer;
+import org.pkl.core.evaluatorSettings.TraceMode;
 import org.pkl.core.http.HttpClient;
 import org.pkl.core.module.ProjectDependenciesManager;
 import org.pkl.core.packages.PackageResolver;
@@ -50,6 +51,7 @@ public final class VmContext {
     private final ModuleCache moduleCache;
     private final @Nullable PackageResolver packageResolver;
     private final @Nullable ProjectDependenciesManager projectDependenciesManager;
+    private final TraceMode traceMode;
 
     public Holder(
         StackFrameTransformer frameTransformer,
@@ -63,7 +65,8 @@ public final class VmContext {
         @Nullable Path moduleCacheDir,
         @Nullable String outputFormat,
         @Nullable PackageResolver packageResolver,
-        @Nullable ProjectDependenciesManager projectDependenciesManager) {
+        @Nullable ProjectDependenciesManager projectDependenciesManager,
+        @Nullable TraceMode traceMode) {
 
       this.frameTransformer = frameTransformer;
       this.securityManager = securityManager;
@@ -84,6 +87,7 @@ public final class VmContext {
       moduleCache = new ModuleCache();
       this.packageResolver = packageResolver;
       this.projectDependenciesManager = projectDependenciesManager;
+      this.traceMode = traceMode;
     }
   }
 
@@ -143,4 +147,8 @@ public final class VmContext {
   public @Nullable ProjectDependenciesManager getProjectDependenciesManager() {
     return holder.projectDependenciesManager;
   }
+
+  public @Nullable TraceMode getTraceMode() {
+    return holder.traceMode;
+  }
 }

pkl-core/src/test/files/LanguageSnippetTests/input/projects/defaultTraceMode/PklProject

@@ -0,0 +1,5 @@
+amends "pkl:Project"
+
+evaluatorSettings {
+  traceMode = "default"
+}

pkl-core/src/test/files/LanguageSnippetTests/input/projects/defaultTraceMode/defaultTraceMode.pkl

@@ -0,0 +1,18 @@
+amends ".../snippetTest.pkl"
+
+examples {
+  ["traceMode = 'default' results in single-line trace() values"] {
+    trace(new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings = new {
+          kicked = true
+          ["fjordConfig"] = new {
+            isPining = true
+          }
+        }
+      }
+    })
+  }
+}

pkl-core/src/test/files/LanguageSnippetTests/input/projects/evaluatorSettings/nullTraceMode.pkl

@@ -0,0 +1,18 @@
+amends ".../snippetTest.pkl"
+
+examples {
+  ["traceMode = null results in single-line trace() values"] {
+    trace(new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings = new {
+          kicked = true
+          ["fjordConfig"] = new {
+            isPining = true
+          }
+        }
+      }
+    })
+  }
+}

pkl-core/src/test/files/LanguageSnippetTests/input/projects/hiddenTraceMode/PklProject

@@ -0,0 +1,5 @@
+amends "pkl:Project"
+
+evaluatorSettings {
+  traceMode = "hidden"
+}

pkl-core/src/test/files/LanguageSnippetTests/input/projects/hiddenTraceMode/hiddenTraceMode.pkl

@@ -0,0 +1,18 @@
+amends ".../snippetTest.pkl"
+
+examples {
+  ["traceMode = 'hidden' results in no trace output"] {
+    trace(new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings = new {
+          kicked = true
+          ["fjordConfig"] = new {
+            isPining = true
+          }
+        }
+      }
+    })
+  }
+}

pkl-core/src/test/files/LanguageSnippetTests/input/projects/prettyTraceMode/PklProject

@@ -0,0 +1,5 @@
+amends "pkl:Project"
+
+evaluatorSettings {
+  traceMode = "pretty"
+}

pkl-core/src/test/files/LanguageSnippetTests/input/projects/prettyTraceMode/prettyTraceMode.pkl

@@ -0,0 +1,18 @@
+amends ".../snippetTest.pkl"
+
+examples {
+  ["traceMode = 'pretty' results in indented, multi-line output"] {
+    trace(new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings = new {
+          kicked = true
+          ["fjordConfig"] = new {
+            isPining = true
+          }
+        }
+      }
+    })
+  }
+}

pkl-core/src/test/files/LanguageSnippetTests/output/projects/defaultTraceMode/defaultTraceMode.err

@@ -0,0 +1,28 @@
+examples {
+  ["traceMode = 'default' results in single-line trace() values"] {
+    new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings {
+          kicked = true
+          ["fjordConfig"] {
+            isPining = true
+          }
+        }
+      }
+    }
+  }
+}
+pkl: TRACE: new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings = new {
+          kicked = true
+          ["fjordConfig"] = new {
+            isPining = true
+          }
+        }
+      }
+    } = new Dynamic { ["Parrot"] { name = "Parrot"; age = 1234; bucketSettings { kicked = true; ["fjordConfig"] { isPining = true } } } } (file:///$snippetsDir/input/projects/defaultTraceMode/defaultTraceMode.pkl)

pkl-core/src/test/files/LanguageSnippetTests/output/projects/evaluatorSettings/nullTraceMode.err

@@ -0,0 +1,28 @@
+examples {
+  ["traceMode = null results in single-line trace() values"] {
+    new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings {
+          kicked = true
+          ["fjordConfig"] {
+            isPining = true
+          }
+        }
+      }
+    }
+  }
+}
+pkl: TRACE: new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings = new {
+          kicked = true
+          ["fjordConfig"] = new {
+            isPining = true
+          }
+        }
+      }
+    } = new Dynamic { ["Parrot"] { name = "Parrot"; age = 1234; bucketSettings { kicked = true; ["fjordConfig"] { isPining = true } } } } (file:///$snippetsDir/input/projects/evaluatorSettings/nullTraceMode.pkl)

pkl-core/src/test/files/LanguageSnippetTests/output/projects/hiddenTraceMode/hiddenTraceMode.pcf

@@ -0,0 +1,16 @@
+examples {
+  ["traceMode = 'hidden' results in no trace output"] {
+    new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings {
+          kicked = true
+          ["fjordConfig"] {
+            isPining = true
+          }
+        }
+      }
+    }
+  }
+}

pkl-core/src/test/files/LanguageSnippetTests/output/projects/prettyTraceMode/prettyTraceMode.err

@@ -0,0 +1,39 @@
+examples {
+  ["traceMode = 'pretty' results in indented, multi-line output"] {
+    new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings {
+          kicked = true
+          ["fjordConfig"] {
+            isPining = true
+          }
+        }
+      }
+    }
+  }
+}
+pkl: TRACE: new {
+      ["Parrot"] {
+        name = "Parrot"
+        age = 1234
+        bucketSettings = new {
+          kicked = true
+          ["fjordConfig"] = new {
+            isPining = true
+          }
+        }
+      }
+    } = new Dynamic {
+  ["Parrot"] {
+    name = "Parrot"
+    age = 1234
+    bucketSettings {
+      kicked = true
+      ["fjordConfig"] {
+        isPining = true
+      }
+    }
+  }
+} (file:///$snippetsDir/input/projects/prettyTraceMode/prettyTraceMode.pkl)

pkl-core/src/test/kotlin/org/pkl/core/AnalyzerTest.kt

@@ -37,6 +37,7 @@ class AnalyzerTest {
       null,
       null,
       HttpClient.dummyClient(),
+      null,
     )
 
   @Test
@@ -115,6 +116,7 @@ class AnalyzerTest {
         tempDir.resolve("packages"),
         null,
         HttpClient.dummyClient(),
+        null,
       )
     PackageServer.populateCacheDir(tempDir.resolve("packages"))
     val file1 =
@@ -190,6 +192,7 @@ class AnalyzerTest {
         tempDir.resolve("packages"),
         project.dependencies,
         HttpClient.dummyClient(),
+        null,
       )
     val file1 =
       tempDir
@@ -302,6 +305,7 @@ class AnalyzerTest {
         tempDir.resolve("packages"),
         project.dependencies,
         HttpClient.dummyClient(),
+        null,
       )
     val result = analyzer.importGraph(mainPkl.toUri())
     val birdUri = URI("projectpackage://localhost:0/birds@1.0.0#/bird.pkl")

pkl-core/src/test/kotlin/org/pkl/core/ReplServerTest.kt

@@ -45,6 +45,7 @@ class ReplServerTest {
       "/".toPath(),
       StackFrameTransformers.defaultTransformer,
       false,
+      null,
     )
 
   @Test

pkl-core/src/test/kotlin/org/pkl/core/project/ProjectTest.kt

@@ -74,6 +74,7 @@ class ProjectTest {
         null,
         null,
         null,
+        null,
       )
     val expectedAnnotations =
       listOf(

pkl-gradle/src/main/java/org/pkl/gradle/task/BasePklTask.java

@@ -201,7 +201,8 @@ public abstract class BasePklTask extends DefaultTask {
               getHttpNoProxy().getOrElse(List.of()),
               getHttpRewrites().getOrNull(),
               Map.of(),
-              Map.of());
+              Map.of(),
+              null);
     }
     return cachedOptions;
   }

pkl-gradle/src/main/java/org/pkl/gradle/task/ModulesTask.java

@@ -165,7 +165,8 @@ public abstract class ModulesTask extends BasePklTask {
               List.of(),
               getHttpRewrites().getOrNull(),
               Map.of(),
-              Map.of());
+              Map.of(),
+              null);
     }
     return cachedOptions;
   }

pkl-server/src/main/kotlin/org/pkl/server/BinaryEvaluator.kt

@@ -20,6 +20,7 @@ import java.time.Duration
 import org.msgpack.core.MessagePacker
 import org.pkl.core.*
 import org.pkl.core.ast.member.ObjectMember
+import org.pkl.core.evaluatorSettings.TraceMode
 import org.pkl.core.http.HttpClient
 import org.pkl.core.module.ModuleKeyFactory
 import org.pkl.core.project.DeclaredDependencies
@@ -39,6 +40,7 @@ internal class BinaryEvaluator(
   moduleCacheDir: Path?,
   declaredDependencies: DeclaredDependencies?,
   outputFormat: String?,
+  traceMode: TraceMode?,
 ) :
   EvaluatorImpl(
     transformer,
@@ -54,6 +56,7 @@ internal class BinaryEvaluator(
     moduleCacheDir,
     declaredDependencies,
     outputFormat,
+    traceMode,
   ) {
   fun evaluate(moduleSource: ModuleSource, expression: String?): ByteArray {
     return doEvaluate(moduleSource) { module ->

pkl-server/src/main/kotlin/org/pkl/server/Server.kt

@@ -227,6 +227,7 @@ class Server(private val transport: MessageTransport) : AutoCloseable {
         cacheDir,
         dependencies,
         message.outputFormat,
+        message.traceMode,
       )
     } catch (e: IllegalArgumentException) {
       throw ProtocolException(e.message ?: "Failed to create an evalutor. $e", e)

pkl-server/src/main/kotlin/org/pkl/server/ServerMessagePackDecoder.kt

@@ -22,6 +22,7 @@ import java.time.Duration
 import org.msgpack.core.MessagePack
 import org.msgpack.core.MessageUnpacker
 import org.msgpack.value.Value
+import org.pkl.core.evaluatorSettings.TraceMode
 import org.pkl.core.messaging.BaseMessagePackDecoder
 import org.pkl.core.messaging.Message
 import org.pkl.core.packages.Checksums
@@ -50,6 +51,7 @@ class ServerMessagePackDecoder(unpacker: MessageUnpacker) : BaseMessagePackDecod
           map.unpackHttp(),
           unpackStringMapOrNull(map, "externalModuleReaders", ::unpackExternalReader),
           unpackStringMapOrNull(map, "externalResourceReaders", ::unpackExternalReader),
+          unpackStringOrNull(map, "traceMode") { TraceMode.valueOf(it.uppercase()) },
         )
       Message.Type.CREATE_EVALUATOR_RESPONSE ->
         CreateEvaluatorResponse(

pkl-server/src/main/kotlin/org/pkl/server/ServerMessagePackEncoder.kt

@@ -110,6 +110,7 @@ class ServerMessagePackEncoder(packer: MessagePacker) : BaseMessagePackEncoder(p
           msg.http,
           msg.externalModuleReaders,
           msg.externalResourceReaders,
+          msg.traceMode,
         )
         packKeyValue("requestId", msg.requestId())
         packKeyValue("allowedModules", msg.allowedModules)
@@ -159,6 +160,9 @@ class ServerMessagePackEncoder(packer: MessagePacker) : BaseMessagePackEncoder(p
             packExternalReader(spec)
           }
         }
+        if (msg.traceMode != null) {
+          packKeyValue("traceMode", msg.traceMode.toString())
+        }
         return
       }
       Message.Type.CREATE_EVALUATOR_RESPONSE -> {

pkl-server/src/main/kotlin/org/pkl/server/ServerMessages.kt

@@ -19,6 +19,7 @@ import java.net.URI
 import java.nio.file.Path
 import java.time.Duration
 import java.util.*
+import org.pkl.core.evaluatorSettings.TraceMode
 import org.pkl.core.messaging.Message
 import org.pkl.core.messaging.Messages
 import org.pkl.core.packages.Checksums
@@ -40,6 +41,7 @@ data class CreateEvaluatorRequest(
   val http: Http?,
   val externalModuleReaders: Map<String, ExternalReader>?,
   val externalResourceReaders: Map<String, ExternalReader>?,
+  val traceMode: TraceMode?,
 ) : Message.Client.Request {
 
   override fun type(): Message.Type = Message.Type.CREATE_EVALUATOR_REQUEST

pkl-server/src/test/kotlin/org/pkl/server/AbstractServerTest.kt

@@ -78,6 +78,7 @@ abstract class AbstractServerTest {
       project = null,
       externalModuleReaders = null,
       externalResourceReaders = null,
+      traceMode = null,
     )
 
   @Test
@@ -1025,6 +1026,7 @@ abstract class AbstractServerTest {
         http,
         null,
         null,
+        null,
       )
 
     send(message)

pkl-server/src/test/kotlin/org/pkl/server/BinaryEvaluatorSnippetTests.kt

@@ -56,6 +56,7 @@ class BinaryEvaluatorSnippetTestEngine : InputOutputTestEngine() {
       null,
       null,
       null,
+      null,
     )
 
   private fun String.stripFilePaths() =

pkl-server/src/test/kotlin/org/pkl/server/BinaryEvaluatorTest.kt

@@ -45,6 +45,7 @@ class BinaryEvaluatorTest {
       null,
       null,
       null,
+      null,
     )
 
   private fun evaluate(text: String, expression: String?) =

pkl-server/src/test/kotlin/org/pkl/server/ServerMessagePackCodecTest.kt

@@ -23,6 +23,7 @@ import java.time.Duration
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
 import org.msgpack.core.MessagePack
+import org.pkl.core.evaluatorSettings.TraceMode
 import org.pkl.core.messaging.Message
 import org.pkl.core.messaging.MessageDecoder
 import org.pkl.core.messaging.MessageEncoder
@@ -100,6 +101,7 @@ class ServerMessagePackCodecTest {
           ),
         externalModuleReaders = mapOf("external" to externalReader, "external2" to externalReader),
         externalResourceReaders = mapOf("external" to externalReader),
+        traceMode = TraceMode.PRETTY,
       )
     )
   }

stdlib/EvaluatorSettings.pkl

@@ -109,6 +109,16 @@ externalModuleReaders: Mapping<String, ExternalReader>?
 @Since { version = "0.27.0" }
 externalResourceReaders: Mapping<String, ExternalReader>?
 
+/// Defines options for the formatting of calls to the trace() method.
+///
+/// Possible values:
+///
+/// - `"hidden"`: All trace() calls will not be emitted to stderr.
+/// - `"default"`: All structures passed to trace() will be emitted on a single line.
+/// - `"pretty"`: All structures passed to trace() will be indented and emitted across multiple lines.
+@Since { version = "0.30.0" }
+traceMode: ("hidden"|"default"|"pretty")?
+
 const local hostnameRegex = Regex(#"https?://([^/?#]*)"#)
 
 const local hasNonEmptyHostname = (it: String) ->