langfun 0.1.2.dev202509250804__py3-none-any.whl → 0.1.2.dev202509270803__py3-none-any.whl

langfun/env/event_handlers/event_logger.py

@@ -0,0 +1,415 @@
+# Copyright 2025 The Langfun Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Environment event logger."""
+
+import re
+import time
+from typing import Annotated
+from langfun.env.event_handlers import base
+import pyglove as pg
+
+
+class EventLogger(pg.Object, base.EventHandler):
+  """Event handler for logging debugger."""
+
+  regex: Annotated[
+      str | list[str] | None,
+      (
+          'One or a list of regular expressions to filter event messages. '
+          'If None, no filtering will be applied.'
+      )
+  ] = None
+
+  error_only: Annotated[
+      bool,
+      (
+          'If True, log events with errors only.'
+      )
+  ] = False
+
+  sandbox_status: Annotated[
+      bool,
+      (
+          'If True, log events for sandbox status changes.'
+      )
+  ] = True
+
+  feature_status: Annotated[
+      bool,
+      (
+          'If True, log events for feature setup/teardown updates.'
+      )
+  ] = True
+
+  session_status: Annotated[
+      bool,
+      (
+          'If True, log events for session start/end status update.'
+      )
+  ] = True
+
+  housekeep_status: Annotated[
+      bool,
+      (
+          'If True, log housekeeping events.'
+      )
+  ] = True
+
+  stats_report_interval: Annotated[
+      float | None,
+      (
+          'The minimum interval in seconds for reporting the environment '
+          'stats. If None, stats will not be reported.'
+      )
+  ] = 300.0
+
+  def _on_bound(self) -> None:
+    super()._on_bound()
+
+    regex_exps = self.regex
+    if isinstance(regex_exps, str):
+      regex_exps = [regex_exps]
+    elif regex_exps is None:
+      regex_exps = []
+    self._regex_exps = [re.compile(x) for x in regex_exps]
+    self._last_stats_report_time = None
+
+  def _format_message(
+      self,
+      message: str,
+      error: BaseException | None,
+  ) -> str:
+    if error is not None:
+      message = f'{message} with error: {error}'
+    return message
+
+  def _keep(
+      self,
+      message: str,
+      error: BaseException | None,
+  ) -> bool:
+    if error is None and self.error_only:
+      return False
+    if self._regex_exps and all(
+        not exp.match(message) for exp in self._regex_exps
+    ):
+      return False
+    return True
+
+  def on_environment_start(
+      self,
+      environment: base.Environment,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when the environment is started."""
+    self._print(
+        f'[{environment.id}] environment started '
+        f'(duration={duration:.2f} seconds)',
+        error=error,
+        color='green',
+        styles=['bold'],
+    )
+
+  def on_environment_housekeep(
+      self,
+      environment: base.Environment,
+      counter: int,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when the environment is housekeeping."""
+    if self.housekeep_status:
+      self._print(
+          f'[{environment.id}] environment housekeeping complete'
+          f'(counter={counter}, duration={duration:.2f} seconds)',
+          error=error,
+          color='green',
+      )
+    if (self.stats_report_interval is not None and
+        (self._last_stats_report_time is None
+         or time.time() - self._last_stats_report_time
+         > self.stats_report_interval)):
+      self._write_log(
+          f'[{environment.id}] environment stats: {environment.stats()}',
+          color='magenta',
+          error=None,
+      )
+      self._last_stats_report_time = time.time()
+
+  def on_environment_shutdown(
+      self,
+      environment: base.Environment,
+      lifetime: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when the environment is shutdown."""
+    self._print(
+        f'[{environment.id}] environment shutdown '
+        f'(lifetime={lifetime:.2f} seconds)',
+        error=error,
+        color='green',
+        styles=['bold'],
+    )
+
+  def on_sandbox_start(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    if self.sandbox_status:
+      self._print(
+          f'[{sandbox.id}] sandbox started '
+          f'(duration={duration:.2f} seconds)',
+          error=error,
+          color='white',
+          styles=['bold'],
+      )
+
+  def on_sandbox_status_change(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      old_status: base.Sandbox.Status,
+      new_status: base.Sandbox.Status,
+      span: float
+  ) -> None:
+    if self.sandbox_status:
+      self._print(
+          f'[{sandbox.id}] {old_status.value} '
+          f'({span:.2f} seconds) -> {new_status.value}',
+          error=None,
+          color='white',
+      )
+
+  def on_sandbox_shutdown(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      lifetime: float,
+      error: BaseException | None
+  ) -> None:
+    if self.sandbox_status:
+      self._print(
+          f'[{sandbox.id}] sandbox shutdown '
+          f'(lifetime={lifetime:.2f} seconds)',
+          error=error,
+          color='white',
+          styles=['bold'],
+      )
+
+  def on_sandbox_housekeep(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      counter: int,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is housekeeping."""
+    if self.sandbox_status and self.housekeep_status:
+      self._print(
+          f'[{sandbox.id}] sandbox housekeeping complete '
+          f'(counter={counter}, duration={duration:.2f} seconds)',
+          error=error,
+          color='white',
+      )
+
+  def on_feature_setup(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      feature: base.Feature,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is setup."""
+    if self.feature_status:
+      self._print(
+          f'[{sandbox.id}/<idle>/{feature.name}] feature setup complete '
+          f'(duration={duration:.2f} seconds)',
+          error=error,
+          color='white',
+      )
+
+  def on_feature_teardown(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      feature: base.Feature,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is teardown."""
+    if self.feature_status:
+      self._print(
+          f'[{sandbox.id}/<idle>/{feature.name}] feature teardown complete '
+          f'(duration={duration:.2f} seconds)',
+          error=error,
+          color='white',
+      )
+
+  def on_feature_setup_session(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      feature: base.Feature,
+      session_id: str | None,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is setup."""
+    if self.feature_status:
+      self._print(
+          f'[{sandbox.id}/{session_id or "<idle>"}/{feature.name}] '
+          f'feature setup complete (duration={duration:.2f} seconds)',
+          error=error,
+          color='yellow',
+      )
+
+  def on_feature_teardown_session(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      feature: base.Feature,
+      session_id: str,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is teardown."""
+    if self.feature_status:
+      self._print(
+          f'[{sandbox.id}/{session_id}>/{feature.name}] '
+          f'feature teardown complete (duration={duration:.2f} seconds)',
+          error=error,
+          color='yellow',
+      )
+
+  def on_feature_housekeep(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      feature: base.Feature,
+      counter: int,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is housekeeping."""
+    if self.feature_status and self.housekeep_status:
+      self._print(
+          f'[{sandbox.id}/<idle>/{feature.name}] feature housekeeping complete '
+          f'(counter={counter}, (duration={duration:.2f} seconds)',
+          error=error,
+          color='white',
+      )
+
+  def on_session_start(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      session_id: str,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox session starts."""
+    if self.session_status:
+      self._print(
+          f'[{sandbox.id}/{session_id}] session started '
+          f'(duration={duration:.2f} seconds)',
+          error=error,
+          color='blue',
+      )
+
+  def on_session_end(
+      self,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      session_id: str,
+      lifetime: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox session ends."""
+    if self.session_status:
+      self._print(
+          f'[{sandbox.id}/{session_id}] session ended '
+          f'(lifetime={lifetime:.2f} seconds)',
+          error=error,
+          color='blue',
+      )
+
+  def on_sandbox_activity(
+      self,
+      name: str,
+      environment: base.Environment,
+      sandbox: base.Sandbox,
+      feature: base.Feature | None,
+      session_id: str | None,
+      duration: float,
+      error: BaseException | None,
+      **kwargs
+  ) -> None:
+    """Called when a sandbox activity is performed."""
+    del environment
+    log_id = f'{sandbox.id}/{session_id or "<idle>"}'
+    if feature is not None:
+      log_id = f'{log_id}/{feature.name}'
+
+    color = 'yellow' if session_id is None else 'cyan'
+    self._print(
+        f'[{log_id}] call {name!r} '
+        f'(duration={duration:.2f} seconds, kwargs={kwargs}) ',
+        error,
+        color=color
+    )
+
+  def _print(
+      self,
+      message: str,
+      error: BaseException | None,
+      color: str | None = None,
+      styles: list[str] | None = None,
+  ):
+    message = self._format_message(message, error)
+    if not self._keep(message, error):
+      return
+    self._write_log(message, error, color, styles)
+
+  def _write_log(
+      self,
+      message: str,
+      error: BaseException | None,
+      color: str | None = None,
+      styles: list[str] | None = None,
+  ):
+    if error is not None:
+      pg.logging.error(pg.colored(message, 'red', styles=styles))
+    else:
+      pg.logging.info(pg.colored(message, color, styles=styles))
+
+
+class ConsoleEventLogger(EventLogger):
+  """Event handler for console debugger."""
+
+  def _write_log(
+      self,
+      message: str,
+      error: BaseException | None,
+      color: str | None = None,
+      styles: list[str] | None = None,
+  ):
+    print(
+        pg.colored(message, color if error is None else 'red', styles=styles)
+    )

langfun/env/event_handlers/event_logger_test.py

@@ -0,0 +1,289 @@
+# Copyright 2025 The Langfun Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import contextlib
+import io
+from typing import Iterator
+import unittest
+
+from langfun.env import interface
+from langfun.env import test_utils
+from langfun.env.event_handlers import event_logger as event_logger_lib
+import pyglove as pg
+
+
+class EventLoggerTest(unittest.TestCase):
+
+  LOGGER_CLS = event_logger_lib.EventLogger
+
+  @contextlib.contextmanager
+  def _capture_logs(self, test_name: str) -> Iterator[io.StringIO]:
+    try:
+      stream = io.StringIO()
+      with pg.logging.redirect_stream(
+          stream, name=f'{self.LOGGER_CLS.__name__}.{test_name}'
+      ):
+        yield stream
+    finally:
+      pass
+
+  def _test_logger(
+      self,
+      *,
+      test_name: str,
+      expected_substrings: list[str],
+      unexpected_substrings: list[str],
+      error_only: bool = False,
+      regex: str | None = None,
+      sandbox_status: bool = True,
+      session_status: bool = True,
+      feature_status: bool = True,
+      housekeep_status: bool = True,
+      stats_report_interval: float = 1.0,
+  ):
+    event_logger = self.LOGGER_CLS(
+        error_only=error_only,
+        regex=regex,
+        sandbox_status=sandbox_status,
+        session_status=session_status,
+        feature_status=feature_status,
+        housekeep_status=housekeep_status,
+        stats_report_interval=stats_report_interval,
+    )
+    env = test_utils.TestingEnvironment(
+        features={
+            'test_feature1': test_utils.TestingFeature(housekeep_interval=0),
+            'test_feature2': test_utils.TestingFeature(housekeep_interval=None),
+        },
+        pool_size=2,
+        outage_grace_period=0,
+        outage_retry_interval=0,
+        housekeep_interval=1.0,
+        sandbox_keepalive_interval=1.0,
+        event_handlers=[event_logger],
+    )
+    with self._capture_logs(test_name) as stream:
+      with env:
+        with env.sandbox('session1') as sb:
+          self.assertEqual(sb.test_feature1.num_shell_calls(), 4)
+
+        with self.assertRaises(interface.SandboxStateError):
+          with env.sandbox('session2') as sb:
+            sb.shell('echo "bar"', raise_error=RuntimeError)
+
+    stdout = stream.getvalue()
+    for substring in expected_substrings:
+      self.assertIn(substring, stdout)
+    for substring in unexpected_substrings:
+      self.assertNotIn(substring, stdout)
+
+  def test_all_flags_on(self):
+    return self._test_logger(
+        test_name='test_all_flags_on',
+        expected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment housekeeping',
+            'environment stats',
+            'sandbox started',
+            '-> acquired',
+            'sandbox shutdown',
+            'sandbox housekeeping',
+            'feature setup complete',
+            'feature teardown complete',
+            '/test_feature1] feature housekeeping',
+            'session started',
+            'session ended',
+            'call \'shell\'',
+            'RuntimeError',
+        ],
+        unexpected_substrings=[
+            '/test_feature2] feature housekeeping',
+        ],
+    )
+
+  def test_error_only(self):
+    return self._test_logger(
+        test_name='test_error_only',
+        expected_substrings=[
+            'session ended',
+            'call \'shell\'',
+            'RuntimeError',
+        ],
+        unexpected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment housekeeping',
+            'sandbox started',
+            '-> acquired',
+            'sandbox shutdown',
+            'feature setup complete',
+            'feature teardown complete',
+            'session started',
+        ],
+        error_only=True,
+    )
+
+  def test_regex(self):
+    return self._test_logger(
+        test_name='test_regex',
+        expected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment housekeeping',
+        ],
+        unexpected_substrings=[
+            'sandbox started',
+            '-> acquired',
+            'sandbox shutdown',
+            'feature setup complete',
+            'feature teardown complete',
+            'session started',
+            'session ended',
+            'call \'shell\'',
+            'RuntimeError',
+        ],
+        regex='.*environment.*',
+    )
+
+  def test_sandbox_status_off(self):
+    return self._test_logger(
+        test_name='test_sandbox_status_off',
+        expected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment housekeeping',
+            'feature setup complete',
+            'feature teardown complete',
+            'feature housekeeping',
+            'session started',
+            'session ended',
+            'call \'shell\'',
+            'RuntimeError',
+        ],
+        unexpected_substrings=[
+            'sandbox started',
+            '-> acquired',
+            'sandbox shutdown',
+            'sandbox housekeeping',
+        ],
+        sandbox_status=False,
+    )
+
+  def test_feature_status_off(self):
+    return self._test_logger(
+        test_name='test_feature_status_off',
+        expected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment housekeeping',
+            'environment stats',
+            'sandbox started',
+            '-> acquired',
+            'sandbox shutdown',
+            'sandbox housekeeping',
+            'session started',
+            'session ended',
+            'call \'shell\'',
+            'RuntimeError',
+        ],
+        unexpected_substrings=[
+            'feature setup complete',
+            'feature teardown complete',
+            'feature housekeeping',
+        ],
+        feature_status=False,
+    )
+
+  def test_session_status_off(self):
+    return self._test_logger(
+        test_name='test_session_status_off',
+        expected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment stats',
+            'environment housekeeping',
+            'sandbox started',
+            '-> acquired',
+            'sandbox shutdown',
+            'sandbox housekeeping',
+            'feature setup complete',
+            'feature teardown complete',
+            'feature housekeeping',
+            'call \'shell\'',
+            'RuntimeError',
+        ],
+        unexpected_substrings=[
+            'session started',
+            'session ended',
+        ],
+        session_status=False,
+    )
+
+  def test_housekeep_status_off(self):
+    return self._test_logger(
+        test_name='test_housekeep_status_off',
+        expected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment stats',
+            'sandbox started',
+            '-> acquired',
+            'sandbox shutdown',
+            'feature setup complete',
+            'feature teardown complete',
+            'session started',
+            'session ended',
+            'call \'shell\'',
+            'RuntimeError',
+        ],
+        unexpected_substrings=[
+            'environment housekeeping',
+            'sandbox housekeeping',
+            'feature housekeeping',
+        ],
+        housekeep_status=False,
+    )
+
+  def test_no_stats_report(self):
+    return self._test_logger(
+        test_name='test_housekeep_status_off',
+        expected_substrings=[
+            'environment started',
+            'environment shutdown',
+            'environment housekeeping',
+        ],
+        unexpected_substrings=[
+            'environment stats',
+        ],
+        stats_report_interval=None,
+    )
+
+
+class ConsoleEventLoggerTest(EventLoggerTest):
+
+  LOGGER_CLS = event_logger_lib.ConsoleEventLogger
+
+  @contextlib.contextmanager
+  def _capture_logs(self, test_name: str) -> Iterator[io.StringIO]:
+    try:
+      stream = io.StringIO()
+      with contextlib.redirect_stdout(stream):
+        yield stream
+    finally:
+      pass
+
+
+if __name__ == '__main__':
+  unittest.main()