您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Application Insights SDK 中的筛选和预处理遥测 | Microsoft AzureFiltering and preprocessing telemetry in the Application Insights SDK

你可以编写和配置 Application Insights SDK 的插件,以自定义在将遥测发送到 Application Insights 服务之前如何对其进行充实和处理。You can write and configure plug-ins for the Application Insights SDK to customize how telemetry can be enriched and processed before it's sent to the Application Insights service.

  • 采样可在不影响统计信息的情况下减少遥测量。Sampling reduces the volume of telemetry without affecting your statistics. 它还保留相关数据点,以便可以在诊断问题时导航这些点。It keeps together related data points so that you can navigate between them when diagnosing a problem. 在门户中,总计相乘以补偿采样。In the portal, the total counts are multiplied to compensate for the sampling.
  • 通过遥测处理器进行筛选,可以在将遥测发送到服务器之前,筛选出 SDK 中的遥测数据。Filtering with Telemetry Processors lets you filter out telemetry in the SDK before it is sent to the server. 例如,可以通过排除机器人请求减少遥测量。For example, you could reduce the volume of telemetry by excluding requests from robots. 筛选是减少流量比采样更基本的方法。Filtering is a more basic approach to reducing traffic than sampling. 它允许更好地控制传输的内容,但你必须知道它会影响统计信息(例如,如果筛选出所有成功请求)。It allows you more control over what is transmitted, but you have to be aware that it affects your statistics - for example, if you filter out all successful requests.
  • 遥测初始值设定项添加或修改从应用发送的任何遥测的属性,包括来自标准模块的遥测。Telemetry Initializers add or modify properties to any telemetry sent from your app, including telemetry from the standard modules. 例如,可以添加计算得出的值;或在门户中筛选数据所依据的版本号。For example, you could add calculated values; or version numbers by which to filter the data in the portal.
  • SDK API 用于发送自定义事件和指标。The SDK API is used to send custom events and metrics.

开始之前:Before you start:

筛选:ITelemetryProcessorFiltering: ITelemetryProcessor

此方法可让你直接控制遥测流中包含或排除的内容。This technique gives you direct control over what is included or excluded from the telemetry stream. 筛选可用于删除从发送到 Application Insights 的遥测项。Filtering can be used to drop telemetry items from being sent to Application Insights. 可以将其与采样结合使用,也可以单独使用。You can use it in conjunction with Sampling, or separately.

若要筛选遥测数据,请编写遥测处理器,并将其注册到 TelemetryConfigurationTo filter telemetry, you write a telemetry processor and register it with the TelemetryConfiguration. 所有遥测数据都通过你的处理器,你可以选择将其从流中删除,或将其发送到链中的下一个处理器。All telemetry goes through your processor, and you can choose to drop it from the stream or give it to the next processor in the chain. 这包括来自标准模块的遥测数据,例如 HTTP 请求收集器、依赖关系收集器以及您自己跟踪的遥测。This includes telemetry from the standard modules such as the HTTP request collector and the dependency collector, and telemetry you have tracked yourself. 例如,可以筛选出有关机器人请求或成功依赖项调用的遥测。You can, for example, filter out telemetry about requests from robots, or successful dependency calls.

警告

使用处理器筛选从 SDK 发送的遥测会使门户中看到的统计信息出现偏差,并使它难以跟进相关项目。Filtering the telemetry sent from the SDK using processors can skew the statistics that you see in the portal, and make it difficult to follow related items.

此时,考虑使用采样Instead, consider using sampling.

