Documentation

Overview

Metreja is a CLI-first .NET profiler designed to be driven by AI coding agents. Every operation is a command. Every output is machine-readable NDJSON. The full measure-analyze-fix loop runs without human intervention.

It consists of two components: a native C++ profiler DLL that attaches to the .NET runtime via COR_PROFILER environment variables, and a C# CLI tool for session management and trace analysis.

Installation

Prerequisites: .NET 8 SDK or later, Windows 10/11 (x64).

dotnet tool install -g Metreja.Tool

After installation, the metreja command is available globally in your terminal.

Quick Start

Five commands from zero to actionable hotspot data:

# 1. Create a session
SESSION=$(metreja init --scenario "baseline")

# 2. Tell it what to trace (your code, not the framework)
metreja add include -s $SESSION --assembly MyApp
metreja add exclude -s $SESSION --assembly "System.*"
metreja add exclude -s $SESSION --assembly "Microsoft.*"

# 3. Generate the profiler environment and run your app
metreja generate-env -s $SESSION --format shell > env.sh
source env.sh && dotnet run --project src/MyApp -c Release

# 4. Find the bottleneck
metreja hotspots .metreja/output/*.ndjson --top 10

# 5. Drill into the slowest method
metreja calltree .metreja/output/*.ndjson --method "ValidateInventory"

Commands

Analysis commands read NDJSON trace files produced by the profiler. Pass a file path or a glob pattern as the first argument.

hotspots

Per-method timing ranked by self time, inclusive time, call count, or allocation count.

metreja hotspots trace.ndjson --top 10 --sort self
metreja hotspots trace.ndjson --filter "MyApp.Services" --min-ms 1

calltree

Call tree for a specific method invocation, slowest first.

metreja calltree trace.ndjson --method "ProcessOrder"
metreja calltree trace.ndjson --method "ProcessOrder" --occurrence 2

callers

Who calls a method, with call count and timing per caller.

metreja callers trace.ndjson --method "SaveChanges" --top 10

memory

GC summary (generation counts, pause times) and per-type allocation hotspots.

metreja memory trace.ndjson --top 20
metreja memory trace.ndjson --filter "System.String"

analyze-diff

Compare two traces. Shows per-method timing delta (base vs. compare).

metreja analyze-diff baseline.ndjson optimized.ndjson

report

Report an issue to the GitHub repository. Requires the GitHub CLI (gh) installed and authenticated.

metreja report --title "Bug: crash on empty trace" --description "Detailed description."

Exit codes: 0 success · 1 failed · 2 gh not installed · 3 gh not authenticated

Session Management

Sessions store profiler configuration in .metreja/sessions/{sessionId}.json. Each session has a unique 6-hex-char ID.

init

Create a new profiling session. Returns a random session ID.

metreja init
metreja init --scenario "before-refactor"

add include / add exclude

Add filter rules controlling which methods get traced. Supports wildcards (*).

metreja add include -s a1b2c3 --assembly MyApp
metreja add include -s a1b2c3 --assembly MyApp --namespace "MyApp.Core"
metreja add exclude -s a1b2c3 --assembly "System.*"
metreja add exclude -s a1b2c3 --class "*Generated*"

generate-env

Generate a script that sets the environment variables to attach the profiler to your app.

metreja generate-env -s a1b2c3                    # Windows batch
metreja generate-env -s a1b2c3 --format powershell  # PowerShell
metreja generate-env -s a1b2c3 --format shell       # bash/sh

set

Configure session settings via subcommands.

validate

Check session configuration for errors. Exits with code 1 on failure.

metreja validate -s a1b2c3

flush

Trigger an on-demand stats flush on a running profiled process. Useful when the profiled process may be force-killed before a periodic flush occurs, or when statsFlushIntervalSeconds is set to 0 (manual-only mode).

metreja flush --pid 12345

The profiler creates a named Windows event MetrejaFlush_{pid} for IPC signaling. The flush thread responds to both periodic timeouts and manual flush signals.

clear

Delete profiling sessions.

metreja clear -s a1b2c3   # delete one session
metreja clear --all       # delete all sessions

Session Config Format

Stored at .metreja/sessions/{sessionId}.json:

{
  "sessionId": "a1b2c3",
  "metadata": { "scenario": "baseline" },
  "instrumentation": {
    "maxEvents": 0,
    "computeDeltas": true,
    "statsFlushIntervalSeconds": 30,
    "includes": [
      { "assembly": "MyApp", "namespace": "*", "class": "*", "method": "*" }
    ],
    "excludes": []
  },
  "output": {
    "path": ".metreja/output/{sessionId}_{pid}.ndjson"
  }
}

Output path tokens:

Architecture

Metreja is a two-component system:

Data flow: CLI creates session config → generate-env sets profiler env vars → profiled app loads DLL → DLL writes NDJSON → CLI analysis commands read NDJSON.

Building from Source

Prerequisites: Windows 10/11 (x64), .NET 10 SDK (multi-targets .NET 8/9/10), Visual Studio 2022 Build Tools with "Desktop development with C++" workload.

# Build components
dotnet build src/Metreja.Tool/Metreja.Tool.csproj -c Release
msbuild src/Metreja.Profiler/Metreja.Profiler.vcxproj /p:Configuration=Release /p:Platform=x64

# Run integration tests
dotnet test test/Metreja.IntegrationTests/Metreja.IntegrationTests.csproj -c Release

# Format C++ code
scripts/format-cpp.bat

Build outputs:

Claude Code Plugin

The metreja-profiler plugin for Claude Code enables fully automated profiling sessions. Install it and ask questions in plain English — Claude handles session setup, profiling, analysis, and fix suggestions automatically.

/plugin marketplace add kodroi/metreja-profiler-marketplace
/plugin install metreja-profiler@metreja-profiler-marketplace

After installation, just ask: "This endpoint takes 3 seconds, find out why" or "Where am I wasting memory?"

Requires Metreja.Tool to be installed globally (dotnet tool install -g Metreja.Tool).