Metricy.Extract 0.4.1

dotnet-metricy-extract

CLI tool + annotations library that extract Prometheus metric metadata (name, type, help, description, calculation, labels) from compiled .NET assemblies via static reflection — no application startup required. Companion to the Metricy registry: the extractor emits a JSON snapshot that CI posts to Metricy to keep the metric catalogue up to date.

Installation

# Install the global extraction tool
dotnet tool install -g Metricy.Extract

# Add the annotation attributes to your service project
dotnet add package Metricy.Annotations

Or add the package reference directly in your .csproj:

<PackageReference Include="Metricy.Annotations" Version="0.4.0" />

Usage

dotnet metricy-extract --assembly bin/Debug/net9.0/MyService.dll --output metrics.json

Why

In an era where agents write and maintain dozens of services in parallel, re-analyzing code on every task to answer "what metrics does service X expose, what do they mean, and how are they computed?" is wasteful — each agent run burns tokens rediscovering facts the code already captures. The scalable alternative is a metric registry (the Metricy catalogue) that agents and humans consult directly instead of re-scanning source trees.

For such a registry to stay trustworthy, every metric must be:

1. Described next to the code — business meaning, calculation algorithm, and label semantics annotated on the same line as the Metrics.CreateCounter(...) call, not authored ad-hoc in PR descriptions or a separate wiki.
2. Exported deterministically — the same code in produces the same JSON out, on every build, with no AI-inferred descriptions and no drift between what the registry shows and what the service actually declares.

dotnet-metricy-extract is that export step. Annotate metrics once with [MetricInfo] / [MetricLabel], run the tool in CI on every build, post the JSON snapshot to Metricy. The registry stays current without any agent re-scanning code.

Technical advantage

Standard reflection (Assembly.LoadFrom) runs static initializers — a real service tries to open databases, read environment variables, start background jobs. Without infrastructure, the process crashes before metadata can be read. dotnet-metricy-extract reads the DLL via MetadataLoadContext without executing any code, so extraction works:

• In CI/CD without any infrastructure.
• On developer machines without Docker or databases running.
• On any .NET 6 / 7 / 8 / 9 / 10 assembly (the tool itself targets .NET 10, the target assembly can be any version).

Quick Example

Service code:

using Metricy.Annotations;
using Prometheus;

public static class AppMetrics
{
    [MetricInfo(
        description: "Total incoming HTTP requests across all endpoints.",
        calculation: "Incremented in RequestLoggingMiddleware.InvokeAsync() on each completed request.")]
    [MetricLabel("method", "HTTP method: GET, POST, PUT, DELETE")]
    [MetricLabel("status_code", "HTTP response status code")]
    public static readonly Counter HttpRequests = Metrics.CreateCounter(
        "http_requests_total",
        "Total HTTP requests processed",
        new CounterConfiguration { LabelNames = new[] { "method", "status_code" } });
}

Both attributes use positional constructors — [MetricInfo("desc", "calc")] (positional) and [MetricInfo(description: "desc", calculation: "calc")] (named-argument) are equivalent and both supported.

Extracted JSON (excerpt):

{
  "schema_version": "1.0",
  "project": "MyService",
  "extracted_at": "2026-04-20T10:00:00Z",
  "extractor": { "name": "dotnet-metricy-extract", "version": "0.4.0" },
  "metrics": [
    {
      "name": "http_requests_total",
      "type": "counter",
      "help": "Total HTTP requests processed",
      "description": "Total incoming HTTP requests across all endpoints.",
      "calculation": "Incremented in RequestLoggingMiddleware.InvokeAsync() on each completed request.",
      "labels": [
        { "name": "method", "description": "HTTP method: GET, POST, PUT, DELETE" },
        { "name": "status_code", "description": "HTTP response status code" }
      ],
      "source_location": {
        "file": "src/MyService/Metrics.cs",
        "line": 12,
        "class": "AppMetrics",
        "member": "HttpRequests"
      }
    }
  ]
}

CLI Parameters