创建遥测处理器 (C#)Create a telemetry processor (C#)

  1. 若要创建筛选器,请实现 ITelemetryProcessorTo create a filter, implement ITelemetryProcessor.

    请注意,遥测处理器构建一个处理链。Notice that Telemetry Processors construct a chain of processing. 实例化遥测处理器时,将为您提供对链中下一个处理器的引用。When you instantiate a telemetry processor, you are given a reference to the next processor in the chain. 将遥测数据点传递到处理方法时,它将执行其工作,然后调用(或不调用)链中的下一个遥测处理器。When a telemetry data point is passed to the Process method, it does its work and then calls (or not calls) the next Telemetry Processor in the chain.

    using Microsoft.ApplicationInsights.Channel;
    using Microsoft.ApplicationInsights.Extensibility;
    
    public class SuccessfulDependencyFilter : ITelemetryProcessor
    {
        private ITelemetryProcessor Next { get; set; }
    
        // next will point to the next TelemetryProcessor in the chain.
        public SuccessfulDependencyFilter(ITelemetryProcessor next)
        {
            this.Next = next;
        }
    
        public void Process(ITelemetry item)
        {
            // To filter out an item, return without calling the next processor.
            if (!OKtoSend(item)) { return; }
    
            this.Next.Process(item);
        }
    
        // Example: replace with your own criteria.
        private bool OKtoSend (ITelemetry item)
        {
            var dependency = item as DependencyTelemetry;
            if (dependency == null) return true;
    
            return dependency.Success != true;
        }
    }
    
  2. 添加处理器。Add your processor.

ASP.NET 应用在 Applicationinsights.config 中插入此代码片段:ASP.NET apps Insert this snippet in ApplicationInsights.config:

<TelemetryProcessors>
  <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
     <!-- Set public property -->
     <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
  </Add>
</TelemetryProcessors>

可通过在类中提供公共命名属性,传递 .config 文件中的字符串值。You can pass string values from the .config file by providing public named properties in your class.

警告

注意将 .config 文件中的类型名称和任何属性名称匹配到代码中的类和属性名称。Take care to match the type name and any property names in the .config file to the class and property names in the code. 如果 .config 文件引用不存在的类型或属性,该 SDK 在发送任何遥测时可能静默失败。If the .config file references a non-existent type or property, the SDK may silently fail to send any telemetry.

或者, 可以在代码中初始化筛选器。Alternatively, you can initialize the filter in code. 在合适的初始化类中(例如 AppStart)在 Global.asax.cs-将处理器插入链:In a suitable initialization class - for example AppStart in Global.asax.cs - insert your processor into the chain:

var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
builder.Use((next) => new SuccessfulDependencyFilter(next));

// If you have more processors:
builder.Use((next) => new AnotherProcessor(next));

builder.Build();

在此点后创建的 TelemetryClients 将使用处理器。TelemetryClients created after this point will use your processors.

ASP.NET Core/辅助角色服务应用ASP.NET Core/ Worker Service apps

备注

使用 ApplicationInsights.config 或使用 TelemetryConfiguration.Active 添加处理器对于 ASP.NET Core 应用程序无效,或者如果使用 WorkerService SDK,则无效。Adding processor using ApplicationInsights.config or using TelemetryConfiguration.Active is not valid for ASP.NET Core applications or if you are using Microsoft.ApplicationInsights.WorkerService SDK.

对于使用ASP.NET CoreWorkerService编写的应用,添加新的 TelemetryProcessor 是通过在 IServiceCollection 上使用 @no__t 3 扩展方法完成的,如下所示。For apps written using ASP.NET Core or WorkerService, adding a new TelemetryProcessor is done by using AddApplicationInsightsTelemetryProcessor extension method on IServiceCollection, as shown below. 此方法在 @no__t 1 类的 @no__t 0 方法中调用。This method is called in ConfigureServices method of your Startup.cs class.

    public void ConfigureServices(IServiceCollection services)
    {
        // ...
        services.AddApplicationInsightsTelemetry();
        services.AddApplicationInsightsTelemetryProcessor<SuccessfulDependencyFilter>();

        // If you have more processors:
        services.AddApplicationInsightsTelemetryProcessor<AnotherProcessor>();
    }

示例筛选器Example filters

综合请求Synthetic requests

筛选出机器人和 Web 测试。Filter out bots and web tests. 尽管指标资源管理器提供筛选合成源的选项,但此选项可通过在 SDK 本身对流量进行筛选来减少流量和引入大小。Although Metrics Explorer gives you the option to filter out synthetic sources, this option reduces traffic and ingestion size by filtering them at the SDK itself.

public void Process(ITelemetry item)
{
  if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}

  // Send everything else:
  this.Next.Process(item);
}

身份验证失败Failed authentication

筛选出带有“401”响应的请求。Filter out requests with a "401" response.

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}

筛选出快速远程依赖项调用Filter out fast remote dependency calls

如果只想诊断速度较慢的调用,则筛选出快速调用。If you only want to diagnose calls that are slow, filter out the fast ones.

备注

这会使门户上看到的统计信息出现偏差。This will skew the statistics you see on the portal.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

诊断依赖项问题Diagnose dependency issues

本博客介绍了通过自动将常规 Ping 发送到依赖项诊断依赖项问题的项目。This blog describes a project to diagnose dependency issues by automatically sending regular pings to dependencies.

