Filtro y preprocesamiento de la telemetría en el SDK de Application Insights
Puedes escribir código para filtrar, modificar o enriquecer tu telemetría antes de que se envíe desde el SDK. El procesamiento incluye los datos enviados desde los módulos de telemetría estándar, como la recopilación de solicitudes HTTP y de dependencias.
El filtrado puede modificar o descartar la telemetría antes de que se envíe desde el SDK, mediante la implementación de
ITelemetryProcessor. Por ejemplo, para reducir el volumen de la telemetría puede excluir las solicitudes de robots. A diferencia del muestreo, tienes el control total sobre lo que se envía o descarta, pero afecta cualquier métrica basada en registros agregados. Dependiendo de cómo descartes elementos, también podrías perder la capacidad de navegar entre elementos relacionados.Agrega o modifica propiedades a cualquier telemetría enviada desde tu aplicación mediante la implementación de un archivo
ITelemetryInitializer. Por ejemplo, puede agregar valores calculados o números de versión para filtrar los datos en el portal.muestreo reduce el volumen de la telemetría sin que ello influya en las estadísticas. Mantiene juntos los puntos de datos relacionados para que pueda navegar entre ellos a la hora de diagnosticar un problema. En el portal, se multiplican los recuentos totales para compensar el muestreo.
Nota:
API del SDK se usa para enviar métricas y eventos personalizados.
Requisitos previos
Instale el SDK adecuado para su aplicación: ASP.NET, ASP.NET Core, No HTTP/Trabajo para .NET/.NET Core o JavaScript.
Filtros
Esta técnica le ofrece un control directo sobre lo que se incluirá en la transmisión de telemetría o lo que se excluirá de ella. El filtrado se puede usar para impedir el envío de elementos de telemetría a Application Insights. Puede utilizar el filtrado junto con el muestreo o por separado.
Para filtrar la telemetría, escriba un procesador de telemetría y regístrelo con TelemetryConfiguration. Toda la telemetría pasa por el procesador. Puede optar por no incluirla en la transmisión o por proporcionársela al procesador siguiente en la cadena. Esto incluye la telemetría de los módulos estándar, como el recopilador de solicitudes HTTP y el recopilador de dependencia, así como la telemetría de la que haya realizado un seguimiento. Por ejemplo, puede filtrar para dejar fuera la telemetría acerca de las solicitudes de robots o las llamadas de dependencia correctas.
Advertencia
El filtrado de la telemetría enviada desde el SDK usando procesadores puede sesgar las estadísticas que se ven en el portal y dificultar el seguimiento de elementos relacionados.
En su lugar, puede efectuar un muestreo.
Aplicaciones .NET
Implemente
ITelemetryProcessor.Los procesadores de telemetría forman una cadena de procesamiento. Al crear instancias de un procesador de telemetría, se le proporciona una referencia al procesador siguiente en la cadena. Cuando un punto de datos de telemetría se pasa al método de proceso, realiza su trabajo y, a continuación, llama (o no) al procesador de telemetría siguiente en la cadena.
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; } }Agregue el procesador.
Inserte este fragmento en ApplicationInsights.config:
<TelemetryProcessors> <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9"> <!-- Set public property --> <MyParamFromConfigFile>2-beta</MyParamFromConfigFile> </Add> </TelemetryProcessors>Puede pasar valores de cadena desde el archivo .config proporcionando propiedades con nombre públicas en la clase.
Advertencia
Tenga cuidado para que el nombre de tipo y los nombres de propiedad del archivo .config coincidan con los nombres de clase y propiedad del código. Si el archivo .config hace referencia a un tipo o propiedad que no existe, el SDK puede producir un error de forma silenciosa al enviar cualquier telemetría.
Alternativamente, se puede inicializar el filtro en el código. En una clase de inicialización adecuada (por ejemplo, AppStart de
Global.asax.cs), inserte el procesador en la cadena: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();Los clientes de telemetría creados a partir de este punto usan sus procesadores.
Filtros de ejemplo
Solicitudes sintéticas
Filtrar las pruebas web y robots. Aunque el Explorador de métricas proporciona la opción para filtrar y dejar fuera los orígenes sintéticos, esta opción reduce el tráfico y el tamaño de ingesta filtrándolos en el SDK.
public void Process(ITelemetry item)
{
if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
// Send everything else:
this.Next.Process(item);
}
Error de autenticación
Filtrar solicitudes con una respuesta "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 las llamadas de dependencia rápida y remota
Si quiere diagnosticar solo las llamadas que son lentas, descarte las rápidas.
Nota
Este filtrado sesgará las estadísticas que se ven en el portal.
public void Process(ITelemetry item)
{
var request = item as DependencyTelemetry;
if (request != null && request.Duration.TotalMilliseconds < 100)
{
return;
}
this.Next.Process(item);
}
Diagnóstico de problemas de dependencia
este blog se describe un proyecto para diagnosticar problemas de dependencia enviando automáticamente pings regulares a las dependencias.
Aplicaciones Java
Para más información sobre los procesadores de telemetría y su implementación en Java, consulte la documentación de los procesadores de telemetría de Java.
Aplicaciones web de JavaScript
Puede filtrar la telemetría desde aplicaciones web de JavaScript mediante ITelemetryInitializer.
Cree una función de devolución de llamada del inicializador de telemetría. La función de devolución de llamada toma
ITelemetryItemcomo parámetro, que es el evento que se está procesando. La devolución defalsedesde esta devolución de llamada da lugar a que se filtre el elemento de telemetría.var filteringFunction = (envelope) => { if (envelope.data.someField === 'tobefilteredout') { return false; } return true; };Agregue la devolución de llamada del inicializador de telemetría:
appInsights.addTelemetryInitializer(filteringFunction);
Agregar o modificar propiedades: ITelemetryInitializer
Use los inicializadores de telemetría para enriquecer la telemetría con información adicional o para invalidar las propiedades de telemetría establecidas por los módulos de telemetría estándar.
Por ejemplo, Application Insights para un paquete web recopila telemetría acerca de las solicitudes HTTP. De forma predeterminada, marca cualquier solicitud con un código de respuesta >=400 como error. Si en su lugar quiere tratar 400 como correcto, puede proporcionar un inicializador de telemetría que establezca la propiedad de éxito.
Si se proporciona un inicializador de telemetría, se llama cada vez que se llama a cualquiera de los métodos Track*(). Este inicializador incluye los métodos Track() que llaman los módulos de telemetría estándar. Por convención, estos módulos no establecen ninguna propiedad que ya haya sido establecida por un inicializador. Se llama a los inicializadores de telemetría antes de llamar a los procesadores de telemetría, por lo que los enriquecimientos realizados por inicializadores son visibles para los procesadores.
Aplicaciones .NET
Defina su 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 } } }Carga del inicializador
En ApplicationInsights.config:
<ApplicationInsights> <TelemetryInitializers> <!-- Fully qualified type name, assembly name: --> <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/> ... </TelemetryInitializers> </ApplicationInsights>Alternativamente, se pueden crear instancias del inicializador en el código, por ejemplo en Global.aspx.cs:
protected void Application_Start() { // ... TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer()); }Obtenga más información de este ejemplo.
Inicializadores de telemetría de JavaScript
Inserte un inicializador de telemetría de JavaScript, si es necesario. Para más información sobre los inicializadores de telemetría para el SDK de JavaScript de Application Insights, consulte Inicializadores de telemetría.
Inserte un inicializador de telemetría agregando la función de devolución de llamada onInit en la configuración del script del cargador del SDK de 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 obtener un resumen de las propiedades no personalizadas disponibles en el elemento de telemetría, consulte Modelo de exportación de datos de Application Insights.
Puede agregar tantos inicializadores como desee. Se llaman en el orden en que se agregan.
Procesadores de telemetría de Python para OpenCensus
Los procesadores de telemetría de Python para OpenCensus son simplemente funciones de devolución de llamada utilizadas para procesar la telemetría antes de que se exporten. La función de devolución de llamada debe aceptar un tipo de datos de sobre como parámetro. Para filtrar la telemetría para que no se exporte, asegúrese de que la función de devolución de llamada devuelva False. Puede ver el esquema de los tipos de datos de Azure Monitor en los sobres en GitHub.
Nota
cloud_RoleName se puede modificar cambiando el atributo ai.cloud.role del 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()
Puede agregar tantos procesadores como quiera. Se llaman en el orden en que se agregan. En el caso de que un procesador produzca una excepción, esta no afectará a los procesadores siguientes.
TelemetryInitializers de ejemplo
Adición de una propiedad personalizada
El siguiente inicializador de ejemplo agrega una propiedad personalizada a cada una de las telemetrías de las que se ha realizado un seguimiento.
public void Initialize(ITelemetry item)
{
var itemProperties = item as ISupportProperties;
if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
{
itemProperties.Properties["customProp"] = "customValue";
}
}
Adición de un nombre de rol en la nube
El siguiente inicializador de ejemplo establece el nombre de rol en la nube a cada una de las telemetrías de las que se ha realizado un seguimiento.
public void Initialize(ITelemetry telemetry)
{
if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
{
telemetry.Context.Cloud.RoleName = "MyCloudRoleName";
}
}
Control de la dirección IP del cliente usada para las asignaciones de geolocalización
El inicializador de ejemplo siguiente establece la dirección IP del cliente que se usa para la asignación de geolocalización, en lugar de la dirección IP del socket de cliente, durante la ingesta de telemetría.
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
¿Cuál es la diferencia entre los procesadores de telemetría y los inicializadores de telemetría?
- Hay algunas superposiciones en lo que puede hacer con ellos. Ambos se pueden usar para agregar o modificar las propiedades de la telemetría, aunque se recomienda usar inicializadores con esa finalidad.
- Los inicializadores de telemetría siempre se ejecutan antes que los procesadores de telemetría.
- Se puede llamar a los inicializadores de telemetría más de una vez. Por convención, no establecen ninguna propiedad que ya se haya establecido.
- Los procesadores de telemetría permiten reemplazar o descartar por completo un elemento de telemetría.
- Todos los inicializadores de telemetría registrados reciben llamadas para cada elemento de telemetría. En el caso de los procesadores de telemetría, el SDK garantiza la llamada al primer procesador de telemetría. Los procesadores de telemetría anteriores deciden si se llama o no al resto de los procesadores.
- Use los inicializadores de la telemetría para enriquecerla con más propiedades o invalidar una existente. Use un procesador de telemetría para filtrar la telemetría.
Nota
JavaScript solo tiene inicializadores de telemetría que pueden filtrar eventos mediante ITelemetryInitializer.
Solución de problemas de ApplicationInsights.config
- Compruebe que el nombre del tipo completo y el nombre del ensamblado sean correctos.
- Compruebe que el archivo applicationinsights.config esté en el directorio de salida y que contenga todos los cambios recientes.
Referencia de tipos de datos de telemetría de Azure Monitor
- SDK básico de ASP.NET
- SDK de ASP.NET
- SDK de Node.js
- SDK de Java (a través de la configuración)
- SDK de Python
- SDK de JavaScript