Filtrar e pré-processar telemetria no SDK do Application Insights
Você pode escrever código para filtrar, modificar ou enriquecer seus dados telemétricos antes que eles sejam enviados do SDK. O processamento inclui dados que são enviados dos módulos de telemetria padrão, como a coleta de solicitação HTTP e a coleta de dependência.
A filtragem pode modificar ou descartar a telemetria antes que ela seja enviada do SDK pela implementação de
ITelemetryProcessor
. Por exemplo, você pode reduzir o volume de telemetria excluindo as solicitações de robôs. Ao contrário da amostragem, você tem controle total do que é enviado ou descartado, mas isso afeta todas as métricas com base nos logs agregados. Dependendo de como você descartar os itens, você também poderá perder a capacidade de navegar entre itens relacionados.Adicione ou modifique propriedades de qualquer telemetria enviada de seu aplicativo implementando um
ITelemetryInitializer
. Por exemplo, é possível adicionar valores calculados ou números de versão pelos quais os dados serão filtrados no portal.Amostragem reduz o volume de telemetria sem afetar as estatísticas. Ela mantém juntos os 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.
Observação
A API do SDK é usada para enviar eventos personalizados e métricas.
Pré-requisitos
Instale o SDK apropriado para o seu aplicativo: ASP.NET, ASP.NET Core, Não HTTP/trabalho para .NET/.NET Core ou JavaScript.
Filtragem
Esta técnica fornece um controle mais direto sobre o que é incluído ou excluído do fluxo de telemetria. A filtragem pode ser usada para evitar que itens de telemetria sejam enviados para o Application Insights. Você pode usar a filtragem com a amostragem ou separadamente.
Para filtrar a telemetria, crie um processador de telemetria e registre-o no TelemetryConfiguration
. Toda a telemetria passa pelo processador. Você pode optar por removê-lo do fluxo ou fornecê-lo ao próximo processador na cadeia. Estão incluídas a telemetria controlada por você mesmo e a telemetria dos módulos padrão, como o coletor de solicitações HTTP e o coletor de dependências. Por exemplo, é possível filtrar a telemetria sobre solicitações de robôs ou sobre 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 usar a amostragem.
Aplicativos .NET
Implementar
ITelemetryProcessor
.Os processadores de telemetria criam uma cadeia de processamento. Quando você cria uma instância de um processador de telemetria, recebe uma referência ao próximo processador na cadeia. Quando um ponto de dados de telemetria é transmitido para o método de processo, ele faz seu trabalho e chama (ou não) o próximo processador de telemetria da 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 seu processador.
Insira este snippet em ApplicationInsights.config:
<TelemetryProcessors> <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9"> <!-- Set public property --> <MyParamFromConfigFile>2-beta</MyParamFromConfigFile> </Add> </TelemetryProcessors>
Você pode transmitir valores de cadeia de caracteres do arquivo .config fornecendo propriedades nomeadas públicas em sua classe.
Aviso
Fique atento para que o nome do tipo e todos os nomes de propriedade no arquivo .config correspondam aos nomes de classe e de propriedade no código. Se o arquivo .config fizer referência a um tipo ou propriedade inexistente, o SDK poderá falhar silenciosamente quando enviar qualquer telemetria.
Como alternativa, é possível 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 depois desse ponto usam os seus processadores.
Filtros de exemplo
Solicitações sintéticas
Filtre os bots e os testes Web. Embora o Metrics Explorer ofereça a opção de filtrar origens sintéticas, ela reduz o tráfego e o tamanho da ingestão filtrando-as no próprio SDK.
public void Process(ITelemetry item)
{
if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
// Send everything else:
this.Next.Process(item);
}
Autenticação com falha
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 de dependência rápidas remotas
Caso queira diagnosticar apenas chamadas lentas, filtre as rápidas.
Observação
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 ao enviar automaticamente pings regulares para as dependências.
Aplicativos Java
Para saber mais sobre os processadores de telemetria e a implementação deles em Java, referencie a documentação dos processadores de telemetria em Java.
Aplicativos Web JavaScript
Você pode filtrar a telemetria dos aplicativos Web JavaScript usando ITelemetryInitializer.
Crie uma função de retorno de chamada do inicializador de telemetria. Essa função usa
ITelemetryItem
como parâmetro, que é o evento que está sendo processado. Um resultadofalse
nesse retorno de chamada faz com que o item de telemetria seja 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 a telemetria sobre solicitações HTTP. Por padrão, ele sinaliza como com falha qualquer solicitação com um código de resposta >= 400. Se você quiser tratar o código 400 como êxito, forneça um inicializador de telemetria que define a propriedade de êxito.
Se você fornecer um inicializador de telemetria, ele será chamado sempre que qualquer um dos métodos Track*() for chamado. Esse inicializador inclui métodos Track()
chamados pelos módulos de telemetria padrão. Por convenção, esses módulos não definem qualquer propriedade que já tenha sido definida por um inicializador. Os inicializadores de telemetria são chamados antes dos processadores de telemetria e, portanto, todos os enriquecimentos feitos pelos inicializadores ficam visíveis para os processadores.
Aplicativos .NET
Definir seu 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 seu inicializador
Em ApplicationInsights.config:
<ApplicationInsights> <TelemetryInitializers> <!-- Fully qualified type name, assembly name: --> <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/> ... </TelemetryInitializers> </ApplicationInsights>
Como alternativa, você pode criar uma instância do 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 do 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 Script de Carregador de SDK do JavaScript (Web):
<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, confira Modelo de dados de exportação do Application Insights.
Você pode adicionar quantos inicializadores desejar. Eles são chamados na ordem em que são adicionados.
Processadores de telemetria do Python OpenCensus
Os processadores de telemetria no Python OpenCensus são simplesmente funções de retorno de chamada que são chamadas para processar a telemetria antes de serem exportadas. A função de retorno de chamada deve aceitar um tipo de dados de envelope como seu parâmetro. Para filtrar a telemetria com base no que está sendo exportado, verifique se a função de retorno de chamada retorna False
. Você pode ver o esquema para tipos de dados do Azure Monitor nos envelopes no GitHub.
Observação
É possível modificar cloud_RoleName
alterando o atributo ai.cloud.role
no campo tags
.
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 gerar uma exceção, ele não afetará os processadores a seguir.
Exemplo de TelemetryInitializers
Adicionar uma propriedade personalizada
Este exemplo de inicializador adiciona uma propriedade personalizada a cada telemetria rastreada.
public void Initialize(ITelemetry item)
{
var itemProperties = item as ISupportProperties;
if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
{
itemProperties.Properties["customProp"] = "customValue";
}
}
Adicionar um nome da função de nuvem
Este exemplo de inicializador 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";
}
}
Controlar 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 o 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 os processadores de telemetria e inicializadores de telemetria?
- Há algumas sobreposições no que pode ser feito com eles. Ambos podem ser usados para adicionar ou modificar propriedades de telemetria, embora seja recomendável usar inicializadores para essa finalidade.
- Os inicializadores de telemetria são sempre 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á tenha sido definida.
- Os processadores de telemetria permitem que você substitua ou descarte 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 a chamada do primeiro processador de telemetria. Os processadores de telemetria anteriores é que decidem se o restante dos processadores será chamado ou não.
- Use inicializadores de telemetria para enriquecer a telemetria com mais propriedades ou substituir uma existente. Use um processador de telemetria para filtrar a telemetria.
Observação
O JavaScript tem apenas inicializadores de telemetria que podem filtrar eventos usando ITelemetryInitializer
Solucionar problemas de 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 seu diretório de saída e contém todas as alterações recentes.
Referência de Tipos de Dados de Telemetria do Azure Monitor
- SDK de Núcleo do ASP.NET
- SDK do ASP.NET
- SDK do Node.js
- SDK do Java (via configuração)
- SDK do Python
- SDK do JavaScript