在 Java Web 应用中筛选遥测Filter telemetry in your Java web app

可通过筛选器选择 Java Web 应用发送到 Application Insights 的遥测。Filters provide a way to select the telemetry that your Java web app sends to Application Insights. 可使用现成的筛选器,也可编写自己的自定义筛选器。There are some out-of-the-box filters that you can use, and you can also write your own custom filters.

现成的筛选器包括:The out-of-the-box filters include:

  • 跟踪严重性级别Trace severity level
  • 特定的 URL、关键字或响应代码Specific URLs, keywords or response codes
  • 快速响应,即快速向应用响应的遥测发出请求Fast responses - that is, requests to which your app responded to quickly
  • 特定事件名称Specific event names

备注

筛选器会使应用的指标产生偏差。Filters skew the metrics of your app. 例如,为了诊断缓慢响应,你可能会决定设置一个排除快速响应时间的筛选器。For example, you might decide that, in order to diagnose slow responses, you will set a filter to discard fast response times. 但必须注意,Application Insights 报告的平均响应时间会慢于实际速度,且请求数会小于实际数目。But you must be aware that the average response times reported by Application Insights will then be slower than the true speed, and the count of requests will be smaller than the real count. 如果这是一个问题,请改用采样If this is a concern, use Sampling instead.

设置筛选器Setting filters

在 ApplicationInsights.xml 中,添加 TelemetryProcessors 部分,如此例所示:In ApplicationInsights.xml, add a TelemetryProcessors section like this example:


    <ApplicationInsights>
      <TelemetryProcessors>

        <BuiltInProcessors>
           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>

           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="100"/>
                  <Add name="NotNeededResponseCodes" value="200-400"/>
           </Processor>

           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="100"/>
                  <Add name="NotNeededNames" value="home,index"/>
                  <Add name="NotNeededUrls" value=".jpg,.css"/>
           </Processor>

           <Processor type="TelemetryEventFilter">
                  <!-- Names of events we don't want to see -->
                  <Add name="NotNeededNames" value="Start,Stop,Pause"/>
           </Processor>

           <!-- Exclude telemetry from availability tests and bots -->
           <Processor type="SyntheticSourceFilter">
                <!-- Optional: specify which synthetic sources,
                     comma-separated
                     - default is all synthetics -->
                <Add name="NotNeededSources" value="Application Insights Availability Monitoring,BingPreview"
           </Processor>

        </BuiltInProcessors>

        <CustomProcessors>
          <Processor type="com.fabrikam.MyFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>

      </TelemetryProcessors>
    </ApplicationInsights>

检查整套内置处理器Inspect the full set of built-in processors.

内置筛选器Built-in filters

指标遥测筛选器Metric Telemetry filter


           <Processor type="MetricTelemetryFilter">
                  <Add name="NotNeeded" value="metric1,metric2"/>
           </Processor>
  • NotNeeded - 用逗号分隔的自定义指标名称列表。NotNeeded - Comma-separated list of custom metric names.

页面视图遥测筛选器Page View Telemetry filter


           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="500"/>
                  <Add name="NotNeededNames" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>
  • DurationThresholdInMS - 持续时间,表示加载该页所花的时间。DurationThresholdInMS - Duration refers to the time taken to load the page. 如果设置了此筛选器,那么页面加载时间快于此时间时就不会报告。If this is set, pages that loaded faster than this time are not reported.
  • NotNeededNames - 用逗号分隔的页名称列表。NotNeededNames - Comma-separated list of page names.
  • NotNeededUrls - 用逗号分隔的 URL 分段列表。NotNeededUrls - Comma-separated list of URL fragments. 例如,"home" 可筛选出 URL 中包含“home”的所有页面。For example, "home" filters out all pages that have "home" in the URL.

请求遥测筛选器Request Telemetry Filter


           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="500"/>
                  <Add name="NotNeededResponseCodes" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>

综合源筛选器Synthetic Source filter

筛选出 SyntheticSource 属性中具有值的所有遥测。Filters out all telemetry that have values in the SyntheticSource property. 其中包括来自动程序、蜘蛛程序和可用性测试的请求。These include requests from bots, spiders and availability tests.

筛选出针对所有综合请求的遥测:Filter out telemetry for all synthetic requests:


           <Processor type="SyntheticSourceFilter" />

