added small but powerful feature to the capture_timestamp workflows: timestamp_args (which adjusts the name based on the method call's params)

Author: DinisCruz

…0__timestamp-capture__llm-usage-brief.md …1__timestamp-capture__llm-usage-brief.mddocs/llm-briefs/features/v3.58.0__timestamp-capture__llm-usage-brief.md renamed to docs/llm-briefs/features/v3.59.1__timestamp-capture__llm-usage-brief.md docs/llm-briefs/features/v3.58.0__timestamp-capture__llm-usage-brief.md renamed to docs/llm-briefs/features/v3.59.1__timestamp-capture__llm-usage-brief.md

@@ -1,6 +1,6 @@
 # Timestamp Capture - LLM Usage Brief
 
-**Version**: v3.58.0  
+**Version**: v3.59.1  
 **Purpose**: Guide for LLMs and developers on using the timestamp_capture instrumentation system  
 **Location**: `osbot_utils.helpers.timestamp_capture`  
 **Repo**: https://github.com/owasp-sbot/OSBot-Utils  
@@ -103,6 +103,9 @@ from osbot_utils.helpers.timestamp_capture.Timestamp_Collector          import T
 # Decorator
 from osbot_utils.helpers.timestamp_capture.decorators.timestamp         import timestamp
 
+# Decorator for dynamic names from function arguments
+from osbot_utils.helpers.timestamp_capture.decorators.timestamp_args    import timestamp_args
+
 # Context manager for code blocks
 from osbot_utils.helpers.timestamp_capture.context_managers.timestamp_block import timestamp_block
 
@@ -299,7 +302,106 @@ def handle_delete(self):
 | `component.stage.action` | `pipeline.stage1.extract` | Pipeline stages |
 | `feature.version.method` | `algorithm.v2.sort` | A/B testing |
 
-### Pattern 5: Programmatic Analysis
+
+### Pattern 5: Dynamic Names from Function Arguments
+
+When a method is called multiple times with different arguments and you need to distinguish each call in reports, use `@timestamp_args`. This interpolates function argument values into the metric name at runtime.
+```python
+from osbot_utils.helpers.timestamp_capture.decorators.timestamp_args import timestamp_args
+
+class DocumentBuilder:
+    
+    @timestamp_args(name="link_component({name})")
+    def _link_component(self, name: str, root_id: int):
+        # Link a component graph to the document
+        ...
+
+# Each call is tracked separately:
+builder._link_component("head", 1)
+builder._link_component("body", 2)
+builder._link_component("attrs", 3)
+```
+
+**Timeline shows each call distinctly:**
+```
+20.879ms           ▶ link_component(head)
+21.846ms           ◀ link_component(head)
+21.860ms           ▶ link_component(body)
+22.659ms           ◀ link_component(body)
+22.671ms           ▶ link_component(attrs)
+23.433ms           ◀ link_component(attrs)
+```
+
+**Hotspots show individual breakdowns:**
+```
+link_component(head)     0.97ms [1 call]
+link_component(body)     0.80ms [1 call]
+link_component(attrs)    0.76ms [1 call]
+```
+
+#### When to use `@timestamp_args` vs `@timestamp`
+
+| Decorator | Name Resolution | Use When |
+|-----------|-----------------|----------|
+| `@timestamp` | At decoration time (static) | Same name for all calls |
+| `@timestamp_args` | At call time (dynamic) | Need to distinguish calls by argument values |
+
+#### Supported Argument Patterns
+```python
+# Positional arguments
+@timestamp_args(name="process.{item_type}")
+def process(item_type: str, data: dict):
+    ...
+
+# Multiple arguments
+@timestamp_args(name="handler.{method}.{path}")
+def handle_request(method: str, path: str):
+    ...
+
+# Keyword-only arguments (after *)
+@timestamp_args(name="config.{env}.{region}")
+def configure(*, env: str, region: str = "us-east-1"):
+    ...
+
+# Mixed positional and keyword-only
+@timestamp_args(name="request.{method}")
+def make_request(method: str, *, timeout: int = 30):
+    ...
+
+# Using default values (defaults are interpolated too)
+@timestamp_args(name="cache.{strategy}")
+def cache_data(data: dict, *, strategy: str = "lru"):
+    ...
+# cache_data({"a": 1}) → "cache.lru"
+# cache_data({"a": 1}, strategy="fifo") → "cache.fifo"
+```
+
+#### Real-World Example
+```python
+class Html_MGraph__Document:
+    
+    @timestamp(name="html_mgraph.document.setup")
+    def setup(self):
+        self.head_graph  = Html_MGraph__Head().setup()
+        self.body_graph  = Html_MGraph__Body().setup()
+        self.attrs_graph = Html_MGraph__Attributes().setup()
+        
+        # Each link is tracked separately
+        self._link_component_graph('head', self.head_graph.root_id)
+        self._link_component_graph('body', self.body_graph.root_id)
+        self._link_component_graph('attrs', self.attrs_graph.root_id)
+        return self
+    
+    @timestamp_args(name="html_mgraph.document._link_component_graph({name})")
+    def _link_component_graph(self, name: str, component_root_id: Node_Id):
+        # Now each call shows which component in timeline/reports
+        ...
+```
+
+**Important:** `@timestamp_args` requires at least one `{placeholder}` in the name. For static names, use `@timestamp` instead (lower overhead).
+
+
+### Pattern 6: Programmatic Analysis
 
 ```python
 from osbot_utils.helpers.timestamp_capture.Timestamp_Collector__Analysis import Timestamp_Collector__Analysis
@@ -329,7 +431,7 @@ by_total = analysis.get_timings_by_total()
 by_calls = analysis.get_timings_by_call_count()
 ```
 
-### Pattern 6: Test Performance Assertions
+### Pattern 7: Test Performance Assertions
 
 ```python
 def test_process_performance(self):
@@ -549,6 +651,7 @@ with _timestamp_collector_:
 | @timestamp, no collector | ~3 μs | ✅ Yes |
 | @timestamp, with collector | ~8 μs | ✅ Yes (for methods >100μs) |
 | Nested decorators (N levels) | N × overhead | ✅ Scales linearly |
+| @timestamp_args, with collector | ~10 μs | ✅ Yes (slight overhead for arg binding) |
 
 **Rule of thumb**: If your method takes >100μs, the 8μs capture overhead is <8% - acceptable for most scenarios including production profiling.
 
@@ -712,6 +815,24 @@ with timestamp_block("process_all_items"):
 MAX_STACK_DEPTH = 100  # Increase if needed
 ```
 
+### Problem: Can't Distinguish Multiple Calls to Same Method
+
+**Cause**: Using `@timestamp` on a method called with different arguments
+```python
+# ❌ All 5 calls show as same name
+@timestamp(name="link_component")
+def _link_component(self, name: str, root_id: int):
+    ...
+```
+
+**Solution**: Use `@timestamp_args` to include argument values in the name
+```python
+# ✅ Each call shows distinct name
+@timestamp_args(name="link_component({name})")
+def _link_component(self, name: str, root_id: int):
+    ...
+```
+
 ---
 
 ## Summary Checklist
@@ -721,6 +842,7 @@ When adding timestamp capture to a codebase:
 - [ ] Import `@timestamp` decorator and `Timestamp_Collector`
 - [ ] Add `@timestamp` to key methods (entry points, major processing steps)
 - [ ] Use `@timestamp(name="...")` for hierarchical/grouped naming when helpful
+- [ ] Use `@timestamp_args(name="method({arg})")` when you need to distinguish calls by argument values
 - [ ] Skip tiny utility functions and hot-loop internals
 - [ ] Use `timestamp_block` for code phases not in methods
 - [ ] Name collector variable exactly `_timestamp_collector_`

osbot_utils/helpers/timestamp_capture/Timestamp_Collector__Report.py

@@ -4,21 +4,41 @@
 
 Formats and prints timing reports from collected timestamps.
 """
-from osbot_utils.helpers.timestamp_capture.Timestamp_Collector import Timestamp_Collector
+
 from osbot_utils.helpers.timestamp_capture.Timestamp_Collector__Analysis         import Timestamp_Collector__Analysis
 from osbot_utils.helpers.timestamp_capture.static_methods.timestamp_utils        import method_timing__total_ms, method_timing__self_ms, method_timing__avg_ms
 from osbot_utils.type_safe.Type_Safe                                             import Type_Safe
+from osbot_utils.helpers.timestamp_capture.Timestamp_Collector                   import Timestamp_Collector
 
 
 class Timestamp_Collector__Report(Type_Safe):
 
     collector: Timestamp_Collector = None
 
-    def format_report(self, show_self_time: bool = True) -> str:                # Format comprehensive timing report
+    MIN_METHOD_WIDTH = 40                                                        # Minimum width for method column
+    MAX_METHOD_WIDTH = 80                                                        # Maximum width to prevent excessive stretching
+
+    def _calculate_method_width(self, names: list) -> int:                       # Calculate optimal column width
+        if not names:
+            return self.MIN_METHOD_WIDTH
+        max_name_len = max(len(name) for name in names)
+        return min(max(max_name_len + 2, self.MIN_METHOD_WIDTH), self.MAX_METHOD_WIDTH)
+
+    def _calculate_total_width(self, method_width: int) -> int:                  # Calculate total line width
+        return method_width + 50                                                 # method + calls + total + self + avg + %
+
+    def format_report(self, show_self_time: bool = True) -> str:                 # Format comprehensive timing report
+        analysis = Timestamp_Collector__Analysis(collector=self.collector)
+        timings  = analysis.get_method_timings()
+
+        method_names  = list(timings.keys()) if timings else []
+        method_width  = self._calculate_method_width(method_names)
+        total_width   = self._calculate_total_width(method_width)
+
         lines = []
-        lines.append("=" * 100)
+        lines.append("=" * total_width)
         lines.append(f"Timestamp Report: {self.collector.name}")
-        lines.append("=" * 100)
+        lines.append("=" * total_width)
         lines.append("")
 
         total_ms = self.collector.total_duration_ms()
@@ -27,20 +47,17 @@ def format_report(self, show_self_time: bool = True) -> str:                # Fo
         lines.append(f"  Methods Traced : {self.collector.method_count()}")
         lines.append("")
 
-        analysis = Timestamp_Collector__Analysis(collector=self.collector)
-        timings  = analysis.get_method_timings()
-
         if timings:
             lines.append("Method Timings (sorted by total time):")
-            lines.append("-" * 100)
+            lines.append("-" * total_width)
 
             if show_self_time:
-                header = f"{'Method':<50} {'Calls':>6} {'Total':>10} {'Self':>10} {'Avg':>8} {'%Total':>7}"
+                header = f"{'Method':<{method_width}} {'Calls':>6} {'Total':>10} {'Self':>10} {'Avg':>9} {'%Total':>7}"
             else:
-                header = f"{'Method':<50} {'Calls':>6} {'Total(ms)':>10} {'Avg(ms)':>10} {'%Total':>7}"
+                header = f"{'Method':<{method_width}} {'Calls':>6} {'Total(ms)':>10} {'Avg(ms)':>10} {'%Total':>7}"
 
             lines.append(header)
-            lines.append("-" * 100)
+            lines.append("-" * total_width)
 
             sorted_timings = analysis.get_timings_by_total()
             total_ns       = self.collector.total_duration_ns()
@@ -50,27 +67,37 @@ def format_report(self, show_self_time: bool = True) -> str:                # Fo
 
                 if show_self_time:
                     lines.append(
-                        f"{mt.name:<50} {mt.call_count:>6} "
+                        f"{mt.name:<{method_width}} {mt.call_count:>6} "
                         f"{method_timing__total_ms(mt):>9.2f}ms {method_timing__self_ms(mt):>9.2f}ms "
-                        f"{method_timing__avg_ms(mt):>7.3f}ms {pct:>6.1f}%"
+                        f"{method_timing__avg_ms(mt):>8.3f}ms {pct:>6.1f}%"
                     )
                 else:
                     lines.append(
-                        f"{mt.name:<50} {mt.call_count:>6} "
+                        f"{mt.name:<{method_width}} {mt.call_count:>6} "
                         f"{method_timing__total_ms(mt):>10.2f} {method_timing__avg_ms(mt):>10.3f} {pct:>6.1f}%"
                     )
 
         lines.append("")
-        lines.append("=" * 100)
+        lines.append("=" * total_width)
         return "\n".join(lines)
 
-    def format_timeline(self, max_entries: int = 100) -> str:                   # Format timeline view
+    def format_timeline(self, max_entries: int = 100) -> str:                    # Format timeline view
+        entries = self.collector.entries[:max_entries]
+
+        # Calculate width based on deepest indent + longest name
+        if entries:
+            max_indent    = max(entry.depth for entry in entries) * 2
+            max_name_len  = max(len(entry.name) for entry in entries)
+            content_width = 12 + max_indent + 2 + max_name_len                   # timestamp + indent + marker + name
+            total_width   = max(80, content_width + 2)
+        else:
+            total_width = 80
+
         lines = []
-        lines.append("=" * 80)
+        lines.append("=" * total_width)
         lines.append("Execution Timeline")
-        lines.append("=" * 80)
+        lines.append("=" * total_width)
 
-        entries = self.collector.entries[:max_entries]
         if len(self.collector.entries) > max_entries:
             lines.append(f"(showing first {max_entries} of {len(self.collector.entries)} entries)")
 
@@ -80,35 +107,39 @@ def format_timeline(self, max_entries: int = 100) -> str:                   # Fo
             marker    = "▶" if entry.event == 'enter' else "◀"
             lines.append(f"{offset_ms:>10.3f}ms {indent}{marker} {entry.name}")
 
-        lines.append("=" * 80)
+        lines.append("=" * total_width)
         return "\n".join(lines)
 
-    def format_hotspots(self, top_n: int = 10) -> str:                          # Format hotspot analysis (by self-time)
-        lines = []
-        lines.append("=" * 80)
-        lines.append(f"Top {top_n} Hotspots (by self-time)")
-        lines.append("=" * 80)
-
+    def format_hotspots(self, top_n: int = 10) -> str:                           # Format hotspot analysis (by self-time)
         analysis = Timestamp_Collector__Analysis(collector=self.collector)
         hotspots = analysis.get_hotspots(top_n)
         total_ns = self.collector.total_duration_ns()
 
+        # Calculate width based on longest method name
+        if hotspots:
+            method_names = [mt.name for mt in hotspots]
+            method_width = self._calculate_method_width(method_names)
+        else:
+            method_width = self.MIN_METHOD_WIDTH
+
+        total_width = method_width + 40                                          # method + rank + timing + percentage + calls
+
+        lines = []
+        lines.append("=" * total_width)
+        lines.append(f"Top {top_n} Hotspots (by self-time)")
+        lines.append("=" * total_width)
+
         for i, mt in enumerate(hotspots, 1):
             pct = (mt.self_ns / total_ns * 100) if total_ns > 0 else 0
             lines.append(
-                f"  {i:>2}. {mt.name:<45} "
+                f"  {i:>2}. {mt.name:<{method_width}} "
                 f"{method_timing__self_ms(mt):>8.2f}ms ({pct:>5.1f}%) "
                 f"[{mt.call_count} calls]"
             )
 
-        lines.append("=" * 80)
+        lines.append("=" * total_width)
         return "\n".join(lines)
 
-    def print_all(self):
-        self.print_report  ()
-        self.print_timeline()
-        self.print_hotspots()
-
     def print_report(self, show_self_time: bool = True):
         print(self.format_report(show_self_time))