Merge pull request certinia#716 from lukecotter/feat-timeline-governorlimits

feat: timeline - governor limits strip

Author: lcottercertinia

CHANGELOG.md

@@ -24,6 +24,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
       - **Scroll** → zoom (vertical) or pan (horizontal)
       - **Double-click** → reset to full timeline view
     - **Keyboard shortcuts** (when hovering minimap): Arrow keys pan, `W`/`S` zoom, `Home`/`End` jump, `0` resets.
+  - **📊 Governor Limits Visualization**: New metric strip showing governor limit usage over time. ([#714])
+    - **Traffic Light Coloring**: Instant visual feedback on limit consumption (safe/warning/critical/breach zones).
+    - **Collapsed Mode**: Compact heat-style strip showing max usage across all metrics.
+    - **Expanded Mode**: Full step chart with individual metric lines (click chevron or `Shift+Click` to toggle).
+    - **Smart Tooltips**: Hover to see detailed breakdown with top metrics, always-visible core limits (CPU, Heap, SOQL, DML), and usage percentages.
+    - **Tier Classification**: Metrics auto-classified by usage—Tier 1 (top 3), Tier 2 (>80%), Tier 3 (others aggregated).
+    - **Synced Navigation**: Zoom, pan, and cursor synchronized with main timeline.
   - **Adaptive Frame Bucketing**: Reveals nested frame detail and stack structure as you zoom, automatically adjusting frame granularity to understand complex call hierarchies.
   - **Dynamic Frame Labels**: Labels automatically appear on timeline frames as you zoom and pan, making log scanning and navigation effortless without manually hovering to see event details. ([#92])
   - **Keyboard and Mouse Navigation**: Comprehensive interaction controls for the timeline. ([#573] [#366] [#296] [#295] [#535])
@@ -459,6 +466,7 @@ Skipped due to adopting odd numbering for pre releases and even number for relea
 
 <!-- Unreleased -->
 
+[#714]: https://github.com/certinia/debug-log-analyzer/issues/714
 [#245]: https://github.com/certinia/debug-log-analyzer/issues/245
 [#164]: https://github.com/certinia/debug-log-analyzer/issues/164
 [#535]: https://github.com/certinia/debug-log-analyzer/issues/535

README.md

@@ -90,6 +90,7 @@ The Timeline view shows a live visualization of your Salesforce Apex log executi
 - **Zoom & Pan** – Navigate your logs down to 0.001 ms with precision zoom. `W`/`S` keys or scroll wheel for zoom; `A`/`D` keys or drag for pan.
 - **Dynamic Frame Labels** – Instantly see method names on timeline frames for faster scanning.
 - **🗺️ Minimap** – Bird's-eye view with skyline overview showing call stack depth, viewport lens for navigation, and instant teleport to any position.
+- **📊 Governor Limits Strip** – At-a-glance limit usage with traffic light coloring (safe/warning/critical/breach). Expand for detailed step chart.
 - **📏 Measure Range** – `Shift+Drag` to measure the duration between any two points. Resize edges, double-click to zoom.
 - **🔍 Area Zoom** – `Alt/Option+Drag` to select a region and instantly zoom to fit.
 - **Tooltips** – Hover for duration, event name, SOQL/DML/Exception counts, SOQL/DML rows, and more.

lana-docs-site/docs/docs/features/timeline.md

@@ -86,6 +86,72 @@ When hovering over the viewport lens or dragging, a label appears showing:
 - The **duration** of the selected time range (e.g., "1.23s")
 - The **time range** start and end (e.g., "0.5s - 1.73s")
 
+## Governor Limits Strip
+
+The Governor Limits strip displays Salesforce governor limit usage over time, positioned below the main timeline. It provides instant visual feedback on limit consumption to help identify potential limit breaches.
+
+### Display Modes
+
+#### Collapsed Mode (Default)
+
+A compact heat-style visualization showing the maximum limit usage across all metrics at each point in time.
+
+**Traffic Light Colors:**
+
+| Usage Range | Color        | Meaning  |
+| ----------- | ------------ | -------- |
+| 0-50%       | Transparent  | Safe     |
+| 50-80%      | Amber/Orange | Warning  |
+| 80-100%     | Red          | Critical |
+| >100%       | Purple       | Breach   |
+
+#### Expanded Mode
+
+Click the chevron icon (◀/▼) in the top-left corner or `Shift+Click` anywhere to expand to a full step chart showing:
+
+- **Tier 1 Metrics**: Top 3 metrics by usage (solid colored lines)
+- **Tier 2 Metrics**: Any metric exceeding 80% (solid colored lines)
+- **Tier 3 Metrics**: Remaining metrics (aggregated as grey dashed line)
+- **Danger Zone**: Semi-transparent band from 80-100%
+- **100% Limit Line**: Red dashed line at the limit threshold
+- **Breach Areas**: Purple shading for values above 100%
+
+### Mouse Interactions
+
+| Action          | Mouse                          | Result                            |
+| --------------- | ------------------------------ | --------------------------------- |
+| Toggle View     | Click chevron or `Shift+Click` | Switch between collapsed/expanded |
+| Show Tooltip    | Hover                          | Display metric breakdown          |
+| Center Timeline | Click on strip                 | Pan timeline to clicked position  |
+| Zoom            | Scroll (vertical)              | Zoom at cursor position           |
+| Pan             | Scroll (horizontal)            | Move timeline left/right          |
+| Reset View      | Double-click                   | Fit entire timeline               |
+
+### Keyboard Shortcuts
+
+When your mouse is hovering over the Governor Limits strip, these keyboard shortcuts are available:
+
+| Key            | Action                                      |
+| -------------- | ------------------------------------------- |
+| `Arrow Left`   | Pan viewport left (10% of selection width)  |
+| `Arrow Right`  | Pan viewport right (10% of selection width) |
+| `W` / `+`      | Zoom in                                     |
+| `S` / `-`      | Zoom out                                    |
+| `Home`         | Jump to timeline start                      |
+| `End`          | Jump to timeline end                        |
+| `0` / `Escape` | Reset zoom (fit entire timeline)            |
+
+### Tooltip
+
+Hovering over the metric strip displays a detailed breakdown showing:
+
+- **Always-visible metrics**: CPU Time, Heap Size, SOQL Queries, Query Rows, DML Statements, DML Rows
+- **Top 3 by percentage**: Highest usage metrics (if not already shown)
+- **Critical metrics**: Any metric at or above 80%
+- **Summary**: Count of remaining metrics with max percentage
+
+Each row displays: color swatch, metric name, percentage, and used/limit values.
+
 ## Navigation
 
 ### Zoom + Pan

log-viewer/src/core/log-parser/ApexLogParser.ts

@@ -49,6 +49,7 @@ export class ApexLogParser {
     queueableJobsAddedToQueue: { used: 0, limit: 0 },
     mobileApexPushCalls: { used: 0, limit: 0 },
     byNamespace: new Map<string, Limits>(),
+    snapshots: [],
   };
 
   /**

log-viewer/src/core/log-parser/LogEvents.ts

@@ -338,6 +338,7 @@ export class ApexLog extends LogEvent {
     queueableJobsAddedToQueue: { used: 0, limit: 0 },
     mobileApexPushCalls: { used: 0, limit: 0 },
     byNamespace: new Map<string, Limits>(),
+    snapshots: [],
   };
 
   /**
@@ -1092,6 +1093,13 @@ export class LimitUsageForNSLine extends LogEvent {
     }
 
     parser.governorLimits.byNamespace.set(this.namespace, limits);
+
+    // Track snapshots for governor limit visualization
+    parser.governorLimits.snapshots.push({
+      timestamp: this.timestamp,
+      namespace: this.namespace,
+      limits,
+    });
   }
 }
 

log-viewer/src/core/log-parser/types.ts

@@ -34,8 +34,22 @@ export interface Limits {
   mobileApexPushCalls: { used: number; limit: number };
 }
 
+/**
+ * A single governor limit usage snapshot at a point in time.
+ */
+export interface GovernorSnapshot {
+  /** Timestamp in nanoseconds when this limit snapshot was recorded. */
+  timestamp: number;
+  /** Namespace the limits apply to (e.g., 'default', 'MyPackage'). */
+  namespace: string;
+  /** The limit values at this timestamp. */
+  limits: Limits;
+}
+
 export interface GovernorLimits extends Limits {
   byNamespace: Map<string, Limits>;
+  /** Point-in-time snapshots of governor limit usage, ordered by timestamp ascending. */
+  snapshots: GovernorSnapshot[];
 }
 
 export interface LogIssue {

log-viewer/src/features/timeline/__tests__/keyboard-handler.test.ts

@@ -61,6 +61,14 @@ describe('KeyboardHandler', () => {
       onMinimapJumpStart: jest.fn(),
       onMinimapJumpEnd: jest.fn(),
       onMinimapResetZoom: jest.fn(),
+      // Metric strip keyboard callbacks
+      isInMetricStripArea: jest.fn().mockReturnValue(false),
+      onMetricStripPanViewport: jest.fn(),
+      onMetricStripPanDepth: jest.fn(),
+      onMetricStripZoom: jest.fn(),
+      onMetricStripJumpStart: jest.fn(),
+      onMetricStripJumpEnd: jest.fn(),
+      onMetricStripResetZoom: jest.fn(),
     };
 
     handler = new KeyboardHandler(container, viewport, callbacks);

log-viewer/src/features/timeline/optimised/ApexLogTimeline.ts

@@ -19,6 +19,7 @@
 
 import { ContextMenu, type ContextMenuItem } from '../../../components/ContextMenu.js';
 import type { ApexLog, LogEvent } from '../../../core/log-parser/LogEvents.js';
+import type { GovernorSnapshot, Limits } from '../../../core/log-parser/types.js';
 import { vscodeMessenger } from '../../../core/messaging/VSCodeExtensionMessenger.js';
 import { formatDuration } from '../../../core/utility/Util.js';
 import { goToRow } from '../../call-tree/components/CalltreeView.js';
@@ -27,6 +28,8 @@ import type {
   EventNode,
   FindEventDetail,
   FindResultsEventDetail,
+  HeatStripMetric,
+  HeatStripTimeSeries,
   ModifierKeys,
   TimelineMarker,
   TimelineOptions,
@@ -38,6 +41,39 @@ import { logEventToTreeNode } from '../utils/tree-converter.js';
 import { FlameChart } from './FlameChart.js';
 import { TimelineTooltipManager } from './TimelineTooltipManager.js';
 
+/**
+ * Apex-specific metric definitions for heat strip visualization.
+ * "Big 4" limits (CPU, SOQL, DML, Heap) have priority < 4 and are always shown.
+ * Other limits have priority >= 4 and are only shown when > 0%.
+ */
+const APEX_METRICS: Map<keyof Limits, HeatStripMetric> = new Map([
+  ['cpuTime', { id: 'cpuTime', displayName: 'CPU Time', unit: 'ms', priority: 0 }],
+  ['soqlQueries', { id: 'soqlQueries', displayName: 'SOQL Queries', unit: '', priority: 1 }],
+  ['dmlStatements', { id: 'dmlStatements', displayName: 'DML Statements', unit: '', priority: 2 }],
+  ['heapSize', { id: 'heapSize', displayName: 'Heap Size', unit: 'bytes', priority: 3 }],
+  ['queryRows', { id: 'queryRows', displayName: 'Query Rows', unit: '', priority: 4 }],
+  ['soslQueries', { id: 'soslQueries', displayName: 'SOSL Queries', unit: '', priority: 5 }],
+  ['dmlRows', { id: 'dmlRows', displayName: 'DML Rows', unit: '', priority: 6 }],
+  [
+    'publishImmediateDml',
+    { id: 'publishImmediateDml', displayName: 'Publish Immediate DML', unit: '', priority: 7 },
+  ],
+  ['callouts', { id: 'callouts', displayName: 'Callouts', unit: '', priority: 8 }],
+  [
+    'emailInvocations',
+    { id: 'emailInvocations', displayName: 'Email Invocations', unit: '', priority: 9 },
+  ],
+  ['futureCalls', { id: 'futureCalls', displayName: 'Future Calls', unit: '', priority: 10 }],
+  [
+    'queueableJobsAddedToQueue',
+    { id: 'queueableJobsAddedToQueue', displayName: 'Queueable Jobs', unit: '', priority: 11 },
+  ],
+  [
+    'mobileApexPushCalls',
+    { id: 'mobileApexPushCalls', displayName: 'Mobile Push Calls', unit: '', priority: 12 },
+  ],
+]);
+
 interface ApexTimelineOptions extends TimelineOptions {
   themeName?: string | null;
 }
@@ -157,6 +193,14 @@ export class ApexLogTimeline {
 
     // Wire up search event listeners
     this.enableSearch();
+
+    // Transform and set heat strip time series data for visualization
+    if (apexLog.governorLimits.snapshots.length > 0) {
+      const heatStripSeries = this.transformGovernorToHeatStrip(apexLog.governorLimits.snapshots);
+      this.flamechart.setHeatStripTimeSeries(heatStripSeries);
+    } else {
+      this.flamechart.setHeatStripTimeSeries(null);
+    }
   }
 
   /**
@@ -868,4 +912,42 @@ export class ApexLogTimeline {
 
     document.dispatchEvent(event);
   }
+
+  // ============================================================================
+  // APEX-SPECIFIC DATA TRANSFORMATION
+  // ============================================================================
+
+  /**
+   * Transform Apex-specific governor snapshots to generic HeatStripTimeSeries.
+   * This converts Apex governor limits data to the generic format expected by
+   * the heat strip visualization components.
+   *
+   * @param snapshots - Apex governor limit snapshots
+   * @returns Generic heat strip time series
+   */
+  private transformGovernorToHeatStrip(snapshots: GovernorSnapshot[]): HeatStripTimeSeries {
+    // Convert APEX_METRICS to string-keyed Map for the generic interface
+    const metrics = new Map<string, HeatStripMetric>();
+    for (const [key, metric] of APEX_METRICS) {
+      metrics.set(key, metric);
+    }
+
+    // Transform snapshots to events
+    const events = snapshots.map((snapshot) => {
+      const values = new Map<string, { used: number; limit: number }>();
+      for (const [key, value] of Object.entries(snapshot.limits) as [
+        keyof Limits,
+        { used: number; limit: number },
+      ][]) {
+        values.set(key, { used: value.used, limit: value.limit });
+      }
+      return {
+        timestamp: snapshot.timestamp,
+        namespace: snapshot.namespace,
+        values,
+      };
+    });
+
+    return { metrics, events };
+  }
 }

log-viewer/src/features/timeline/optimised/CLAUDE.md

@@ -24,6 +24,18 @@ import type { LogEvent } from '../../../core/log-parser/LogEvents.js';
 
 The `flamechart.types.ts` file re-exports necessary types from external modules, keeping dependencies contained at the boundary.
 
+### Metric Strip Architecture
+
+The metric strip visualization (governor limits) is rendered below the main timeline and above the minimap:
+
+- `MetricStripOrchestrator` manages the metric strip lifecycle and interactions
+- `MetricStripRenderer` renders step charts for governor limit metrics
+- `MetricStripManager` processes `HeatStripTimeSeries` data and classifies metrics into tiers
+- `ApexLogTimeline` transforms `GovernorSnapshot[]` → `HeatStripTimeSeries`
+- Apex-specific display names, units, and priority order are defined ONLY in ApexLogTimeline
+
+The metric strip supports collapsed (heat-style) and expanded (step chart) views, toggled via a chevron icon.
+
 ## Spatial Queries: Use TemporalSegmentTree
 
 **Always use TemporalSegmentTree (via RectangleManager) for frame queries. Never traverse the event tree directly.**
@@ -266,12 +278,18 @@ Tests should focus on the manager's API, not internal implementation.
    - Use instanced rendering where possible
    - Minimize state changes
 
-4. **Profile before optimizing**
+4. **Use Mesh for filled shapes, Graphics for lines**
+   - Mesh-based rendering (RectangleGeometry + custom shader) for rectangles/filled shapes
+   - Single draw call for many rectangles, much faster than Graphics
+   - Keep Graphics for thin lines (step charts, dashed lines) - mesh overhead not justified
+   - See `MeshRectangleRenderer`, `MeshMetricStripRenderer` for examples
+
+5. **Profile before optimizing**
    - Use Chrome DevTools Performance tab
    - Measure frame time, not just "feels fast"
    - Target 60fps (16.6ms frame budget)
 
-5. **Cache computed values**
+6. **Cache computed values**
    - Viewport transforms
    - Color conversions
    - Text measurements