筛选出针对特定综合源的遥测:Filter out telemetry for specific synthetic sources:


           <Processor type="SyntheticSourceFilter" >
                  <Add name="NotNeeded" value="source1,source2"/>
           </Processor>
  • NotNeeded - 用逗号分隔的综合源名称列表。NotNeeded - Comma-separated list of synthetic source names.

遥测事件筛选器Telemetry Event filter

筛选自定义事件(使用 TrackEvent() 记录)。Filters custom events (logged using TrackEvent()).


           <Processor type="TelemetryEventFilter" >
                  <Add name="NotNeededNames" value="event1, event2"/>
           </Processor>
  • NotNeededNames - 用逗号分隔的事件名称列表。NotNeededNames - Comma-separated list of event names.

跟踪遥测筛选器Trace Telemetry filter

筛选日志跟踪(使用 TrackTrace()记录框架收集器记录)。Filters log traces (logged using TrackTrace() or a logging framework collector).


           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>
  • FromSeverityLevel 有效值是:FromSeverityLevel valid values are:
    • OFF - 筛选出所有跟踪OFF - Filter out ALL traces
    • TRACE -不筛选。TRACE - No filtering. 等效于 Trace 级别equals to Trace level
    • INFO - 筛选出 TRACE 级别INFO - Filter out TRACE level
    • WARN - 筛选出 TRACE 和 INFOWARN - Filter out TRACE and INFO
    • ERROR - 筛选出 WARN、INFO、TRACEERROR - Filter out WARN, INFO, TRACE
    • CRITICAL - 筛选出除 CRITICAL 外的所有值CRITICAL - filter out all but CRITICAL

自定义筛选器Custom filters

1.编写筛选器代码1. Code your filter

在代码中创建实现 TelemetryProcessor 的类:In your code, create a class that implements TelemetryProcessor:


    package com.fabrikam.MyFilter;
    import com.microsoft.applicationinsights.extensibility.TelemetryProcessor;
    import com.microsoft.applicationinsights.telemetry.Telemetry;

    public class SuccessFilter implements TelemetryProcessor {

       /* Any parameters that are required to support the filter.*/
       private final String successful;

       /* Initializers for the parameters, named "setParameterName" */
       public void setNotNeeded(String successful)
       {
          this.successful = successful;
       }

       /* This method is called for each item of telemetry to be sent.
          Return false to discard it.
          Return true to allow other processors to inspect it. */
       @Override
       public boolean process(Telemetry telemetry) {
        if (telemetry == null) { return true; }
        if (telemetry instanceof RequestTelemetry)
        {
            RequestTelemetry requestTelemetry = (RequestTelemetry)telemetry;
            return request.getSuccess() == successful;
        }
        return true;
       }
    }

2.在配置文件中调用筛选器2. Invoke your filter in the configuration file

在 ApplicationInsights.xml 中:In ApplicationInsights.xml:



    <ApplicationInsights>
      <TelemetryProcessors>
        <CustomProcessors>
          <Processor type="com.fabrikam.SuccessFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>
      </TelemetryProcessors>
    </ApplicationInsights>

3.调用筛选器 (Java Spring)3. Invoke your filter (Java Spring)

对于基于 Spring 框架的应用程序,自定义遥测处理器必须在主应用程序类中注册为 bean。For applications based on the Spring framework, custom telemetry processors must be registered in your main application class as a bean. 然后,它们将在应用程序启动时自动连接。They will then be autowired when the application starts.

@Bean
public TelemetryProcessor successFilter() {
      return new SuccessFilter();
}

你将需要在 application.properties 中创建自己的筛选器参数,并利用 Spring Boot 的外部化配置框架将这些参数传递到自定义筛选器。You will need to create your own filter parameters in application.properties and leverage Spring Boot's externalized configuration framework to pass those parameters into your custom filter.

故障排除Troubleshooting

我的筛选器不能正常工作 。My filter isn't working.

  • 请检查提供的参数值是否有效。Check that you have provided valid parameter values. 例如,持续时间应为整数。For example, durations should be integers. 无效值将导致筛选器被忽略。Invalid values will cause the filter to be ignored. 如果自定义筛选器从构造函数或 set 方法中引发异常,它会被忽略。If your custom filter throws an exception from a constructor or set method, it will be ignored.

后续步骤Next steps

  • 采样 - 请考虑将采样作为替代方法,该方法不会使指标出现偏差。Sampling - Consider sampling as an alternative that does not skew your metrics.