Class H2LogStore

java.lang.Object
com.scivicslab.actoriac.log.H2LogStore
All Implemented Interfaces:
DistributedLogStore, AutoCloseable
public class H2LogStore extends Object implements DistributedLogStore
H2 Database implementation of DistributedLogStore.

Uses H2 embedded database for storing logs from distributed workflow execution. Supports concurrent access from multiple threads and provides efficient querying by node, level, and time.

Features:

  • Pure Java - no native dependencies
  • Single file storage (.mv.db)
  • Asynchronous batch writing for performance
  • SQL-based querying
Author:
devteam@scivicslab.com

  • Field Details

  • Constructor Details

    • H2LogStore

      public H2LogStore(Path dbPath) throws SQLException
      Creates an H2LogStore with the specified database path.
      Parameters:
      dbPath - path to the database file (without extension)
      Throws:
      SQLException - if database connection fails

    • H2LogStore

      public H2LogStore() throws SQLException
      Creates an in-memory H2LogStore (for testing).
      Throws:
      SQLException - if database connection fails

  • Method Details

    • getConnection

      public Connection getConnection()
      Gets the database connection for read-only operations.

      This connection is shared and should NOT be closed by the caller. The connection will be closed when the H2LogStore is closed.

      Specified by:
      getConnection in interface DistributedLogStore
      Returns:
      the JDBC connection

    • setTextLogFile

      public void setTextLogFile(Path textLogPath) throws IOException
      Sets the text log file for additional text-based logging.

      When a text log file is set, all log entries written to the database are also appended to this text file in a human-readable format.

      Parameters:
      textLogPath - path to the text log file
      Throws:
      IOException - if the file cannot be opened for writing

    • disableTextLog

      public void disableTextLog()
      Disables text file logging.

    • initSchema

      private void initSchema() throws SQLException
      Throws:
      SQLException

    • initSchema

      public static void initSchema(Connection conn) throws SQLException
      Initializes the log database schema on the given connection.

      This method can be called from external components (e.g., log server) to ensure consistent schema across all database access points.

      Parameters:
      conn - the database connection
      Throws:
      SQLException - if schema initialization fails

    • writerLoop

      private void writerLoop()

    • processBatch

      private void processBatch(List<H2LogStore.LogTask> batch)

    • startSession

      public long startSession(String workflowName, int nodeCount)
      Description copied from interface: DistributedLogStore
      Starts a new workflow execution session.
      Specified by:
      startSession in interface DistributedLogStore
      Parameters:
      workflowName - name of the workflow being executed
      nodeCount - number of nodes participating in this session
      Returns:
      session ID for subsequent log entries

    • startSession

      public long startSession(String workflowName, String overlayName, String inventoryName, int nodeCount)
      Description copied from interface: DistributedLogStore
      Starts a new workflow execution session with overlay and inventory info.
      Specified by:
      startSession in interface DistributedLogStore
      Parameters:
      workflowName - name of the workflow being executed
      overlayName - name of the overlay being used (may be null)
      inventoryName - name of the inventory file being used (may be null)
      nodeCount - number of nodes participating in this session
      Returns:
      session ID for subsequent log entries

    • startSession

      public long startSession(String workflowName, String overlayName, String inventoryName, int nodeCount, String cwd, String gitCommit, String gitBranch, String commandLine, String actorIacVersion, String actorIacCommit)
      Description copied from interface: DistributedLogStore
      Starts a new workflow execution session with full execution context.
      Specified by:
      startSession in interface DistributedLogStore
      Parameters:
      workflowName - name of the workflow being executed
      overlayName - name of the overlay being used (may be null)
      inventoryName - name of the inventory file being used (may be null)
      nodeCount - number of nodes participating in this session
      cwd - current working directory
      gitCommit - git commit hash of the workflow directory (may be null)
      gitBranch - git branch name (may be null)
      commandLine - the command line used to invoke actor-IaC
      actorIacVersion - actor-IaC version
      actorIacCommit - actor-IaC git commit hash (may be null)
      Returns:
      session ID for subsequent log entries

    • log

      public void log(long sessionId, String nodeId, LogLevel level, String message)
      Description copied from interface: DistributedLogStore
      Records a log entry.
      Specified by:
      log in interface DistributedLogStore
      Parameters:
      sessionId - session ID from startSession()
      nodeId - identifier of the node generating this log
      level - log level
      message - log message

    • log

      public void log(long sessionId, String nodeId, String label, LogLevel level, String message)
      Description copied from interface: DistributedLogStore
      Records a log entry with transition context.
      Specified by:
      log in interface DistributedLogStore
      Parameters:
      sessionId - session ID from startSession()
      nodeId - identifier of the node
      label - current label in workflow
      level - log level
      message - log message

    • logAction

      public void logAction(long sessionId, String nodeId, String label, String actionName, int exitCode, long durationMs, String output)
      Description copied from interface: DistributedLogStore
      Records an action result.
      Specified by:
      logAction in interface DistributedLogStore
      Parameters:
      sessionId - session ID
      nodeId - node identifier
      label - label
      actionName - action/method name
      exitCode - command exit code (0 for success)
      durationMs - execution duration in milliseconds
      output - command output or result message

    • parseLogLevelFromLabel

      private LogLevel parseLogLevelFromLabel(String label, int exitCode)
      Parses log level from the label parameter.

      Maps java.util.logging levels to LogLevel:

      • SEVERE → ERROR
      • WARNING → WARN
      • INFO → INFO
      • CONFIG, FINE, FINER, FINEST → DEBUG

    • writeToTextLog

      private void writeToTextLog(String nodeId, String label, LogLevel level, String message)
      Writes a log entry to the text log file if enabled.
      Parameters:
      nodeId - the node identifier
      label - the workflow label (may be null)
      level - the log level
      message - the log message

    • markNodeSuccess

      public void markNodeSuccess(long sessionId, String nodeId)
      Description copied from interface: DistributedLogStore
      Marks a node as succeeded in this session.
      Specified by:
      markNodeSuccess in interface DistributedLogStore
      Parameters:
      sessionId - session ID
      nodeId - node identifier

    • markNodeFailed

      public void markNodeFailed(long sessionId, String nodeId, String reason)
      Description copied from interface: DistributedLogStore
      Marks a node as failed in this session.
      Specified by:
      markNodeFailed in interface DistributedLogStore
      Parameters:
      sessionId - session ID
      nodeId - node identifier
      reason - failure reason

    • endSession

      public void endSession(long sessionId, SessionStatus status)
      Description copied from interface: DistributedLogStore
      Ends a session with the given status.
      Specified by:
      endSession in interface DistributedLogStore
      Parameters:
      sessionId - session ID
      status - final status

    • flushWrites

      private void flushWrites()

    • getLogsByNode

      public List<LogEntry> getLogsByNode(long sessionId, String nodeId)
      Description copied from interface: DistributedLogStore
      Retrieves all log entries for a specific node in a session.
      Specified by:
      getLogsByNode in interface DistributedLogStore
      Parameters:
      sessionId - session ID
      nodeId - node identifier
      Returns:
      list of log entries

    • getLogsByLevel

      public List<LogEntry> getLogsByLevel(long sessionId, LogLevel minLevel)
      Description copied from interface: DistributedLogStore
      Retrieves log entries filtered by level.
      Specified by:
      getLogsByLevel in interface DistributedLogStore
      Parameters:
      sessionId - session ID
      minLevel - minimum log level to include
      Returns:
      list of log entries

    • getSummary

      public SessionSummary getSummary(long sessionId)
      Description copied from interface: DistributedLogStore
      Gets a summary of the session.
      Specified by:
      getSummary in interface DistributedLogStore
      Parameters:
      sessionId - session ID
      Returns:
      session summary

    • getLatestSessionId

      public long getLatestSessionId()
      Description copied from interface: DistributedLogStore
      Gets the most recent session ID.
      Specified by:
      getLatestSessionId in interface DistributedLogStore
      Returns:
      latest session ID, or -1 if no sessions exist

    • listSessions

      public List<SessionSummary> listSessions(int limit)
      Description copied from interface: DistributedLogStore
      Lists all sessions.
      Specified by:
      listSessions in interface DistributedLogStore
      Parameters:
      limit - maximum number of sessions to return
      Returns:
      list of session summaries

    • close

      public void close() throws Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception