Interface DistributedLogStore

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
H2LogStore
public interface DistributedLogStore extends AutoCloseable
Interface for distributed log storage.

This interface defines operations for storing and querying logs from distributed workflow execution across multiple nodes.

The interface provides singleton access for components that need database connection (e.g., WorkflowReporter). The singleton is set by RunCLI at workflow startup and cleared after execution.

Author:
devteam@scivicslab.com

  • Method Details

    • setInstance

      static void setInstance(DistributedLogStore store)
      Sets the singleton instance.

      Called by RunCLI when starting workflow execution.

      Parameters:
      store - the DistributedLogStore instance to use globally

    • getInstance

      static DistributedLogStore getInstance()
      Gets the singleton instance.
      Returns:
      the global DistributedLogStore instance, or null if not set

    • getConnection

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

      Components should NOT close this connection. The connection is owned by RunCLI and will be closed when the workflow execution ends.

      Returns:
      the JDBC connection

    • startSession

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

    • startSession

      long startSession(String workflowName, String overlayName, String inventoryName, int nodeCount)
      Starts a new workflow execution session with overlay and inventory info.
      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

      default long startSession(String workflowName, String overlayName, String inventoryName, int nodeCount, String cwd, String gitCommit, String gitBranch, String commandLine, String actorIacVersion, String actorIacCommit)
      Starts a new workflow execution session with full execution context.
      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

      void log(long sessionId, String nodeId, LogLevel level, String message)
      Records a log entry.
      Parameters:
      sessionId - session ID from startSession()
      nodeId - identifier of the node generating this log
      level - log level
      message - log message

    • log

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

    • logAction

      void logAction(long sessionId, String nodeId, String label, String actionName, int exitCode, long durationMs, String output)
      Records an action result.
      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

    • markNodeSuccess

      void markNodeSuccess(long sessionId, String nodeId)
      Marks a node as succeeded in this session.
      Parameters:
      sessionId - session ID
      nodeId - node identifier

    • markNodeFailed

      void markNodeFailed(long sessionId, String nodeId, String reason)
      Marks a node as failed in this session.
      Parameters:
      sessionId - session ID
      nodeId - node identifier
      reason - failure reason

    • endSession

      void endSession(long sessionId, SessionStatus status)
      Ends a session with the given status.
      Parameters:
      sessionId - session ID
      status - final status

    • getLogsByNode

      List<LogEntry> getLogsByNode(long sessionId, String nodeId)
      Retrieves all log entries for a specific node in a session.
      Parameters:
      sessionId - session ID
      nodeId - node identifier
      Returns:
      list of log entries

    • getLogsByLevel

      List<LogEntry> getLogsByLevel(long sessionId, LogLevel minLevel)
      Retrieves log entries filtered by level.
      Parameters:
      sessionId - session ID
      minLevel - minimum log level to include
      Returns:
      list of log entries

    • getErrors

      default List<LogEntry> getErrors(long sessionId)
      Retrieves error logs for a session.
      Parameters:
      sessionId - session ID
      Returns:
      list of error log entries

    • getSummary

      SessionSummary getSummary(long sessionId)
      Gets a summary of the session.
      Parameters:
      sessionId - session ID
      Returns:
      session summary

    • getLatestSessionId

      long getLatestSessionId()
      Gets the most recent session ID.
      Returns:
      latest session ID, or -1 if no sessions exist

    • listSessions

      List<SessionSummary> listSessions(int limit)
      Lists all sessions.
      Parameters:
      limit - maximum number of sessions to return
      Returns:
      list of session summaries