Linux Client Diagnostics Agent

A specialized GitHub Copilot agent for analyzing Linux kernel SMB (cifs.ko) and NFS client diagnostic captures.

Overview

This agent helps diagnose issues with Linux SMB and NFS client mounts by analyzing diagnostic captures produced by:

• SMB: SMBDiagnostics/smbclientlogs.sh from azure-files-samples
• NFS: NfsDiagnostics/nfsclientlogs.sh from azure-files-samples

The agent interprets kernel trace events (trace-cmd / tracepoints), DebugData, Stats, open_files, mountstats, nfsstat, dmesg, and process callstacks to diagnose:

• Connectivity issues
• Performance bottlenecks
• Authentication failures
• Lease/delegation problems
• Credit/slot management issues

Structure

linux-client-diag-agent/
├── Linux-client-diag-analysis-agent.agent.md     # Agent definition
├── skills/
│   ├── smb-client-diag/
│   │   └── SKILL.md                             # SMB diagnostic knowledge
│   └── nfs-client-diag/
│       └── SKILL.md                             # NFS diagnostic knowledge
└── README.md                                     # This file

Usage

In VS Code

To use this agent in VS Code:

1. Add this directory to your VS Code workspace
2. The agent will be available in the Copilot agent selector as Linux-client-diag-analysis-agent
3. When you invoke the agent, paste diagnostic captures or describe symptoms

Example invocation:

@linux-client-diag-analysis-agent
Paste your cifs_diag.txt and cifs_trace files here and describe the issue

Skills

The agent has two associated skills:

• SMB Client Diagnostics (skills/smb-client-diag/SKILL.md)

  • Comprehensive reference for analyzing SMB capture files
  • Covers DebugData, Stats, open_files, tracepoints, and error codes
  • Includes common issue patterns and diagnostics checklists

• NFS Client Diagnostics (skills/nfs-client-diag/SKILL.md)

  • Reference for analyzing NFS capture files
  • Covers mountstats, nfsstat, tracepoints, and RPC debugging
  • Includes NFSv4 error codes and common issues

Key Features

✅ Trace Analysis

• Interprets kernel tracepoints from trace-cmd (cifs and nfs subsystems)
• Maps SMB2/SMB3 command codes to operations
• Correlates timestamp and event sequences

✅ Credit & Slot Management (SMB-specific)

• Analyzes credit exhaustion and hold times
• Kernel version awareness (6.6 vs 6.8+ differences in netfs integration)
• Identifies parallelism bottlenecks

✅ Lease & Oplock Analysis

• Interprets lease state changes
• Detects lease breaks and acquisition failures
• Tracks handle caching state

✅ Performance Diagnosis

• Per-channel distribution analysis (multichannel SMB)
• Latency measurements and slow-response detection
• Per-connection statistics analysis

✅ Kernel Version Awareness

• Different tracepoints, features, and behaviors across kernel versions
• Documents version-dependent read path differences (pre-netfs vs netfs)
• Helps identify kernel-level bottlenecks

Recent Analysis Examples

SMB3 Read Throughput Analysis

The agent includes detailed analysis of kernel-dependent read path performance:

Finding: Azure Linux 3 (kernel 6.6) achieves 47.5 MB/s vs Ubuntu 24.04 (kernel 6.17) achieving 82.1 MB/s on identical hardware.

Root Cause: Kernel 6.6 uses pre-netfs cifs read path lacking early credit return and subrequest parallelism.

Documentation:

• Report: ../scratch/linux-client-diag-analysis-agent/reports/azl3-vs-ubuntu-throughput-analysis.md
• Journal: ../kernel-knowledge-mcp/journals/fs/smb/client/netfs-credit-management.md
• Journal: ../kernel-knowledge-mcp/journals/fs/smb/client/netfs-subrequest-dispatch.md

Setup for GitHub

This repository is self-contained and ready for GitHub. To use:

1. Clone the repository into your VS Code workspace:

   git clone https://github.com/your-org/linux-client-diag-agent.git
   cd linux-client-diag-agent

2. Open in VS Code and add to workspace

3. Start diagnosing by invoking the agent with diagnostic captures

Contributing

To improve the skills or agent:

1. Make diagnostic observations during analysis
2. Test on real captures from various kernel versions
3. Update the relevant SKILL.md file with new findings
4. Commit changes and push to GitHub

References

• Azure Files Samples Repository — Source of diagnostic collection scripts
• Linux Kernel Documentation
  • fs/smb/client/ — CIFS client source
  • fs/nfs/ — NFS client source
  • fs/netfs/ — Netfs (filesystem cache) layer
• SMB/CIFS Protocol
  • MS-SMB2, MS-SMB3 specifications
• NFS Protocol
  • RFC 7530 (NFSv4), RFC 8881 (NFSv4.1)

License

See LICENSE file in repository root.

---

Last Updated: 2026-07-17
Agent Version: 1.0
Supported Kernels: 6.6 through 6.17+ (with kernel-version-aware diagnostics)