adding perfmonitor

Author: miranov25

UTILS/perfmonitor/README.md

@@ -0,0 +1,118 @@
+# Performance Monitor
+
+Lightweight logging and analysis utility for tracking performance (execution time and memory) of scripts or processing pipelines.
+
+## Features
+
+* Logs elapsed time and memory (RSS) per step
+* Supports multi-level index tags for loop tracking
+* Saves logs in delimiter-separated format (default: `|`)
+* Parses logs to `pandas.DataFrame` for analysis
+* Summarizes stats (mean, max, min) with configurable grouping
+* Plots memory/time using `matplotlib`
+* Optionally saves plots to a PDF
+* Combines logs from multiple files
+
+## Installation
+
+This is a self-contained utility. Just place the `perfmonitor/` directory into your Python path.
+
+## Example Usage
+
+```python
+import time
+import pandas as pd
+import matplotlib.pyplot as plt
+from perfmonitor import PerformanceLogger, default_plot_config, default_summary_config
+
+# Initialize logger
+logger = PerformanceLogger("perf_log.txt")
+logger.log("setup::start")
+
+# Simulate steps with increasing delays
+for i, delay in enumerate([0.1, 0.2, 0.3]):
+    time.sleep(delay)
+    logger.log("loop::step", index=[i])
+
+# Parse logs from one or more files
+df = PerformanceLogger.log_to_dataframe(["perf_log.txt"])
+print(df.head())
+```
+
+### Expected Output
+
+Example output from `print(df.head())`:
+
+```
+              timestamp            step  elapsed_sec  rss_gb        user             host       logfile  index_0
+0  2025-05-31 09:12:01,120  setup::start         0.00     0.13     user123      host.local  perf_log.txt      NaN
+1  2025-05-31 09:12:01,220  loop::step[0]        0.10     0.14     user123      host.local  perf_log.txt      0.0
+2  2025-05-31 09:12:01,420  loop::step[1]        0.20     0.15     user123      host.local  perf_log.txt      1.0
+3  2025-05-31 09:12:01,720  loop::step[2]        0.30     0.15     user123      host.local  perf_log.txt      2.0
+```
+
+## Summary Statistics
+
+```python
+summary = PerformanceLogger.summarize_with_config(df, default_summary_config)
+print(summary)
+```
+
+### Example Summary Output
+
+```
+              elapsed_sec           rss_gb
+                     mean  max  min   mean   max   min
+step
+loop::step[0]         0.10 0.10 0.10  0.14  0.14  0.14
+loop::step[1]         0.20 0.20 0.20  0.15  0.15  0.15
+loop::step[2]         0.30 0.30 0.30  0.15  0.15  0.15
+setup::start          0.00 0.00 0.00  0.13  0.13  0.13
+```
+
+## Plotting
+
+```python
+# Show plots
+PerformanceLogger.plot(df, default_plot_config)
+
+# Save plots to PDF
+PerformanceLogger.plot(df, default_plot_config, output_pdf="perf_plots.pdf")
+```
+
+## Multi-Level Index Extraction
+
+Step IDs can include index metadata like:
+
+```
+load::data[1,2]
+```
+
+This will be automatically parsed into new DataFrame columns:
+
+* `index_0` → 1
+* `index_1` → 2
+
+## Advanced: Custom Configuration
+
+```python
+custom_summary = {
+    "by": ["step", "index_0"],
+    "stats": ["mean", "max"]
+}
+
+custom_plots = {
+    "RSS Over Time": {
+        "kind": "line",
+        "varX": "timestamp",
+        "varY": "rss_gb",
+        "title": "RSS vs Time",
+        "sort": "timestamp",
+    }
+}
+
+PerformanceLogger.plot(df, custom_plots)
+```
+
+## License
+???

UTILS/perfmonitor/performance_logger.py

