Telemetria/Insights Design Reference

_{Keyworks: Application Insights Azure Telemetry Pulse}

Conceitos

Telemetria

Este termo tem sido usado recentemente para representar os dados recolhidos sobre a utilização de uma aplicação. Informação detalhada sobre as operações realizadas pelos utilizadores, o contexto de utilização da aplicação, erros, etc.

Application Insights

Este serviço do Windows Azure permite recolher dados de vários tipos sobre aplicações hospedadas no Azure e também fornece uma API para a configuração do serviço e recolha de eventos adicionais.

Desenho

Numa primeira fase as aplicações Elevation apenas recolherão informação a partir do servidor Web. Ou seja, sobre o Web site ASP.NET MVC. Fica para uma fase posterior a recolha de informação no cliente (browser).

Para ativar o Application Insights e o Primavera.CoreLib.Telemetry é apenas necessário realizar as seguintes operações no host da aplicação:

(1) Instalar o package Microsoft.ApplicationInsights.Web

(2) Instalar o package Primavera.CoreLib.Telemetry

Configuração do Application Insights

Dado o desenho do Application Insights não é possível encapsular a instalação do seu package nem a configuração necessária no host.

Quando o package é instalado, serão instalados na verdade dos seguintes packages relacionados:

• Microsoft.ApplicationInsights
• Microsoft.ApplicationInsights.Agent.Intercept
• Microsoft.ApplicationInsights.DependencyCollector
• Microsoft.ApplicationInsights.PerfCounterCollector
• Microsoft.ApplicationInsights.Web
• Microsoft.ApplicationInsights.WindowsServer
• Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel

A instalação desses packages criará um ficheiro ApplicationInsights.config na root do host e fará algumas alterações ao ficheiro Web.config:

<system.web>
    (...)
    <httpModules>
        (...)
        <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
    </httpModules>
    (...)
<\system.web>
(...)
<system.webServer>
    (...)
    <modules>
        (...)
        <remove name="ApplicationInsightsWebTracking" />
        <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />
    </modules>
    (...)
<\system.webServer>

Todas estas configurações são necessárias para o serviço funcionar corretametne.

Configuração do CoreLib Telemetry

A assembly Primavera.CoreLib.Telemetry disponibiliza um conjunto de tipos que complementam ou simplificam a interação com o Application Insights (AI).

Um dos aspectos que o AI permite é o de recolher informação sobre as exceções não tratadas no host. No entanto, a configuração dessa funcionalidade é manual e por isso está encapsulada no componente Primavera.Core.Telemetry.HttpMvcApplicationTelemetry.

Esse comportamento está implementado da seguinte forma.

(1) No ficheiro Global.asax.cs, o evento Application_Start()sinaliza o arranque da aplicação para permitir que a telemetria se configure.

protected void Application_Start(object sender, EventArgs e)
{
    // Start telemetry

    HttpMvcApplicationTelemetry.Start();

    // Notify the global application events handler

    GlobalApplicationEventsHandler.OnApplicationStart(this);
}

Em Primavera.Core.Telemetry.HttpMvcApplicationTelemetry:

private static void SetupGlobalFilters(TelemetryConfiguration configuration)
{
    // Collect not handled exceptions?

    if (configuration.Enabled && configuration.ServerTelemetryEnabled && configuration.CollectServerUnhandledExceptions)
    {
        GlobalFilterCollection filters = GlobalFilters.Filters;
        if (filters == null)
        {
            // Tracing

            HttpMvcApplicationTelemetry.TracingCategory.Error("GlobalFilters collection is null.");

            // Throw error

            throw new TelemetryException(Properties.Resources.RES_Error_GlobalFilterCollectionNull);
        }

        filters.Add(new TelemetryHandleErrorAttribute());

        // Tracing

        HttpMvcApplicationTelemetry.TracingCategory.Verbose("Added '{0}' global filter.", typeof(TelemetryHandleErrorAttribute));
    }
}

(2) Note-se que ativação deste comportamento está dependente do setting CollectServerUnhandledExceptions que está inativo por defeito.

(3) Assim, sempre que uma exceção não tratada ocorrer, desde que no web.config os custom errors estejam desligados, o evento será recolhido no AI (ver Primavera.Core.Telemetry.TelemetryHandleErrorAttribute).

/// <summary>
/// Called when an exception occurs.
/// </summary>
/// <param name="filterContext">The action-filter context.</param>
public override void OnException(ExceptionContext filterContext)
{
    // Tracing

    Tracing.Category(nameof(TelemetryHandleErrorAttribute))
        .Information("Unhandled exception raised.");

    // Initialized?

    if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
    {
        // Only if customError is enabled

        if (filterContext.HttpContext.IsCustomErrorEnabled)
        {
            // Set the exception source

            filterContext.Exception.SetSource(nameof(TelemetryHandleErrorAttribute));

            // Write (using tracing listener)

            TelemetryTracingListener.WriteException(filterContext.Exception);

            // Tracing

            Tracing.Category(nameof(TelemetryHandleErrorAttribute))
                .Information("Collected unhandled exception.");
        }
        else
        {
            // Tracing

            Tracing.Category(nameof(TelemetryHandleErrorAttribute))
                .Information("CustomError is enabled. Exception will not be collected.");
        }
    }

    // Default behavior

    base.OnException(filterContext);
}

Tracing

Está disponível também um tracing listener que facilita o registo de eventos de tracing para o AppInsights. O seu registo deve ser feito da seguinte forma:

<tracingConfiguration>
    <elements>
        <add name="default" level="Error">
            <listeners>
                <add type="Primavera.Core.Telemetry.TracingListeners.TelemetryTracingListener, Primavera.CoreLib.Telemetry, Version=3.0.0.0, Culture=neutral, PublicKeyToken=33086db60a481256" />
            </listeners>
        </add>
    </elements>
</tracingConfiguration>

TelemetryWriter

O componente Primavera.Core.Telemetry.TelemetryWriter disponibiliza a API completa para registo de eventos, erros, etc na telemetria.

Eis um exemplo da sua utilização:

public void WriteSomeTelemetry()
{
    using (TelemetryWriter writer = new TelemetryWriter())
    {
        writer.WriteEvent("event");
        writer.WriteException(new InvalidOperationException());
        writer.WriteMetric("metric", 10);
        writer.WriteTrace(TelemetrySeverityLevel.Warning, "trace");
    }
}

Os métodos disponibilizados são os seguintes: - WriteEvent - para registar um evento custom. - WriteException - para registar um erro. - WriteMetric - para registar uma métrica. - WriteTrace - para registar um registo de trace.

Ativação do Serviço

Para o serviço recolher realmente os dados no Azure é necessário configurar os app settings do host para incluirem a instrumentation key correspondente.

Questões

• P: Não está a ser recolhida nenhuma informação no application insights. Porquê?
  • R: Provavelmente porque a instrumentation key não está definida ou as configurações no web.config e/ou no applicationinsights.config está incorretas.
• P: Não está a ser recolhida qualquer informação sobre exceções não tratadas. Porquê?
  • R: Provavelmente porque os custom errors estão ativos no web.config.