添加属性:ITelemetryInitializerAdd properties: ITelemetryInitializer

使用遥测初始值设定项,通过其他信息和/或重写标准遥测模块设置的遥测属性,来充实遥测数据。Use telemetry initializers to enrich telemetry with additional information and/or to override telemetry properties set by the standard telemetry modules.

例如,Web 包的 Application Insights 收集有关 HTTP 请求的遥测数据。For example, the Application Insights for Web package collect telemetry about HTTP requests. 默认情况下,它标记为所有请求失败,并且响应代码 >= 400。By default, it flags as failed any request with a response code >= 400. 但是,如果希望将 400 视为成功,可以提供一个设置成功属性的遥测初始值设定项。But if you want to treat 400 as a success, you can provide a telemetry initializer that sets the Success property.

如果提供了遥测初始值设定项,只要调用任何 Track*() 方法,就会调用它。If you provide a telemetry initializer, it is called whenever any of the Track*() methods are called. 这包括标准遥测模块调用 @no__t 0 方法。This includes Track() methods called by the standard telemetry modules. 按照约定,这些模块不会设置已由初始值设定项设置的任何属性。By convention, these modules do not set any property that has already been set by an initializer. 在调用遥测处理器之前调用遥测初始值设定项。Telemetry initializers are called before calling telemetry processors. 因此,通过初始值设定项完成的任何根据对处理器都可见。So any enrichments done by initializers are visible to processors.

定义初始值设定项Define your initializer

C#C#

using System;
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

namespace MvcWebRole.Telemetry
{
  /*
   * Custom TelemetryInitializer that overrides the default SDK
   * behavior of treating response codes >= 400 as failed requests
   *
   */
  public class MyTelemetryInitializer : ITelemetryInitializer
  {
    public void Initialize(ITelemetry telemetry)
    {
        var requestTelemetry = telemetry as RequestTelemetry;
        // Is this a TrackRequest() ?
        if (requestTelemetry == null) return;
        int code;
        bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
        if (!parsed) return;
        if (code >= 400 && code < 500)
        {
            // If we set the Success property, the SDK won't change it:
            requestTelemetry.Success = true;

            // Allow us to filter these requests in the portal:
            requestTelemetry.Properties["Overridden400s"] = "true";
        }
        // else leave the SDK to set the Success property
    }
  }
}

ASP.NET 应用:加载初始值设定项ASP.NET apps: Load your initializer

在 ApplicationInsights.config 中:In ApplicationInsights.config:

<ApplicationInsights>
  <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
  </TelemetryInitializers>
</ApplicationInsights>

或者, 可以在代码中实例化初始值设定项,例如在 Global.aspx.cs 中:Alternatively, you can instantiate the initializer in code, for example in Global.aspx.cs:

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

查看此示例的详细信息。See more of this sample.

@no__t 0ASP.NET 核心/辅助角色服务应用:加载初始值设定项**ASP.NET Core/ Worker Service apps: Load your initializer

备注

使用 ApplicationInsights.config 或使用 TelemetryConfiguration.Active 添加初始值设定项对于 ASP.NET Core 应用程序无效,或者如果使用 WorkerService SDK,则无效。Adding initializer using ApplicationInsights.config or using TelemetryConfiguration.Active is not valid for ASP.NET Core applications or if you are using Microsoft.ApplicationInsights.WorkerService SDK.

对于使用ASP.NET CoreWorkerService编写的应用,通过将新的 @no__t 添加到依赖关系注入容器来添加新的,如下所示。For apps written using ASP.NET Core or WorkerService, adding a new TelemetryInitializer is done by adding it to the Dependency Injection container, as shown below. 这是在 Startup.ConfigureServices 方法中完成的。This is done in Startup.ConfigureServices method.

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}

Java 遥测初始值设定项Java telemetry initializers

Java SDK 文档Java SDK documentation

public interface TelemetryInitializer
{ /** Initializes properties of the specified object. * @param telemetry The {@link com.microsoft.applicationinsights.telemetry.Telemetry} to initialize. */

void initialize(Telemetry telemetry); }

然后在 applicationinsights.xml 文件中注册自定义初始值设定项。Then register the custom initializer in your applicationinsights.xml file.

<Add type="mypackage.MyConfigurableContextInitializer">
    <Param name="some_config_property" value="some_value" />
</Add>

JavaScript 遥测初始值设定项JavaScript telemetry initializers

