Implementation:OpenHands OpenHands SaaSMonitoringListener

Knowledge Sources	OpenHands
Domains	Server_Architecture, SaaS_Infrastructure
Last Updated	2026-02-11 21:00 GMT

Overview

Concrete tool for collecting and forwarding session metrics, agent event tracking, and conversation monitoring through a singleton listener, provided by the OpenHands enterprise server layer.

Description

The SaaSMonitoringListener class implements a singleton pattern that subscribes to application events and records metrics for operational monitoring. The get_instance class method ensures only one listener instance exists per process, initialized with the OpenHandsConfig configuration object. The listener implements three key event handlers: on_session_event processes individual session events (such as agent actions and observations), on_agent_session_start records session creation metrics including success/failure status and initialization duration, and on_create_conversation tracks conversation creation for capacity planning and usage analytics. The module also provides supporting startup utilities: setup_all_loggers configures structured logging across all application modules with appropriate log levels and formatters, and get_admin_user_id resolves administrative user identity from request context for privileged operations such as email validation.

Usage

Use this listener during server startup to establish monitoring infrastructure before the server begins accepting traffic. Call SaaSMonitoringListener.get_instance(config) during the bootstrap sequence to initialize the singleton. The listener then automatically receives events from the application runtime. Call setup_all_loggers() early in startup to ensure all subsequent operations are logged with consistent formatting. Use get_admin_user_id in administrative route handlers that require elevated permission checks.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/server/saas_monitoring_listener.py:L12-55
• Also: enterprise/server/logger.py:L86-115 (setup_all_loggers), enterprise/server/email_validation.py:L11-68 (get_admin_user_id)

Signature

class SaaSMonitoringListener:
    @classmethod
    def get_instance(cls, config: OpenHandsConfig) -> 'SaaSMonitoringListener':
        ...

    def on_session_event(self, event: Event) -> None:
        ...

    def on_agent_session_start(self, success: bool, duration: float) -> None:
        ...

    def on_create_conversation(self) -> None:
        ...

# Logger setup utility
def setup_all_loggers() -> None:
    ...

# Admin user resolution utility
def get_admin_user_id(request: Request, user_id: str) -> str:
    ...

Import

from enterprise.server.saas_monitoring_listener import SaaSMonitoringListener
from enterprise.server.logger import setup_all_loggers
from enterprise.server.email_validation import get_admin_user_id

I/O Contract

Inputs

Name	Type	Required	Description
config	OpenHandsConfig	Yes	The application configuration object used to initialize monitoring parameters
event	Event	Yes	A session event object containing event type, metadata, and payload (for on_session_event)
success	bool	Yes	Whether the agent session started successfully (for on_agent_session_start)
duration	float	Yes	Time in seconds taken to initialize the agent session (for on_agent_session_start)
request	Request	Yes	The incoming HTTP request containing user identity information (for get_admin_user_id)
user_id	str	Yes	The user ID to validate for administrative privileges (for get_admin_user_id)

Outputs

Name	Type	Description
instance	SaaSMonitoringListener	The singleton monitoring listener instance
admin_user_id	str	The resolved and validated administrative user ID

Usage Examples

Basic Usage

from enterprise.server.saas_monitoring_listener import SaaSMonitoringListener
from enterprise.server.logger import setup_all_loggers
from openhands.core.config import OpenHandsConfig

# Step 1: Configure logging first
setup_all_loggers()

# Step 2: Initialize configuration
config = OpenHandsConfig()

# Step 3: Initialize the monitoring singleton
monitoring = SaaSMonitoringListener.get_instance(config)

# The listener now automatically receives events
# Manual event forwarding example:
monitoring.on_create_conversation()
monitoring.on_agent_session_start(success=True, duration=1.23)

Related Pages

Implements Principle

• Principle:OpenHands_OpenHands_Server_Startup

Environment

• Environment:OpenHands_OpenHands_SaaS_Server_Environment