监控系统简介（二）：使用 App Metrics 在 ASP.NET Web API 中记录指标

最新推荐文章于 2024-09-25 08:44:12 发布

dotNET跨平台

最新推荐文章于 2024-09-25 08:44:12 发布

阅读量1.1k

点赞数

文章标签： java python spring web docker

原文链接：https://bun.dev/posts/introduction-to-monitoring-use-app-metrics-in-asp-net-application

版权

回顾

在《监控系统简介：使用 Prometheus 与 Grafana》一文中，我们了解了什么是监控系统，Prometheus 这一监控工具及它提供的数据类型、PromQL 以及 Grafana 可视化工具的基本用法。今天这一篇我们将在 ASP.NET Web API 项目中进行实战，将 Web API 接口的请求次数、响应耗时、错误率等指标记录下来，并提供给 Prometheus 和 Grafana，用于分析和呈现。

我们主要采用一个名为 App Metrics 的类库记录指标。App Metrics 是以 Apache v2 协议开源的一款类库，支持 .NET Framework 4.5.2 以上，以及 .NET Core 的应用程序。除了记录各种程序生成的指标，它还提供健康检查的功能，但这不在本文的范围内。

为什么没有使用 Prometheus 推荐的 .NET 类库，主要是因为 App Metrics 在 GitHub 的 star 比较多，另外 API 用起来比较顺手而已……

本文示例代码已提交至 Github https://github.com/huhubun/AppMetricsPrometheusSample 欢迎一同讨论。

在 ASP.NET Web API 中记录指标

因为还有一些项目在 .NET Framework 下，所以先以 .NET Framework 的 ASP.NET Web API 开始，通过 Visual Studio 创建“ASP.NET Web 应用程序（.NET Framework）”，框架版本高于或等于 .NET Framework 4.5.2 即可，然后选择 “Web API”。

首先，通过 nuget，将 App Metrics 添加至项目中

Install-Package App.Metrics
Install-Package App.Metrics.Formatters.Prometheus

App Metrics 支持各种各样的监控系统或时序数据库。因为我们最终要将数据提供给 Prometheus，所以除了 App Metrics 的包外，还需要安装一个用于格式化数据的包 App.Metrics.Formatters.Prometheus。

由于这是一个新建的项目，简单起见这里创建一个名为 ApiMetrics 的类，保证 Web API 整个生命周期中只初始化一次 App Metrics。如果项目中有依赖注入容器（例如 AutoFac），则直接将 IMetricsRoot 注册为单例即可（通过 InitAppMetrics() 的代码来创建）。

public class ApiMetrics
{
    private static IMetricsRoot _metrics;

    public static IMetricsRoot GetMetrics()
    {
        if (_metrics == null)
        {
            _metrics = InitAppMetrics();
        }

        return _metrics;
    }

    private static IMetricsRoot InitAppMetrics()
    {
        var metrics = new MetricsBuilder()
                        .Configuration.Configure(options =>
                        {
                            options.DefaultContextLabel = "API";
                            options.AddAppTag(Assembly.GetExecutingAssembly().GetName().Name);
                            options.AddServerTag(Environment.MachineName);

#if DEBUG
                            options.AddEnvTag("Dev");
#else
                            options.AddEnvTag("Release");
#endif

                            options.GlobalTags.Add("my_custom_tag", "MyCustomValue");
                        })
                        .Build();

        return metrics;
    }
}

DefaultContextLabel 的值会成为指标的前缀，这里设置成 API，则默认所有指标都为 api_ 开头
AddAppTag() 会为所有指标添加一个名为 app 的 tag，内容为当前程序的名称
AddServerTag() 会为所有指标添加一个名为 server 的 tag，内容是运行程序的机器名称
AddEnvTag() 会为所有指标添加一个名为 env 的 tag，用于区分运行程序的环境
也可以通过 GlobalTags 属性，来添加自定义的 tag

因为没有依赖注入容器，还需要在 Global.asax 的 Application_Start() 中手动调用一下 GetMetrics() 方法以完成初始化。

protected void Application_Start()
{
    // 省略其他内容

    ApiMetrics.GetMetrics();
}

记录程序启动时间

我们把程序启动的时间作为一项指标，在 Grafana 中就能显示出程序已经运行了多长时间。Prometheus 通过 time() 能得到当前时间的 unix 时间戳，所以我们只需要将程序启动时的时间以 unix 时间戳的方式记录下来即可。

