prometheus.client 是 c# 中最轻量、兼容性最佳的指标暴露库，支持 counter、gauge、histogram，无需手动实现文本格式或 http 端点，.net 6+ 控制台与 asp.net core 均可使用，推荐静态定义指标并正确配置端点、标签与 buckets。
用 Prometheus.Client 库暴露基础指标最简单
直接上手不用自己实现文本格式输出或 HTTP 端点，Prometheus.Client 是目前 C# 生态最轻量、兼容性最好的选择。它默认启用 /metrics 端点，支持 Counter、Gauge、Histogram 三类核心指标，且不依赖 ASP.NET Core 的完整中间件管道（.NET 6+ 控制台应用也能跑）。
实操建议：
- 安装 NuGet 包：
Prometheus.Client（注意不是过时的Prometheus.Client.AspNetCore） - 在
Program.cs中注册服务并启动 HTTP 服务器（非 Kestrel）：var metricServer = new MetricServer(port: 9091); metricServer.Start();
- 全局定义指标（推荐 static readonly）：
public static readonly Counter TotalRequests = Metrics.CreateCounter("app_total_requests", "Total HTTP requests received"); - 在业务逻辑中调用
TotalRequests.Inc()或TotalRequests.Inc(1.5)（支持 float 值）
ASP.NET Core 项目里用中间件更自然
如果你的应用已是 ASP.NET Core（6/7/8），用 UsePrometheusServer() 中间件比手动启 MetricServer 更符合生命周期管理，还能自动集成到 WebHostBuilder。
常见错误现象：
- 端点返回 404：没调用
UsePrometheusServer()，或顺序错（必须在UseRouting()之后、UseEndpoints()之前） - 指标值始终为 0：在
Startup.ConfigureServices()或Program.cs中漏掉AddMetrics()（该扩展注册了内部单例收集器） - 多实例部署时指标混在一起：没设置
InstanceLabel，导致 Prometheus 拉取时无法区分不同 Pod/IP
实操建议：
- 注册服务：
builder.Services.AddMetrics();
- 配置中间件：
app.UsePrometheusServer(options => { options.MetricsEndpoint = "/metrics"; }); - 若需区分实例，初始化时加标签：
Metrics.DefaultRegistry.SetInstanceLabel("my-app-v1-abc123");
自定义 Histogram 需要明确 buckets 和 label 组合
HTTP 延迟、数据库查询耗时这类分布型指标，不能只用 Gauge 记最大值——得用 Histogram 才能被 Prometheus 的 rate()、histogram_quantile() 正确计算。
容易踩的坑：
- 没指定
buckets：默认只有 10 个等距桶（0.005~10 秒），对微秒级或分钟级操作完全失真 - label 键名含非法字符（如空格、破折号）：Prometheus 解析失败，整个
/metrics返回 500 - 同一
Histogram实例被多个线程并发Observe()：没问题，库已线程安全；但若反复创建新实例（比如按 controller 名动态 new），会内存泄漏
实操示例（记录带 status 和 method 标签的 API 延迟）：
public static readonly Histogram ApiDuration = Metrics.CreateHistogram(
"api_request_duration_seconds",
"API request duration in seconds",
new HistogramConfiguration
{
Buckets = Histogram.LinearBuckets(0.01, 0.05, 20), // 0.01~1.0s，步长 0.05s
LabelNames = new[] { "method", "status" }
});
<p>// 使用时：
ApiDuration.WithLabels("GET", "200").Observe(elapsed.TotalSeconds);
拉取失败？先检查 /metrics 响应格式和内容
Prometheus 抓取失败，80% 情况下不是配置问题，而是你的端点返回了非标准格式——比如加了 HTML 头、JSON 封装、或者指标行里有未转义的换行/空格。
验证步骤：
- curl 直接访问：
curl -v http://localhost:9091/metrics，确认状态码是 200，Content-Type 是text/plain; version=0.0.4 - 响应体必须是纯文本，每行一个指标，形如：
# HELP app_total_requests Total HTTP requests received # TYPE app_total_requests counter app_total_requests 123
- 禁止出现：
{}、"、\n在指标值内、任意 HTML 标签、BOM 头 - 如果用了反向代理（Nginx / Traefik），确认它没重写
Content-Type或缓存/metrics
复杂点往往藏在细节里：比如开发机时间不对导致 TLS 证书校验失败（即使你用 HTTP）、Docker 容器没暴露对应端口、K8s Service 的 targetPort 写成字符串而非数字——这些都比指标代码本身更容易卡住。
