Module storm.java
Package st.orm.template

Class SqlLog

java.lang.Object
st.orm.template.SqlLog
public final class SqlLog extends Object
Records the statements a call executes, so a unit of work can be judged by what it cost the database.

A scope covers whatever executes inside it, whichever repository, query builder or template issued the statement, so it can wrap the handling of a request rather than a single repository:


 try (var scope = SqlLog.open("getOwner")) {
     ownerService.load(id);
 }

The summary reports through the st.orm.sql.perf logger when the scope closes, and the logger is the only switch: statements are recorded only while it is enabled at INFO, and at TRACE the full statement texts follow the summary. What a scope observed is a report, not an API: production numbers belong to the Micrometer observations, and test assertions to SqlCapture.

Cost when inactive is zero. A scope registers on the interceptor chain that every statement already walks, so a statement executed with no scope open reads a single counter and stops.

A scope follows the thread that opened it. Work handed to another thread, including a subtask forked from a StructuredTaskScope, falls outside it.

How summaries render — hydration shapes, line width, call-site skips — is a property of the deployment, configured rather than programmed: the storm.sql_log.hydration, storm.sql_log.line_width and storm.sql_log.call_site_skip system properties on a plain JVM, or the corresponding keys of the Spring and Ktor integrations.

Since:
1.13

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    SqlLog.Scope
    A scope opened with open(java.lang.String), reporting its summary once closed.

  • Method Summary

    Modifier and Type
    Method
    Description
    static SqlLog.Scope
    open(String name)
    Opens a scope on the calling thread, closed with try-with-resources.
    static SqlLog.Scope
    open(String name, int limit)
    Opens a scope on the calling thread, recording up to limit statements.
    static SqlLog.Scope
    open(String name, int limit, boolean callSites)
    Opens a scope that additionally attributes each execution to the application frame that caused it, which costs a stack walk per execution while the scope records.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • open

      public static SqlLog.Scope open(String name)
      Opens a scope on the calling thread, closed with try-with-resources. 
      
 try (var scope = SqlLog.open("importOwners")) {
     ownerService.importAll(batch);
 }

      The scope must be closed on the thread that opened it, which a try-with-resources block guarantees. Closing reports the summary under st.orm.sql.perf; a scope whose summary nothing consumes, because that logger is disabled, records nothing.

      Parameters:
      name - what the scope covers, used to label the summary.
      Returns:
      the open scope.

    • open

      public static SqlLog.Scope open(String name, int limit)
      Opens a scope on the calling thread, recording up to limit statements.
      Parameters:
      name - what the scope covers, used to label the summary.
      limit - the number of statements to record; the summary counts the rest regardless.
      Returns:
      the open scope.

    • open

      public static SqlLog.Scope open(String name, int limit, boolean callSites)
      Opens a scope that additionally attributes each execution to the application frame that caused it, which costs a stack walk per execution while the scope records.
      Parameters:
      name - what the scope covers, used to label the summary.
      limit - the number of statements to record; the summary counts the rest regardless.
      callSites - whether to record call sites.
      Returns:
      the open scope.