tessl/pypi-tensorboard

TensorBoard is a suite of web applications for inspecting and understanding your TensorFlow runs and graphs

Overview

Eval results

Files

Process Management

Name: tessl/pypi-tensorboard
Author: tessl

TensorBoard's manager module provides process lifecycle management for TensorBoard instances, enabling programmatic control over server startup, monitoring, and shutdown. It includes utilities for managing multiple TensorBoard instances and tracking their state.

Capabilities

TensorBoard Information

Data structure containing metadata about running TensorBoard instances.

@dataclasses.dataclass(frozen=True)
class TensorBoardInfo:
    """
    Information about a running TensorBoard instance.
    
    Dataclass containing process metadata for TensorBoard instances.
    
    Attributes:
        version (str): Version of the running TensorBoard
        start_time (int): Start time as seconds since epoch
        pid (int): Process ID
        port (int): Server port number
        path_prefix (str): Relative URL path prefix (may be empty)
        logdir (str): Data location used by server (may be empty)
        db (str): Database connection used by server (may be empty)
        cache_key (str): Opaque cache key for instance identification
    """
    
    version: str
    start_time: int
    pid: int
    port: int
    path_prefix: str
    logdir: str
    db: str
    cache_key: str

Launch Result Classes

Result objects returned by the start() function indicating launch outcome.

@dataclasses.dataclass(frozen=True)
class StartReused:
    """
    Indicates an existing TensorBoard instance was reused.
    
    Attributes:
        info (TensorBoardInfo): Information about the reused instance
    """
    
    info: TensorBoardInfo

@dataclasses.dataclass(frozen=True)
class StartLaunched:
    """
    Indicates a new TensorBoard instance was launched successfully.
    
    Attributes:
        info (TensorBoardInfo): Information about the new instance
    """
    
    info: TensorBoardInfo

@dataclasses.dataclass(frozen=True)
class StartFailed:
    """
    Indicates TensorBoard launch failed.
    
    Attributes:
        exit_code (int): Process exit code (negative for signal)
        stdout (str, optional): Standard output if readable
        stderr (str, optional): Standard error if readable
    """
    
    exit_code: int
    stdout: Optional[str]
    stderr: Optional[str]

@dataclasses.dataclass(frozen=True)
class StartExecFailed:
    """
    Indicates TensorBoard executable could not be found or executed.
    
    Attributes:
        os_error (OSError): Exception from subprocess execution
        explicit_binary (str, optional): Custom binary path from TENSORBOARD_BINARY env var
    """
    
    os_error: OSError  
    explicit_binary: Optional[str]

@dataclasses.dataclass(frozen=True)
class StartTimedOut:
    """
    Indicates TensorBoard launch timed out.
    
    Attributes:
        pid (int): Process ID of the timed-out TensorBoard instance
    """
    
    pid: int

Process Management Functions

Core functions for managing TensorBoard instances.

def start(arguments, timeout=datetime.timedelta(seconds=60)):
    """
    Start a TensorBoard instance with specified arguments.
    
    Args:
        arguments (list): Command-line arguments for TensorBoard
        timeout (datetime.timedelta): Maximum time to wait for startup 
                                     (default 60 seconds)
        
    Returns:
        Union[StartReused, StartLaunched, StartFailed, StartExecFailed, StartTimedOut]:
            Result object indicating launch outcome
                    
    Automatically detects if a compatible instance is already running
    and reuses it when possible, or launches a new instance otherwise.
    """

def get_all():
    """
    Get information about all known running TensorBoard instances.
    
    Returns:
        list[TensorBoardInfo]: List of TensorBoardInfo objects for 
                              all discovered running instances
                              
    Scans info files in temp directory for TensorBoard metadata.
    May contain stale entries if processes exited uncleanly.
    """

def data_source_from_info(info):
    """
    Format data source information from TensorBoardInfo.
    
    Args:
        info (TensorBoardInfo): TensorBoard instance information
        
    Returns:
        str: Human-readable data source description (e.g., "logdir /path" or "db connection")
    """

File Management Functions

Utilities for managing TensorBoard instance metadata files.

def cache_key(working_directory, arguments, configure_kwargs):
    """
    Generate cache key for TensorBoard instance identification.
    
    Args:
        working_directory (str): Working directory path
        arguments (list): Command-line arguments
        configure_kwargs (dict): Configuration keyword arguments
        
    Returns:
        str: Unique cache key for the configuration
        
    Used to determine if an existing instance matches the requested configuration.
    """

def write_info_file(tensorboard_info):
    """
    Write TensorBoard instance information to file.
    
    Args:
        tensorboard_info (TensorBoardInfo): Instance information to write
        
    Creates a metadata file containing instance information for later retrieval.
    """

def remove_info_file():
    """
    Remove TensorBoard instance information file.
    
    Cleans up metadata files when instances are stopped or no longer needed.
    """

Usage Examples

Basic Instance Management

from tensorboard import manager

# Start TensorBoard with specific arguments
arguments = ['--logdir', './logs', '--port', '6006']
result = manager.start(arguments, timeout=30)

# Check result type and handle accordingly
if isinstance(result, manager.StartLaunched):
    print(f"Started new TensorBoard on port {result.info.port}")
elif isinstance(result, manager.StartReused):
    print(f"Reusing existing TensorBoard on port {result.info.port}")
elif isinstance(result, manager.StartFailed):
    print(f"Failed to start TensorBoard: {result.error}")

Instance Discovery

from tensorboard import manager

# Get all running TensorBoard instances
instances = manager.get_all()

print(f"Found {len(instances)} TensorBoard instances:")
for info in instances:
    print(f"  PID {info.pid}: port {info.port}, logdir {info.logdir}")
    
    # Extract primary data source
    data_source = manager.data_source_from_info(info)
    print(f"    Data source: {data_source}")

Advanced Configuration

from tensorboard import manager
import time

# Start TensorBoard with custom timeout
arguments = ['--logdir', './experiments', '--port', '6007', '--reload_interval', '30']
start_time = time.time()

result = manager.start(arguments, timeout=120)  # 2 minute timeout

if isinstance(result, manager.StartLaunched):
    elapsed = time.time() - start_time
    print(f"TensorBoard started in {elapsed:.2f} seconds")
    
    # Write instance info for tracking
    manager.write_info_file(result.info)
    
elif isinstance(result, manager.StartTimedOut):
    print(f"TensorBoard startup timed out, process still running as PID {result.pid}")

Cache Key Generation

from tensorboard import manager
import os

# Generate cache key for instance identification
working_dir = os.getcwd()
arguments = ['--logdir', './logs', '--port', '6006']
config_kwargs = {'reload_interval': 30, 'max_reload_threads': 4}

cache_key = manager.cache_key(working_dir, arguments, config_kwargs)
print(f"Cache key: {cache_key}")

# This key is used internally to determine if an existing instance
# matches the requested configuration for reuse

Cleanup Operations

from tensorboard import manager

# Clean up instance metadata files
try:
    manager.remove_info_file()
    print("Instance metadata cleaned up")
except Exception as e:
    print(f"Cleanup failed: {e}")

The manager module provides essential process lifecycle functionality for TensorBoard, enabling robust management of server instances in both development and production environments. It handles the complexity of process detection, reuse logic, and metadata tracking automatically.

Install with Tessl CLI