在 Application_Start() 中，当一切准备就绪后通过 App Metrics 创建一个 Gauge：

    var metrics = ApiMetrics.GetMetrics();    // 如果有依赖注入容器，请替换为注入 IMetricsRoot 的代码

    var unixTimestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    metrics.Measure.Gauge.SetValue(new GaugeOptions
    {
        Name = "Boot Time Seconds"
    }, unixTimestamp);

通过 App Metrics 的 Measure 属性可以找到 Gauge 属性，然后通过 SetValue() 方法即可记录指标。指标的各种设置（例如名称）通过参数传入。指标名称 Name 我习惯按可读性高的方式来写，因为 App Metrics 的 Prometheus 格式化器会自动帮我们处理它，后文会说明。

另外，虽然我们创建的是 Gauge，但对于启动时间而言，除了这时的赋值外，这个指标的值是不会改变的。

添加 /metrics 终结点

现在我们已经有一个内容为程序启动时间的指标了，还缺少一个能让 Prometheus 抓取指标数据的地方。因为这是一个 Web API 项目，很简单来创建一个 Web API 控制器 MetricsController：

    [RoutePrefix("metrics")]
    public class MetricsController : ApiController
    {
        [HttpGet]
        [Route("")]
        public async Task<HttpResponseMessage> GetMetricsAsync()
        {
            var formatter = new App.Metrics.Formatters.Prometheus.MetricsPrometheusTextOutputFormatter();
            var snapshot = ApiMetrics.GetMetrics().Snapshot.Get();

            using (var ms = new MemoryStream())
            {
                await formatter.WriteAsync(ms, snapshot);
                var result = Encoding.UTF8.GetString(ms.ToArray());

                var response = Request.CreateResponse(HttpStatusCode.OK);
                response.Content = new StringContent(result, Encoding.UTF8, formatter.MediaType.ContentType);

                return response;
            }
        }
    }

现在启动程序，访问 localhost:端口/metrics 就能看到类似这样的效果：

# HELP api_boot_time_seconds
# TYPE api_boot_time_seconds gauge
api_boot_time_seconds{app="WebAPISample",server="BUNPC",env="Dev",my_custom_tag="MyCustonValue"} 1580913792

App Metrics 的指标类型及转换

由于 App Metrics 的指标类型与 Prometheus 的并不是一一对应的，我们先看看 App Metrics 中提供的类型有哪些：

Apdex 应用性能指数评分，它的含义可以参考《应用性能指标apdex》 https://www.cnblogs.com/tetu/p/4968666.html
Counter 计数器
Gauge gauge
Histogram 直方图
Meter 一个可增减的计数器，一般用于统计次数和速率
Timer 计时器，根据统计的时间，自动进行分组

可以看到，Apdex、Meter 和 Timer 是 Prometheus 中没有的。通过 App.Metrics.Formatters.Prometheus 可以转换成 Prometheus 的指标：

Apdex -> Gauge
Counter -> Counter
Gauge -> Gauge
Histogram -> Histogram
Meter -> Counter，用起来和 Counter 好像也没什么区别…
Timer -> Summary，会自动帮我们计算好 0.5、0.75、0.95、0.99 的分位数

还需要提到的是，通过 App Metrics Prometheus 格式化器，指标的名称也会发生变化，指标名称 Boot Time Seconds 会被转换为 api_boot_time_seconds，空格会自动变为下划线，大写也会被转为小写。所以代码中可以按习惯的方式编写，只要统一即可。

App Metrics 的 API

在 IMetricsRoot 下，我们常用的有这两个属性：

Measure
Provider

通过 Measure 和 Provider 属性都可以访问到所有的指标类型，仔细观察可以发现，通过 Measure 操作指标，方法返回的都是 XXXContext 或者 void，而 Provider 返回的都是 IXXX，来看看方法的定义：

void IMetricsRoot.Measure.Counter.Increment(CounterOptions options, long amount)，只能通过参数列表直接传入值
ICounter IMetricsRoot.Provider.Counter.Instance(CounterOptions options)，可以对该计数器执行 Increment() 增加值、Decrement() 减少值、Reset() 重置等操作（当然，Prometheus 的计数器应该是只增不减的，但因为 App Metrics 并不是专为 Prometheus 设计，所以它的 API 可以这样操作也是可以理解的）

总的来说，区别在于 Measure 中的 API 相当于去测量某些指标，而 Provider 的 API 可以直接为指标赋值。通过 Timer 来看更为明显：