@@ -0,0 +1,150 @@
+import time
+import psutil
+import socket
+import getpass
+import pandas as pd
+import matplotlib.pyplot as plt
+from typing import Union, List, Dict, Optional
+
+class PerformanceLogger:
+    def __init__(self, log_path: str, sep: str = "|"):
+        self.log_path = log_path
+        self.start_time = time.time()
+        self.sep = sep
+        self.user = getpass.getuser()
+        self.host = socket.gethostname()
+
+    def log(self, step: str, index: Optional[List[int]] = None):
+        elapsed = time.time() - self.start_time
+        mem_gb = psutil.Process().memory_info().rss / (1024 ** 3)
+        index_str = "" if index is None else f"[{','.join(map(str, index))}]"
+        step_full = f"{step}{index_str}"
+        line = f"{time.strftime('%Y-%m-%d %H:%M:%S')},{int(time.time() * 1000) % 1000:03d} {self.sep} {step_full} {self.sep} {elapsed:.2f} {self.sep} {mem_gb:.2f} {self.sep} {self.user} {self.sep} {self.host}\n"
+        with open(self.log_path, "a") as f:
+            f.write(line)
+        print(f"{step_full} | {elapsed:.2f} | {mem_gb:.2f} | {self.user} | {self.host}")
+
+    @staticmethod
+    def log_to_dataframe(log_paths: Union[str, List[str]], sep: str = "|") -> pd.DataFrame:
+        if isinstance(log_paths, str):
+            log_paths = [log_paths]
+
+        rows = []
+        for path in log_paths:
+            with open(path) as f:
+                for line in f:
+                    parts = [x.strip() for x in line.strip().split(sep)]
+                    if len(parts) < 5:
+                        continue
+                    timestamp, step, elapsed_str, rss_str, user, host = parts[:6]
+                    row = {
+                        "timestamp": timestamp,
+                        "step": step,
+                        "elapsed_sec": float(elapsed_str),
+                        "rss_gb": float(rss_str),
+                        "user": user,
+                        "host": host,
+                        "logfile": path
+                    }
+
+                    if "[" in step and "]" in step:
+                        base, idx = step.split("[")
+                        row["step"] = base
+                        idx = idx.rstrip("]")
+                        for i, val in enumerate(idx.split(",")):
+                            if val.isdigit():
+                                row[f"index_{i}"] = int(val)
+                    rows.append(row)
+
+        return pd.DataFrame(rows)
+
+    @staticmethod
+    def summarize_with_config(df: pd.DataFrame, config: Dict) -> pd.DataFrame:
+        group_cols = config.get("by", ["step"])
+        stats = config.get("stats", ["mean", "max", "min"])
+
+        agg = {}
+        for col in ["elapsed_sec", "rss_gb"]:
+            agg[col] = stats
+
+        return df.groupby(group_cols).agg(agg)
+
+    @staticmethod
+    def plot(df: pd.DataFrame,
+             config_dict: Dict[str, Dict],
+             filter_expr: Optional[str] = None,
+             output_pdf: Optional[str] = None):
+
+        if filter_expr:
+            df = df.query(filter_expr)
+
+        if output_pdf:
+            from matplotlib.backends.backend_pdf import PdfPages
+            pdf = PdfPages(output_pdf)
+
+        for name, config in config_dict.items():
+            subdf = df.copy()
+            if "filter" in config:
+                subdf = subdf.query(config["filter"])
+
+            if "sort" in config:
+                subdf = subdf.sort_values(config["sort"])
+
+            x = subdf[config.get("varX", "timestamp")]
+            y = subdf[config.get("varY", "elapsed_sec")]
+            kind = config.get("kind", "line")
+
+            plt.figure()
+            if kind == "line":
+                plt.plot(x, y, marker="o")
+            elif kind == "bar":
+                plt.bar(x, y)
+            else:
+                raise ValueError(f"Unsupported plot kind: {kind}")
+
+            plt.title(config.get("title", name))
+            plt.xlabel(config.get("xlabel", config.get("varX", "timestamp")))
+            plt.ylabel(config.get("ylabel", config.get("varY", "elapsed_sec")))
+            plt.xticks(rotation=45)
+            plt.tight_layout()
+
+            if output_pdf:
+                pdf.savefig()
+                plt.close()
+            else:
+                plt.show()
+
+        if output_pdf:
+            pdf.close()
+
+
+# Default configurations
+
+default_plot_config={
+        "RSS vs Time": {
+            "kind": "line",
+            "varX": "timestamp",
+            "varY": "rss_gb",
+            "title": "RSS over Time",
+            "sort": "timestamp"
+        },
+        "RSS vs step": {
+            "kind": "line",
+            "varX": "step",
+            "varY": "rss_gb",
+            "title": "RSS over Time",
+        },
+        "Elapsed Time vs Step": {
+            "kind": "bar",
+            "varX": "step",
+            "varY": "elapsed_sec",
+            "title": "Elapsed Time per Step",
+            "sort": "step"
+        }
+}
+
+default_summary_config={
+        "by": ["step"],
+        "stats": ["mean", "max", "min"]
+    }
+