Filtrar e pré-processar a telemetria no SDK do Application Insights
Você pode escrever código para filtrar, modificar ou enriquecer sua telemetria antes que ela seja enviada do SDK. O processamento inclui dados enviados dos módulos de telemetria padrão, como coleta de solicitação HTTP e coleta de dependência.
A filtragem pode modificar ou descartar a telemetria antes de ser enviada do SDK implementando
ITelemetryProcessoro . Por exemplo, você pode reduzir o volume de telemetria excluindo solicitações de robôs. Ao contrário da amostragem, você tem controle total sobre o que é enviado ou descartado, mas isso afeta qualquer métrica baseada em logs agregados. Dependendo de como você descarta itens, você também pode perder a capacidade de navegar entre itens relacionados.Adicione ou modifique propriedades a qualquer telemetria enviada do seu aplicativo implementando um
ITelemetryInitializerarquivo . Por exemplo, você pode adicionar valores calculados ou números de versão para filtrar os dados no portal.A amostragem reduz o volume de telemetria sem afetar suas estatísticas. Ele mantém juntos pontos de dados relacionados para que você possa navegar entre eles quando diagnosticar um problema. No portal, as contagens totais são multiplicadas para compensar a amostragem.
Nota
A API do SDK é usada para enviar eventos e métricas personalizados.
Pré-requisitos
Instale o SDK apropriado para seu aplicativo: ASP.NET, ASP.NET Core, Non-HTTP/Worker for .NET/.NET Core ou JavaScript.
Filtragem
Essa técnica oferece controle direto sobre o que está incluído ou excluído do fluxo de telemetria. A filtragem pode ser usada para impedir que itens de telemetria sejam enviados para o Application Insights. Você pode usar a filtragem com amostragem ou separadamente.
Para filtrar a telemetria, escreva um processador de telemetria e registre-o com TelemetryConfigurationo . Toda a telemetria passa pelo seu processador. Você pode optar por soltá-lo do fluxo ou entregá-lo ao próximo processador na cadeia. A telemetria dos módulos padrão, como o coletor de solicitação HTTP e o coletor de dependência, e a telemetria que você mesmo rastreou estão incluídas. Por exemplo, você pode filtrar a telemetria sobre solicitações de robôs ou chamadas de dependência bem-sucedidas.
Aviso
Filtrar a telemetria enviada do SDK usando processadores pode distorcer as estatísticas que você vê no portal e dificultar o acompanhamento de itens relacionados.
Em vez disso, considere o uso de amostragem.
Aplicações .NET
Implementar
ITelemetryProcessor.Os processadores de telemetria constroem uma cadeia de processamento. Quando você instancia um processador de telemetria, recebe uma referência ao próximo processador da cadeia. Quando um ponto de dados de telemetria é passado para o método de processo, ele faz seu trabalho e, em seguida, chama (ou não chama) o próximo processador de telemetria na cadeia.
using Microsoft.ApplicationInsights.Channel; using Microsoft.ApplicationInsights.Extensibility; using Microsoft.ApplicationInsights.DataContracts; 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; } }Adicione o processador.
Insira este trecho em ApplicationInsights.config:
<TelemetryProcessors> <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9"> <!-- Set public property --> <MyParamFromConfigFile>2-beta</MyParamFromConfigFile> </Add> </TelemetryProcessors>Você pode passar valores de cadeia de caracteres do arquivo .config fornecendo propriedades nomeadas públicas em sua classe.
Aviso
Tome cuidado para corresponder o nome do tipo e quaisquer nomes de propriedade no arquivo .config com os nomes de classe e propriedade no código. Se o arquivo .config fizer referência a um tipo ou propriedade inexistente, o SDK poderá silenciosamente falhar ao enviar qualquer telemetria.
Como alternativa, você pode inicializar o filtro no código. Em uma classe de inicialização adequada, por exemplo, AppStart em
Global.asax.cs, insira seu processador na cadeia: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();Os clientes de telemetria criados após este ponto usam seus processadores.
Exemplos de filtros
Pedidos sintéticos
Filtre bots e testes da web. Embora o Metrics Explorer ofereça a opção de filtrar fontes sintéticas, essa opção reduz o tráfego e o tamanho da ingestão filtrando-os no próprio SDK.
public void Process(ITelemetry item)
{
if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
// Send everything else:
this.Next.Process(item);
}
Falha na autenticação
Filtre as solicitações com uma resposta "401".
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);
}
Filtrar chamadas rápidas de dependência remota
Se você quiser diagnosticar apenas chamadas que são lentas, filtre as rápidas.
Nota
Essa filtragem distorcerá as estatísticas que você vê no portal.
public void Process(ITelemetry item)
{
var request = item as DependencyTelemetry;
if (request != null && request.Duration.TotalMilliseconds < 100)
{
return;
}
this.Next.Process(item);
}
Diagnosticar problemas de dependência
Este blog descreve um projeto para diagnosticar problemas de dependência enviando automaticamente pings regulares para dependências.
Aplicações Java
Para saber mais sobre processadores de telemetria e sua implementação em Java, consulte a documentação de processadores de telemetria Java.
Aplicações Web JavaScript
Você pode filtrar a telemetria de aplicativos Web JavaScript usando ITelemetryInitializer.
Crie uma função de retorno de chamada do inicializador de telemetria. A função de retorno de chamada toma
ITelemetryItemcomo parâmetro, que é o evento que está sendo processado. O retornofalsedesse retorno de chamada resulta no item de telemetria a ser filtrado.var filteringFunction = (envelope) => { if (envelope.data.someField === 'tobefilteredout') { return false; } return true; };Adicione o retorno de chamada do inicializador de telemetria:
appInsights.addTelemetryInitializer(filteringFunction);
Adicionar/modificar propriedades: ITelemetryInitializer
Use inicializadores de telemetria para enriquecer a telemetria com informações adicionais ou para substituir as propriedades de telemetria definidas pelos módulos de telemetria padrão.
Por exemplo, o Application Insights para um pacote da Web coleta telemetria sobre solicitações HTTP. Por padrão, ele sinaliza qualquer solicitação com um código >de resposta =400 como falha. Se, em vez disso, quiser tratar 400 como um sucesso, você pode fornecer um inicializador de telemetria que define a propriedade success.
Se você fornecer um inicializador de telemetria, ele será chamado sempre que qualquer um dos métodos Track*() for chamado. Este inicializador inclui Track() métodos chamados pelos módulos de telemetria padrão. Por convenção, esses módulos não definem nenhuma propriedade que já tenha sido definida por um inicializador. Os inicializadores de telemetria são chamados antes de chamar os processadores de telemetria, portanto, qualquer enriquecimento feito pelos inicializadores é visível para os processadores.
Aplicações .NET
Defina o inicializador
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 } } }Carregue o inicializador
Em ApplicationInsights.config:
<ApplicationInsights> <TelemetryInitializers> <!-- Fully qualified type name, assembly name: --> <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/> ... </TelemetryInitializers> </ApplicationInsights>Como alternativa, você pode instanciar o inicializador no código, por exemplo, em Global.aspx.cs:
protected void Application_Start() { // ... TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer()); }Veja mais deste exemplo.
Inicializadores de telemetria JavaScript
Insira um inicializador de telemetria JavaScript, se necessário. Para obter mais informações sobre os inicializadores de telemetria para o SDK JavaScript do Application Insights, consulte Inicializadores de telemetria.
Insira um inicializador de telemetria adicionando a função de retorno de chamada onInit na configuração do JavaScript (Web) SDK Loader Script:
<script type="text/javascript">
!(function (cfg){function e(){cfg.onInit&&cfg.onInit(n)}var x,w,D,t,E,n,C=window,O=document,b=C.location,q="script",I="ingestionendpoint",L="disableExceptionTracking",j="ai.device.";"instrumentationKey"[x="toLowerCase"](),w="crossOrigin",D="POST",t="appInsightsSDK",E=cfg.name||"appInsights",(cfg.name||C[t])&&(C[t]=E),n=C[E]||function(g){var f=!1,m=!1,h={initialize:!0,queue:[],sv:"8",version:2,config:g};function v(e,t){var n={},i="Browser";function a(e){e=""+e;return 1===e.length?"0"+e:e}return n[j+"id"]=i[x](),n[j+"type"]=i,n["ai.operation.name"]=b&&b.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(h.sv||h.version),{time:(i=new Date).getUTCFullYear()+"-"+a(1+i.getUTCMonth())+"-"+a(i.getUTCDate())+"T"+a(i.getUTCHours())+":"+a(i.getUTCMinutes())+":"+a(i.getUTCSeconds())+"."+(i.getUTCMilliseconds()/1e3).toFixed(3).slice(2,5)+"Z",iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}},ver:undefined,seq:"1",aiDataContract:undefined}}var n,i,t,a,y=-1,T=0,S=["js.monitor.azure.com","js.cdn.applicationinsights.io","js.cdn.monitor.azure.com","js0.cdn.applicationinsights.io","js0.cdn.monitor.azure.com","js2.cdn.applicationinsights.io","js2.cdn.monitor.azure.com","az416426.vo.msecnd.net"],o=g.url||cfg.src,r=function(){return s(o,null)};function s(d,t){if((n=navigator)&&(~(n=(n.userAgent||"").toLowerCase()).indexOf("msie")||~n.indexOf("trident/"))&&~d.indexOf("ai.3")&&(d=d.replace(/(\/)(ai\.3\.)([^\d]*)$/,function(e,t,n){return t+"ai.2"+n})),!1!==cfg.cr)for(var e=0;e<S.length;e++)if(0<d.indexOf(S[e])){y=e;break}var n,i=function(e){var a,t,n,i,o,r,s,c,u,l;h.queue=[],m||(0<=y&&T+1<S.length?(a=(y+T+1)%S.length,p(d.replace(/^(.*\/\/)([\w\.]*)(\/.*)$/,function(e,t,n,i){return t+S[a]+i})),T+=1):(f=m=!0,s=d,!0!==cfg.dle&&(c=(t=function(){var e,t={},n=g.connectionString;if(n)for(var i=n.split(";"),a=0;a<i.length;a++){var o=i[a].split("=");2===o.length&&(t[o[0][x]()]=o[1])}return t[I]||(e=(n=t.endpointsuffix)?t.location:null,t[I]="https://"+(e?e+".":"")+"dc."+(n||"services.visualstudio.com")),t}()).instrumentationkey||g.instrumentationKey||"",t=(t=(t=t[I])&&"/"===t.slice(-1)?t.slice(0,-1):t)?t+"/v2/track":g.endpointUrl,t=g.userOverrideEndpointUrl||t,(n=[]).push((i="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",o=s,u=t,(l=(r=v(c,"Exception")).data).baseType="ExceptionData",l.baseData.exceptions=[{typeName:"SDKLoadFailed",message:i.replace(/\./g,"-"),hasFullStack:!1,stack:i+"\nSnippet failed to load ["+o+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(b&&b.pathname||"_unknown_")+"\nEndpoint: "+u,parsedStack:[]}],r)),n.push((l=s,i=t,(u=(o=v(c,"Message")).data).baseType="MessageData",(r=u.baseData).message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+l+")").replace(/\"/g,"")+'"',r.properties={endpoint:i},o)),s=n,c=t,JSON&&((u=C.fetch)&&!cfg.useXhr?u(c,{method:D,body:JSON.stringify(s),mode:"cors"}):XMLHttpRequest&&((l=new XMLHttpRequest).open(D,c),l.setRequestHeader("Content-type","application/json"),l.send(JSON.stringify(s)))))))},a=function(e,t){m||setTimeout(function(){!t&&h.core||i()},500),f=!1},p=function(e){var n=O.createElement(q),e=(n.src=e,t&&(n.integrity=t),n.setAttribute("data-ai-name",E),cfg[w]);return!e&&""!==e||"undefined"==n[w]||(n[w]=e),n.onload=a,n.onerror=i,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||a(0,t)},cfg.ld&&cfg.ld<0?O.getElementsByTagName("head")[0].appendChild(n):setTimeout(function(){O.getElementsByTagName(q)[0].parentNode.appendChild(n)},cfg.ld||0),n};p(d)}cfg.sri&&(n=o.match(/^((http[s]?:\/\/.*\/)\w+(\.\d+){1,5})\.(([\w]+\.){0,2}js)$/))&&6===n.length?(d="".concat(n[1],".integrity.json"),i="@".concat(n[4]),l=window.fetch,t=function(e){if(!e.ext||!e.ext[i]||!e.ext[i].file)throw Error("Error Loading JSON response");var t=e.ext[i].integrity||null;s(o=n[2]+e.ext[i].file,t)},l&&!cfg.useXhr?l(d,{method:"GET",mode:"cors"}).then(function(e){return e.json()["catch"](function(){return{}})}).then(t)["catch"](r):XMLHttpRequest&&((a=new XMLHttpRequest).open("GET",d),a.onreadystatechange=function(){if(a.readyState===XMLHttpRequest.DONE)if(200===a.status)try{t(JSON.parse(a.responseText))}catch(e){r()}else r()},a.send())):o&&r();try{h.cookie=O.cookie}catch(k){}function e(e){for(;e.length;)!function(t){h[t]=function(){var e=arguments;f||h.queue.push(function(){h[t].apply(h,e)})}}(e.pop())}var c,u,l="track",d="TrackPage",p="TrackEvent",l=(e([l+"Event",l+"PageView",l+"Exception",l+"Trace",l+"DependencyData",l+"Metric",l+"PageViewPerformance","start"+d,"stop"+d,"start"+p,"stop"+p,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),h.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4},(g.extensionConfig||{}).ApplicationInsightsAnalytics||{});return!0!==g[L]&&!0!==l[L]&&(e(["_"+(c="onerror")]),u=C[c],C[c]=function(e,t,n,i,a){var o=u&&u(e,t,n,i,a);return!0!==o&&h["_"+c]({message:e,url:t,lineNumber:n,columnNumber:i,error:a,evt:C.event}),o},g.autoExceptionInstrumented=!0),h}(cfg.cfg),(C[E]=n).queue&&0===n.queue.length?(n.queue.push(e),n.trackPageView({})):e();})({
src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js",
crossOrigin: "anonymous", // When supplied this will add the provided value as the cross origin attribute on the script tag
onInit: function (sdk) {
sdk.addTelemetryInitializer(function (envelope) {
envelope.data = envelope.data || {};
envelope.data.someField = 'This item passed through my telemetry initializer';
});
}, // Once the application insights instance has loaded and initialized this method will be called
// sri: false, // Custom optional value to specify whether fetching the snippet from integrity file and do integrity check
cfg: { // Application Insights Configuration
connectionString: "YOUR_CONNECTION_STRING"
}});
</script>
Para obter um resumo das propriedades não personalizadas disponíveis no item de telemetria, consulte Modelo de dados de exportação do Application Insights.
Você pode adicionar quantos inicializadores quiser. Eles são chamados na ordem em que são adicionados.
Processadores de telemetria OpenCensus Python
Os processadores de telemetria no OpenCensus Python são simplesmente funções de retorno de chamada chamadas para processar telemetria antes de serem exportadas. A função de retorno de chamada deve aceitar um tipo de dados de envelope como parâmetro. Para filtrar a telemetria de ser exportada, certifique-se de que a função de retorno de chamada retorna False. Você pode ver o esquema para os tipos de dados do Azure Monitor nos envelopes no GitHub.
Nota
Você pode modificar cloud_RoleName alterando o ai.cloud.role tags atributo no campo.
def callback_function(envelope):
envelope.tags['ai.cloud.role'] = 'new_role_name'
# Example for log exporter
import logging
from opencensus.ext.azure.log_exporter import AzureLogHandler
logger = logging.getLogger(__name__)
# Callback function to append '_hello' to each log message telemetry
def callback_function(envelope):
envelope.data.baseData.message += '_hello'
return True
handler = AzureLogHandler(connection_string='InstrumentationKey=<your-instrumentation_key-here>')
handler.add_telemetry_processor(callback_function)
logger.addHandler(handler)
logger.warning('Hello, World!')
# Example for trace exporter
import requests
from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace import config_integration
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer
config_integration.trace_integrations(['requests'])
# Callback function to add os_type: linux to span properties
def callback_function(envelope):
envelope.data.baseData.properties['os_type'] = 'linux'
return True
exporter = AzureExporter(
connection_string='InstrumentationKey=<your-instrumentation-key-here>'
)
exporter.add_telemetry_processor(callback_function)
tracer = Tracer(exporter=exporter, sampler=ProbabilitySampler(1.0))
with tracer.span(name='parent'):
response = requests.get(url='https://www.wikipedia.org/wiki/Rabbit')
# Example for metrics exporter
import time
from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module
from opencensus.stats import stats as stats_module
from opencensus.stats import view as view_module
from opencensus.tags import tag_map as tag_map_module
stats = stats_module.stats
view_manager = stats.view_manager
stats_recorder = stats.stats_recorder
CARROTS_MEASURE = measure_module.MeasureInt("carrots",
"number of carrots",
"carrots")
CARROTS_VIEW = view_module.View("carrots_view",
"number of carrots",
[],
CARROTS_MEASURE,
aggregation_module.CountAggregation())
# Callback function to only export the metric if value is greater than 0
def callback_function(envelope):
return envelope.data.baseData.metrics[0].value > 0
def main():
# Enable metrics
# Set the interval in seconds in which you want to send metrics
exporter = metrics_exporter.new_metrics_exporter(connection_string='InstrumentationKey=<your-instrumentation-key-here>')
exporter.add_telemetry_processor(callback_function)
view_manager.register_exporter(exporter)
view_manager.register_view(CARROTS_VIEW)
mmap = stats_recorder.new_measurement_map()
tmap = tag_map_module.TagMap()
mmap.measure_int_put(CARROTS_MEASURE, 1000)
mmap.record(tmap)
# Default export interval is every 15.0s
# Your application should run for at least this amount
# of time so the exporter will meet this interval
# Sleep can fulfill this
time.sleep(60)
print("Done recording metrics")
if __name__ == "__main__":
main()
Você pode adicionar quantos processadores quiser. Eles são chamados na ordem em que são adicionados. Se um processador lançar uma exceção, isso não afetará os processadores a seguir.
Exemplo TelemetryInitializers
Adicionar uma propriedade personalizada
O inicializador de exemplo a seguir adiciona uma propriedade personalizada a cada telemetria controlada.
public void Initialize(ITelemetry item)
{
var itemProperties = item as ISupportProperties;
if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
{
itemProperties.Properties["customProp"] = "customValue";
}
}
Adicionar um nome de função na nuvem
O inicializador de exemplo a seguir define o nome da função de nuvem para cada telemetria rastreada.
public void Initialize(ITelemetry telemetry)
{
if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
{
telemetry.Context.Cloud.RoleName = "MyCloudRoleName";
}
}
Controle o endereço IP do cliente usado para mapeamentos de geolocalização
O inicializador de exemplo a seguir define o IP do cliente, que é usado para mapeamento de geolocalização, em vez do endereço IP do soquete do cliente, durante a ingestão de telemetria.
public void Initialize(ITelemetry telemetry)
{
var request = telemetry as RequestTelemetry;
if (request == null) return true;
request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;
return true;
}
ITelemetryProcessor e ITelemetryInitializer
Qual é a diferença entre processadores de telemetria e inicializadores de telemetria?
- Existem algumas sobreposições no que você pode fazer com eles. Ambos podem ser usados para adicionar ou modificar propriedades de telemetria, embora recomendemos que você use inicializadores para essa finalidade.
- Os inicializadores de telemetria sempre são executados antes dos processadores de telemetria.
- Os inicializadores de telemetria podem ser chamados mais de uma vez. Por convenção, eles não definem nenhuma propriedade que já estava definida.
- Os processadores de telemetria permitem substituir ou descartar completamente um item de telemetria.
- Todos os inicializadores de telemetria registrados são chamados para cada item de telemetria. Para processadores de telemetria, o SDK garante chamar o primeiro processador de telemetria. Se o resto dos processadores são chamados ou não é decidido pelos processadores de telemetria anteriores.
- Use inicializadores de telemetria para enriquecer a telemetria com mais propriedades ou substituir uma existente. Use um processador de telemetria para filtrar a telemetria.
Nota
JavaScript só tem inicializadores de telemetria que podem filtrar eventos usando ITelemetryInitializer
Solucionar problemas do ApplicationInsights.config
- Confirme se o nome do tipo totalmente qualificado e o nome do assembly estão corretos.
- Confirme se o arquivo applicationinsights.config está no diretório de saída e contém as alterações recentes.