void IMetricsRoot.Measure.Timer.Time(TimerOptions options, Action action) 要求将要统计时间的操作，直接在 Action 中执行，这个 API 会自动开始计时，当 Action 执行完毕后停止计时
TimerContext IMetricsRoot.Measure.Timer.Time(TimerOptions options) 当创建 TimerContext 后开始计时，通过 TimerContext 提供的 Dispose() 方法来停止计时
ITimer IMetricsRoot.Provider.Timer.Instance(TimerOptions options) 通过 Record() 直接设置时间，另外也有 StartRecording()、EndRecording() 等方法手动开始和停止计时

记录 API 响应耗时和请求次数

在 Web API 中，可以通过消息处理程序在请求进入控制器之前，以及响应被生成后，执行一些操作。我们可以通过一个计时器，在收到请求时计时，处理完请求后停止计时的方式，统计一次 HTTP 请求所需要的时间。

确定计时的方案后，需要确定维度。对于 API 的响应耗时，我们应该关注 API 的请求方式（GET、POST、PUT、DELETE等）、API 的路由（/api/values、/api/values/{id}等）、响应状态码这些信息。所以需要在指标中，体现出这几个标签。

最后确认使用何种数据类型。App Metrics 提供了 Timer 类型，能自动生成 0.5、0.99 等分位数，并且转换为 Prometheus 后，它是 summary 类型，意味着还会产生 XXX_sum 和 XXX_count 两个指标。通过 XXX_count ，我们顺便还能把请求次数给计算出来。

新建一个 MetricsHandler 类，代码如下：

    public class MetricsHandler : DelegatingHandler
    {
        private const string API_METRICS_RESPONSE_TIME_KEY = "__ApiMetrics.ResponseTime__";
        private const string API_METRICS_ROUTE = "metrics";

        protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            var routeTemplate = GetRouteTemplate(request);

            // 如果访问的是 /metrics ，则不计入统计中
            if (routeTemplate == API_METRICS_ROUTE)
            {
                return await base.SendAsync(request, cancellationToken);
            }

            StartRecordingResponseTime(request);

            var response = await base.SendAsync(request, cancellationToken);

            EndRecordingResponseTime(routeTemplate, request, response);

            return response;
        }

        private string GetRouteTemplate(HttpRequestMessage request)
        {
            // MS_SubRoutes 适用于 Route Attribute 的情况
            request.GetRouteData().Values.TryGetValue("MS_SubRoutes", out var routes);

            return (routes as System.Web.Http.Routing.IHttpRouteData[])?.FirstOrDefault()?.Route?.RouteTemplate ?? "unknown";
        }

        #region Response Time

        /// <summary>
        /// 开始记录响应时间
        /// </summary>
        /// <param name="request"></param>
        /// <param name="routeTemplate"></param>
        private void StartRecordingResponseTime(HttpRequestMessage request)
        {
            var stopwatch = new Stopwatch();
            stopwatch.Start();

            request.Properties.Add(API_METRICS_RESPONSE_TIME_KEY, stopwatch);
        }

        /// <summary>
        /// 停止记录响应时间
        /// </summary>
        /// <param name="response"></param>
        private void EndRecordingResponseTime(string routeTemplate, HttpRequestMessage request, HttpResponseMessage response)
        {
            var stopwatch = response.RequestMessage.Properties[API_METRICS_RESPONSE_TIME_KEY] as Stopwatch;

            ApiMetrics.GetMetrics().Provider.Timer.Instance(new TimerOptions
            {
                Name = "Response Time",
                Tags = new MetricTags(
                    new string[] { "method", "route", "status" },
                    new string[] { request.Method.Method, routeTemplate, ((int)response.StatusCode).ToString() }
                    ),
                DurationUnit = TimeUnit.Milliseconds,
                RateUnit = TimeUnit.Milliseconds,
                MeasurementUnit = Unit.Requests
            }).Record(stopwatch.ElapsedMilliseconds, TimeUnit.Milliseconds);

            response.RequestMessage.Properties.Remove(API_METRICS_RESPONSE_TIME_KEY);
        }

        #endregion

    }

MetricsHandler 的原理是：

请求进入后，首先触发 StartRecordingResponseTime() 方法，该方法创建了一个 Stopwatch 并开始计时，同时将 Stopwatch 储存在当前请求的缓存中
等待 await base.SendAsync() 完成，这会执行其它的 Handler、Filter 以及 Action 中的内容，这里执行完成意味着所有的操作都已经完成，并且响应体也已经生成
触发 EndRecordingResponseTime() 停止计时，并将记录的时间直接储存到 App Metrics 的 Timer 类型的 Response Time 指标中

