LoggerUsage 1.0.0-preview.5

dotnet-logging-tools

This library is mostly vibe coded using github-copilot with the Claude Sonnet 4 model in agent mode

Create a summary of which log messages a project writes and the parameters to improve consistency

Package	Version	Downloads	Description
LoggerUsage			Core library for analyzing .NET logging usage patterns
LoggerUsage.Cli			Command-line tool for generating HTML/JSON reports
LoggerUsage.Mcp			Model Context Protocol server for AI integrations
LoggerUsage.MSBuild			MSBuild integration for workspace analysis

Background

This tool analyzes .NET projects to extract and summarize logging usage patterns. It supports the following logging APIs:

Supported Logging APIs

• ILogger Extension Methods: Analyzes LoggerExtensions.Log overloads and the level-specific LogInformation, LogWarning, LogError, LogDebug, LogTrace, and LogCritical methods
• Direct ILogger.Log<TState> Calls: Analyzes interface and concrete implementation calls, including log level, event ID, constant string state, and inline KeyValuePair<string, object?> structured state with {OriginalFormat} without executing formatter delegates
• LoggerMessage Attribute: Detects and analyzes methods decorated with [LoggerMessage] attribute for high-performance logging
• LoggerMessage.Define: Analyzes usage of LoggerMessage.Define methods for compile-time log message generation
• Structured Logging: Captures parameter names and templates used in structured logging scenarios

The tool helps identify:

• Inconsistent parameter naming across log messages
• Most commonly used log parameters
• Log level distribution across your codebase
• Template patterns and message structures

Advanced Telemetry Features

The tool also provides advanced telemetry analysis capabilities:

• Custom Tag Names: Detects and tracks custom tag names defined via [TagName] attribute for enhanced structured logging
• Tag Providers: Analyzes tag providers using [TagProvider] attribute for dynamic tag generation and validates their configuration
• Data Classification: Identifies data classification attributes (Public, Internal, Private, Sensitive) for compliance and redaction analysis
• Transitive Properties: Analyzes nested properties when using [LogProperties(Transitive = true)] to track deep object hierarchies

These features enable:

• Better observability through standardized tag naming
• Compliance validation for sensitive data logging
• Understanding of nested property structures in logs
• Identification of tag provider validation issues

Usage

CLI

With the .NET 10 SDK or later installed, run the CLI directly from NuGet without cloning this repository or installing the tool:

dnx LoggerUsage.Cli --prerelease -- <path-to-your-sln-or-csproj> <output-file-name>.<html/json/md/sarif>

Example report:

dnx LoggerUsage.Cli --prerelease -- MySolution.sln report.html

and in dark mode:

Report Features

The generated reports include:

Summary Statistics:

• Total log usages and parameter counts
• Classification breakdown (Public, Internal, Private, Sensitive)
• Telemetry features usage (custom tag names, tag providers, transitive properties)
• Parameter name inconsistencies

Detailed Analysis:

• Individual log usage details with file locations
• Custom tag name mappings
• Tag provider configurations and validation status
• Nested property hierarchies for transitive analysis
• Data classification annotations

Output Formats:

• HTML: Interactive report with collapsible sections, dark mode support, and filtering capabilities
• JSON: Structured data with schema version 2.0 for programmatic analysis
• Markdown: Human-readable report suitable for documentation
• SARIF 2.1.0: Deterministic parameter-consistency findings for GitHub code scanning

GitHub Code Scanning

Generate and upload SARIF in a GitHub Actions workflow:

- name: Generate LoggerUsage SARIF
  run: dnx LoggerUsage.Cli --prerelease -- MySolution.sln artifacts/logger-usage.sarif

- name: Upload LoggerUsage SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: artifacts/logger-usage.sarif

The initial SARIF rules are:

LUT001 Parameter type mismatch

The same logging parameter name is used with conflicting types.

LUT002 Parameter casing inconsistency

Logging parameter names differ only by casing.

SARIF contains actionable consistency findings rather than every extracted logging call. Result ordering, repository-relative paths, and fingerprints are stable across equivalent runs.

Running the MCP Server Locally

To run the MCP server locally:

dotnet run --project src/LoggerUsage.Mcp

By default, the server will use the configuration in src/LoggerUsage.Mcp/appsettings.json. You can modify this file to adjust server settings as needed.

Progress Tracking

The MCP server supports progress tracking for long-running analysis operations. Clients can provide a progressToken parameter when calling the analyze_logger_usages_in_csproj tool to receive real-time progress updates.

Example Usage:

{
  "tool": "analyze_logger_usages_in_csproj",
  "parameters": {
    "fullPathToCsproj": "/path/to/project.csproj",
    "progressToken": "my-progress-token-123"
  }
}

When a progressToken is provided, the server will send notifications/progress messages with the following structure:

{
  "method": "notifications/progress",
  "params": {
    "progressToken": "my-progress-token-123",
    "progress": {
      "progress": 25,
      "total": 100,
      "message": "Analyzing project: 25% complete"
    }
  }
}

Features:

• ✅ Optional parameter (backward compatible - works without progress token)
• ✅ Real-time progress updates during analysis
• ✅ Graceful error handling (progress failures don't interrupt analysis)
• ✅ Low overhead (<5% performance impact)

For more information on MCP progress tracking, see the MCP Progress Documentation.

Roadmap

• Add support for LoggerExtensions.Log overloads
• Add support for direct ILogger.Log<TState> calls
• Add support for ILogger.BeginScope method
• Create a summary of the log messages
• For LoggerMessageAttribute - find all invocations of method (see implementation plan)
• Expose as a MCP
• Add incremental workspace analysis and caching for large solutions
• Add deterministic CI output such as SARIF
• Add symbol-based analysis for custom logging wrappers