开发专栏
监控系统简介(二):使用 App Metrics 在 ASP.NET Web API 中记录指标
2020-02-05 18:06 ( 1 年前 )
1207
快速入门 Prometheus ASP.NET Web API

通过 App Metrics 类库为 ASP.NET Web API 程序记录请求次数、响应耗时、错误率等指标,并提供给 Prometheus 和 Grafana 使用。

回顾

《监控系统简介:使用 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 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;
    }
}
  1. DefaultContextLabel 的值会成为指标的前缀,这里设置成 API,则默认所有指标都为 api_ 开头
  2. AddAppTag() 会为所有指标添加一个名为 app 的 tag,内容为当前程序的名称
  3. AddServerTag() 会为所有指标添加一个名为 server 的 tag,内容是运行程序的机器名称
  4. AddEnvTag() 会为所有指标添加一个名为 env 的 tag,用于区分运行程序的环境
  5. 也可以通过 GlobalTags 属性,来添加自定义的 tag

因为没有依赖注入容器,还需要在 Global.asaxApplication_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》
  • Counter 计数器
  • Gauge gauge
  • Histogram 直方图
  • Meter 一个可增减的计数器,一般用于统计次数和速率
  • Timer 计时器,根据统计的时间,自动进行分组

可以看到,ApdexMeterTimer 是 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

通过 MeasureProvider 属性都可以访问到所有的指标类型,仔细观察可以发现, 通过 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_sumXXX_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 的原理是:

  1. 请求进入后,首先触发 StartRecordingResponseTime() 方法,该方法创建了一个 Stopwatch 并开始计时,同时将 Stopwatch 储存在当前请求的缓存中
  2. 等待 await base.SendAsync() 完成,这会执行其它的 Handler、Filter 以及 Action 中的内容,这里执行完成意味着所有的操作都已经完成,并且响应体也已经生成
  3. 触发 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)
        {
        }
    }

接着修改 WebApiConfigRegister() ,将 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 是一致的, MetricsHandlerMiddleware 实现即可,这里就不展开说了。

通过 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

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

api_response_time{quantile='0.95'}

与 Grafana 图表结合的例子,可以参考本文 demo 的 huhubun/AppMetricsPrometheusSample

Grafana sample dashboard

许可协议

知识共享许可协议:署名-非商业性使用-禁止演绎
监控系统简介(二):使用 App Metrics 在 ASP.NET Web API 中记录指标 huhubun 采用 知识共享 署名-非商业性使用-禁止演绎 4.0 国际 许可协议 进行许可。
基于 https://bun.plus/posts/introduction-to-monitoring-use-app-metrics-in-asp-net-application 上的作品创作。