Validation

Running --validate checks the extracted snapshot against 16 built-in rules — 7 errors + 8 warnings always-on + 1 warning off-by-default.

Rule catalogue

Use dotnet metricy-extract --list-rules to see the canonical up-to-date list. The current 16 rules:

Typical CI usage

# Block on errors only (default)
dotnet metricy-extract --assembly bin/Debug/net9.0/MyService.dll --validate

# Strict: block on any violation including warnings
dotnet metricy-extract --assembly bin/Debug/net9.0/MyService.dll --validate --strict

# Skip a noisy rule
dotnet metricy-extract --assembly bin/Debug/net9.0/MyService.dll --validate \
  --skip-rule metric.deprecated-not-annotated

# Enable high-cardinality check for strict orgs
dotnet metricy-extract --assembly bin/Debug/net9.0/MyService.dll --validate \
  --enable-rule metric.label-high-cardinality-hint

# Per-rule minimum length overrides
dotnet metricy-extract --assembly bin/Debug/net9.0/MyService.dll --validate \
  --min-description-length 30 \
  --rule-min-length metric.label-description-min-length:5

# Write machine-readable JSON report for agent-driven autofix
dotnet metricy-extract --assembly bin/Debug/net9.0/MyService.dll --validate \
  --validation-report report.json

# Browse the full rule catalogue
dotnet metricy-extract --list-rules

What It Extracts

• [MetricInfo] attributes — description and calculation fields
• [MetricLabel] attributes — per-label descriptions matched by label name
• prometheus-net Metrics.CreateCounter/Gauge/Histogram/Summary calls with:
  • Inline CounterConfiguration/GaugeConfiguration/HistogramConfiguration/SummaryConfiguration with LabelNames
  • String-literal name and help arguments
• Legacy // [Metric] comment blocks — recognized for services still using an earlier comment-block tool's output; each block emits a deprecation warning to stderr. Migrate to [MetricInfo] attributes.
• Source locations (file + line + class + member, repo-root-relative with forward-slash separators) via Roslyn analysis of .cs files when a source root is available

Output JSON Format

Full snapshot example:

{
  "schema_version": "1.0",
  "project": "SampleService",
  "extracted_at": "2026-04-20T10:00:00Z",
  "extractor": {
    "name": "dotnet-metricy-extract",
    "version": "0.4.0"
  },
  "metrics": [
    {
      "name": "http_requests_total",
      "type": "counter",
      "help": "Total HTTP requests processed",
      "description": "Total incoming HTTP requests across all endpoints.",
      "calculation": "Incremented in RequestLoggingMiddleware.InvokeAsync() on each completed request.",
      "labels": [
        {
          "name": "method",
          "description": "HTTP method: GET, POST, PUT, DELETE"
        },
        {
          "name": "status_code",
          "description": "HTTP response status code"
        }
      ],
      "source_location": {
        "file": "src/SampleService/Metrics.cs",
        "line": 17,
        "class": "AppMetrics",
        "member": "HttpRequests"
      }
    },
    {
      "name": "http_request_duration_seconds",
      "type": "histogram",
      "help": "HTTP request duration in seconds",
      "description": "Duration of HTTP request handling from middleware entry to response write.",
      "calculation": "Observed in RequestLoggingMiddleware.InvokeAsync() after downstream pipeline returns.",
      "labels": [
        {
          "name": "endpoint",
          "description": "Route template of the matched endpoint"
        }
      ],
      "source_location": {
        "file": "src/SampleService/Metrics.cs",
        "line": 26,
        "class": "AppMetrics",
        "member": "HttpRequestDurationSeconds"
      }
    }
  ]
}

Top-level fields:

Limitations

Dependencies

Does not depend on: ASP.NET Core, Swashbuckle, Entity Framework, prometheus-net, or any infrastructure packages.

Requirements

• .NET 10 SDK (to run the tool)
• The target assembly's build output directory with all reference DLLs (needed for type resolution)

Building

dotnet build
dotnet test

License

MIT