需要注意的是，GetRouteTemplate() 方法通过 MS_SubRoutes 获取路由的方式仅适用于使用特性路由的方式，根据需要可以使用不同的获取路由的方式。

为了使 MetricsHandler 能正常工作，首先修改默认生成的 ValuesController，将其修改为使用特性路由的方式注册路由：

    [RoutePrefix("api/values")]
    public class ValuesController : ApiController
    {
        // GET api/values
        [HttpGet, Route("")]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet, Route("{id:int}")]
        public string Get([FromUri]int id)
        {
            return "value" + id;
        }

        // POST api/values
        [HttpPost, Route("")]
        public void Post([FromBody]string value)
        {
        }

        // PUT api/values/5
        [HttpPut, Route("{id:int}")]
        public void Put([FromUri]int id, [FromBody]string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete, Route("{id:int}")]
        public void Delete([FromUri]int id)
        {
        }
    }

接着修改 WebApiConfig 的 Register() ，将 config.Routes.MapHttpRoute() 路由模板注释掉，然后注册 MetricsHandler。现在 Register() 看起来类似这样：

    public static void Register(HttpConfiguration config)
    {
        config.MapHttpAttributeRoutes();

        // 注释掉这部分代码
        //config.Routes.MapHttpRoute(
        //    name: "DefaultApi",
        //    routeTemplate: "api/{controller}/{id}",
        //    defaults: new { id = RouteParameter.Optional }
        //);

        // Metrics Handler
        config.MessageHandlers.Add(new MetricsHandler());
    }

完成后我们启动程序，先通过浏览器或者 Postman 随意访问几个接口，例如 localhost:端口/api/values ，之后再访问 /metrics，就能看到我们新增的 api_response_time 指标了：

# HELP api_response_time
# TYPE api_response_time summary
api_response_time_sum{method="GET",route="api/values",status="200",app="WebAPISample",server="BUNPC",env="Dev",my_custom_tag="MyCustomValue"} 0.158
api_response_time_count{method="GET",route="api/values",status="200",app="WebAPISample",server="BUNPC",env="Dev",my_custom_tag="MyCustomValue"} 1
api_response_time{method="GET",route="api/values",status="200",app="WebAPISample",server="BUNPC",env="Dev",my_custom_tag="MyCustomValue",quantile="0.5"} 0.158
api_response_time{method="GET",route="api/values",status="200",app="WebAPISample",server="BUNPC",env="Dev",my_custom_tag="MyCustomValue",quantile="0.75"} 0.158
api_response_time{method="GET",route="api/values",status="200",app="WebAPISample",server="BUNPC",env="Dev",my_custom_tag="MyCustomValue",quantile="0.95"} 0.158
api_response_time{method="GET",route="api/values",status="200",app="WebAPISample",server="BUNPC",env="Dev",my_custom_tag="MyCustomValue",quantile="0.99"} 0.158

虽然我们的例子是基于 .NET Framework 的，但其实对于 .NET Core 而言也是类似。App Metrics 的 API 是一致的， `MetricsHandler` 由 `Middleware` 实现即可，这里就不展开说了。

通过 Prometheus 分析

Prometheus 的配置参考上一篇文章，这里直接通过 PromQL 来查询，默认地址为 http://localhost:9090/ 打开 Graph 页面。

计算每个接口总请求数量，因为 api_response_time_count 中包含响应状态，同一个 method 和 route 有时可能返回 200，有时可能返回 400，所以我们需要根据 method 和 route 进行分组再求和：

sum by (method, route)(api_response_time_count)

还可以统计1分钟内的错误率，我们对“错误”的定义为所有非 2XX 的响应，所以非 2 开头的 status 都属于错误：

sum(rate(api_response_time_count{status!~'2.*'}[1m]))

请注意，一定要先 rate() 再 sum()，参考文章 Rate then sum, never sum then rate https://www.robustperception.io/rate-then-sum-never-sum-then-rate

统计每个接口 95% 情况下的响应时间

api_response_time{quantile='0.95'}

与 Grafana 图表结合的例子，可以参考本文 demo 的 https://github.com/huhubun/AppMetricsPrometheusSample

链接

App Metrics 官方网站 https://www.app-metrics.io/