JavaScriptJavaScript

在从门户获取的初始化代码后立即插入遥测初始值设定项:Insert a telemetry initializer immediately after the initialization code that you got from the portal:

<script type="text/javascript">
    // ... initialization code
    ...({
        instrumentationKey: "your instrumentation key"
    });
    window.appInsights = appInsights;


    // Adding telemetry initializer.
    // This is called whenever a new telemetry item
    // is created.

    appInsights.queue.push(function () {
        appInsights.context.addTelemetryInitializer(function (envelope) {
            var telemetryItem = envelope.data.baseData;

            // To check the telemetry items type - for example PageView:
            if (envelope.name == Microsoft.ApplicationInsights.Telemetry.PageView.envelopeType) {
                // this statement removes url from all page view documents
                telemetryItem.url = "URL CENSORED";
            }

            // To set custom properties:
            telemetryItem.properties = telemetryItem.properties || {};
            telemetryItem.properties["globalProperty"] = "boo";

            // To set custom metrics:
            telemetryItem.measurements = telemetryItem.measurements || {};
            telemetryItem.measurements["globalMetric"] = 100;
        });
    });

    // End of inserted code.

    appInsights.trackPageView();
</script>

有关 telemetryItem 上可用的非自定义属性摘要,请参阅Application Insights 导出数据模型For a summary of the non-custom properties available on the telemetryItem, see Application Insights Export Data Model.

您可以根据自己的需要添加任意多个初始值设定项,并按添加顺序调用它们。You can add as many initializers as you like, and they are called in the order they are added.

示例 TelemetryInitializersExample TelemetryInitializers

添加自定义属性Add custom property

下面的示例初始值设定项将自定义属性添加到每个跟踪的遥测。The following sample initializer adds a custom property to every tracked telemetry.

public void Initialize(ITelemetry item)
{
  var itemProperties = item as ISupportProperties;
  if(itemProperties != null && !itemProperties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

添加云角色名称Add cloud role name

下面的示例初始值设定项将云角色名称设置为每个跟踪的遥测。The following sample initializer sets cloud role name to every tracked telemetry.

public void Initialize(ITelemetry telemetry)
{
    if(string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
    {
        telemetry.Context.Cloud.RoleName = "MyCloudRoleName";
    }
}

ITelemetryProcessor 和 ITelemetryInitializerITelemetryProcessor and ITelemetryInitializer

遥测处理器和遥测初始值设定项之间的区别是什么?What's the difference between telemetry processors and telemetry initializers?

  • 您可以对其执行的操作有一些重叠之处:这两种方法可用于添加或修改遥测的属性,但建议为该目的使用初始值设定项。There are some overlaps in what you can do with them: both can be used to add or modify properties of telemetry, though it is recommended to use initializers for that purpose.
  • TelemetryInitializers 始终在 TelemetryProcessors 之前运行。TelemetryInitializers always run before TelemetryProcessors.
  • 可以多次调用 TelemetryInitializers。TelemetryInitializers may be called more than once. 按照约定,它们不会设置任何已设置的属性。By convention, they do not set any property that has already been set.
  • TelemetryProcessors 允许完全替换或丢弃遥测项。TelemetryProcessors allow you to completely replace or discard a telemetry item.
  • 确保为每个遥测项调用所有已注册的 TelemetryInitializers。All registered TelemetryInitializers are guaranteed to be called for every telemetry item. 对于遥测处理器,SDK 保证调用第一个遥测处理器。For Telemetry processors, SDK guarantees calling the very first telemetry processor. 不管是否调用了处理器的其余部分,都由前面的遥测处理器确定。Whether the rest of the processors are called or not, is decided by the preceding telemetry processors.
  • 使用 TelemetryInitializers 通过其他属性或覆盖现有的属性来充实遥测数据。Use TelemetryInitializers to enrich telemetry with additional properties, or override existing one. 使用 TelemetryProcessor 筛选出遥测数据。Use TelemetryProcessor to filter out telemetry.

ApplicationInsights.config 故障排除Troubleshooting ApplicationInsights.config

  • 确认完全限定的类型名称和程序集名称是正确的。Confirm that the fully qualified type name and assembly name are correct.
  • 确认 applicationinsights.config 文件在输出目录中并且包含所有最新更改。Confirm that the applicationinsights.config file is in your output directory and contains any recent changes.

参考文档Reference docs

SDK 代码SDK Code

后续步骤Next steps