Add custom path-specific metrics proposal

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: 2 people

custom-metrics-proposal.md

@@ -0,0 +1,106 @@
+# Custom Path-Specific Metrics for GVisor
+
+## Motivation
+
+Current GVisor metrics provide general filesystem and network access information, but lack path-specific granularity that is crucial for understanding application behavior. Many use cases require tracking access patterns to specific directories or file systems to optimize performance, ensure security compliance, and enable better observability.
+
+For example, organizations need to:
+- Monitor access patterns to sensitive directories
+- Track filesystem usage by application components  
+- Understand data flow patterns for optimization
+- Enable fine-grained debugging of filesystem bottlenecks
+
+The existing GVisor metrics system provides excellent general visibility but cannot answer questions like "how often are specific paths being accessed?" or "which applications are reading/writing to particular directories?" This gap limits the effectiveness of performance analysis and security monitoring.
+
+## Proposed Solutions
+
+We propose two approaches to extend GVisor's metrics system with path-specific tracking capabilities:
+
+### Solution 1: Full Syscall Configuration (Recommended)
+
+**Overview**: Implement a new `--path-metrics-config` flag that accepts a YAML configuration file specifying both path prefixes to monitor AND which specific syscalls to track for each path.
+
+**Implementation**: 
+- Add command-line flag for runtime configuration
+- YAML config format for specifying monitored paths and specific syscalls
+- Filesystem layer modifications to intercept and track configured syscalls
+- Emit separate metrics counters for each path-syscall combination
+
+**Usage**:
+```bash
+# Runtime integration
+runsc create --path-metrics-config=/etc/gvisor/path-metrics.yaml container_id
+
+# Docker integration  
+docker run --runtime=runsc \
+  --runtime-arg="--path-metrics-config=/etc/gvisor/path-metrics.yaml" \
+  --name=container image
+```
+
+**Configuration Example**:
+```yaml
+path_metrics:
+  - path_prefix: "/mnt/data"
+    syscalls: ["open", "openat", "read", "write", "pread", "pwrite", "stat", "fstat", "close"]
+  - path_prefix: "/app/storage"  
+    syscalls: ["open", "read", "write", "stat"]
+  - path_prefix: "/tmp"
+    syscalls: ["open", "write", "close"]
+```
+
+**Benefits**:
+- Maximum flexibility for different monitoring needs
+- Can track any syscall pattern for specific paths
+- Extensible to new paths and syscall combinations
+- Upstream acceptance potential due to comprehensive utility
+- Fine-grained control over performance impact
+
+**Trade-offs**:
+- More complex configuration management
+- Higher implementation complexity
+- Requires deeper syscall interception
+
+### Solution 2: Simplified Path-Only Configuration
+
+**Overview**: Implement a streamlined configuration approach that only requires specifying path prefixes, automatically tracking the most commonly needed metrics (read and write operations) for those paths.
+
+**Implementation**:
+- Same `--path-metrics-config` flag but simplified config format
+- Automatically tracks read/write operations and byte counts
+- Focus on the most popular use case (file access patterns)
+- Simpler filesystem layer modifications
+
+**Configuration Example**:
+```yaml
+monitored_paths:
+  - "/mnt/data"
+  - "/app/storage" 
+  - "/tmp"
+```
+
+**Automatic Metrics Emitted**:
+- `read_operations_count`
+- `write_operations_count` 
+- `bytes_read`
+- `bytes_written`
+
+**Benefits**:
+- Simple configuration - just specify paths
+- Covers most common monitoring needs (read/write patterns)
+- Easier to deploy and maintain
+- Lower implementation complexity
+- Still configurable and flexible for path selection
+
+**Trade-offs**:
+- Less granular than full syscall tracking
+- Fixed to read/write metrics only
+- Cannot track other syscalls like stat, open patterns
+
+## Next Steps
+
+Both solutions use the same flag mechanism and can be implemented incrementally. We'd appreciate feedback on:
+
+1. Which approach better aligns with GVisor's design philosophy
+2. Any concerns about the proposed configuration formats
+3. Preferred implementation approach for the filesystem layer modifications
+4. Interest in upstream contribution and collaboration