Chat Support
Loupe - Log - Monitor - Resolve
Loupe / Getting Started - Introduction
In This Topic
    Getting Started - Introduction
    In This Topic

    Step 1: Add Loupe to Your Application

     

    Add the the following NuGet packages to get Loupe and its relevant dependencies:

    1. Loupe.Agent.AspNetCore: The main Loupe extension for ASP.NET Core, which will also pull in the main Loupe agent itself.
    2. Loupe.Extensions.Logging: Connects Loupe with the Microsoft.Extensions.Logging infrastructure which is used by ASP.NET for common logging.
    3. Loupe.Agent.Core.Services: A small package with configuration builders for ASP.NET Core.
    4. Loupe.Agent.EntityFrameworkCore (Optional): Connects Loupe with EF Core to record performance and diagnostic information for EF Core.
    5. Loupe.Agent.PerformanceCounters (Optional): Records a collection of Windows Performance Counters on Windows systems.

    The recommended way to activate the ASP.NET Core Agent is to add it to the Loupe Agent Builder during the Host setup, typically in Program.cs like this:

    Host Builder Example for Program.cs
    Copy Code
        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .AddLoupe(builder => builder.AddAspNetCoreDiagnostics()
                    .AddClientLogging() //The Loupe endpoint for client logging
                    .AddEntityFrameworkCoreDiagnostics() //EF Core monitoring
                    .AddPerformanceCounters()) //Windows Perf Counter monitoring
                .AddLoupeLogging();
    

    The Loupe Agent for ASP.NET Core needs to access the HttpContext to monitor requests. This isn't always available by default in the ASP.NET Core Dependency Injection context, so we need to add it during the services collection in case it isn't pulled in by any other service. To do this, add the HttpContext Accessor at the top of the ConfigureServices call in the Startup class, like this:

    HttpContext Accessor for Startup.cs
    Copy Code
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHttpContextAccessor();
        //The rest of your services
    }
    

    Adding Client-side Logging

    The Loupe Agent for ASP.NET Core can create a logging endpoint so browser applications can add messages into the Loupe log.  In addition to adding the client side logging to your host builder (as done above) the endpoint has to be mapped and a cookie added to the request handling pipeline.

    To add the Loupe cookie-handling middleware in the app pipeline call UseLoupeCookies in your Configure method of the startup class used for the web site, typically in Startup.cs..  This should go before any Authentication or Routing call but after a Static Files call, if present.  For example:

    Loupe Cookie Handling
    Copy Code
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        // ...
       
        app.UseStaticFiles();
        app.UseLoupeCookies(); // Add Loupe cookie-handling
        app.UseRouting();
        app.UseAuthorization();
       
        // ...
    }
    

    To complete adding the endpoint to receive log messages from the client call MapLoupeClientLogger method in the Configure method as well.  For example:

    Typical Configuration Method
    Copy Code
     public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
     {
             app.UseEndpoints(endpoints =>
             {
                  endpoints.MapControllerRoute(
                          name: "default",
                          pattern: "{controller}/{action=Index}/{id?}");
                  endpoints.MapLoupeClientLogger();
             });
     }
    

     

    For more details on how to integrate Loupe see Using Loupe with ASP.NET Core

    Use NuGet to add the Loupe Agent for ASP.NET MVC to your web application project.  It will automatically add the Loupe Agent to the same project.  You will often want to add the Loupe Agent to other projects in your solution, but the MVC agent only needs to be referenced in one place.

    Once the Agent has been referenced you will need to add a few lines to your application startup to insert the MVC Agent into the global filters configuration.

    using Gibraltar.Agent;
    using Gibraltar.Agent.Web.Mvc.Filters;
    
    public class MvcApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            Log.StartSession(); //Prompt the Loupe Agent to start immediately
    
            //Register the three filters (Order is not important)
            GlobalConfiguration.Configuration.Filters.Add(
                new WebApiRequestMonitorAttribute());
            GlobalFilters.Filters.Add(new MvcRequestMonitorAttribute());
            GlobalFilters.Filters.Add(new UnhandledExceptionAttribute());
         }
    }
    
    Imports Gibraltar.Agent
    Imports Gibraltar.Agent.Web.Mvc.Filters
    
    Public Class MvcApplication
         Inherits System.Web.HttpApplication
         Protected Sub Application_Start()
             Log.StartSession() 'Prompt the Loupe Agent to start immediately
             'Register the three filters
             GlobalConfiguration.Configuration.Filters.Add( _
                    New WebApiRequestMonitorAttribute())
             GlobalFilters.Filters.Add(New MvcRequestMonitorAttribute())
             GlobalFilters.Filters.Add(New UnhandledExceptionAttribute())
         End Sub
    End Class
    

    For more details on how to integrate Loupe see Using Loupe with ASP.NET MVC

    Add the Gibraltar Loupe Agent for ASP.NET WebForms NuGet package to your web project. This will add the basic Loupe Agent and the ASP.NET WebForms agent which automatically records performance and error information for ASP.NET.

    For more details on how to integrate Loupe see Using Loupe with ASP.NET WebForms

    Start by adding the Gibraltar Loupe Agent NuGet package to your WPF project.

    To integrate Loupe with WPF, add a couple lines to your App class and Loupe will log all unhandled exceptions:

    using System.Windows;
    using Gibraltar.Agent;
    public partial class App : Application
    {
      public App() {
        DispatcherUnhandledException += (sender, e) => {
               Log.ReportException(e.Exception, "Unhandled", true, false);
               e.Handled = true;
           };
      }
      protected override void OnStartup(StartupEventArgs e) {
        Log.StartSession();
        base.OnStartup(e);
      }
      protected override void OnExit(ExitEventArgs e) {
        Log.EndSession();
        base.OnExit(e);
      }
    }
    

    For more details on how to integrate Loupe see Using Loupe with WPF

    Start by adding the Gibraltar Loupe Agent NuGet package to your WinForms project.

    To integrate Loupe with WinForms, add a couple lines to your Program class and Loupe will log all unhandled exceptions:

    using System.Windows;
    using Gibraltar.Agent;
    static class Program
    {
      [STAThread]
      static void Main()
      {
        Log.StartSession();
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.Run(new Form1());
        Log.EndSession();
      }
    }
    

    For more details on how to integrate Loupe see Using Loupe with WinForms

    Start by adding the Gibraltar Loupe Agent NuGet package to your Windows Service project.

    To integrate Loupe with your service, add a couple lines to your Service class and Loupe will log all unhandled exceptions:

    using System.Windows;
    using Gibraltar.Agent;
    public partial class YourService : ServiceBase
    {
      public YourService()
      {
        InitializeComponent();
      }
      protected override void OnStart(string[] args)
      {
        Log.StartSession();
      }
      protected override void OnStop()
      {
        Log.EndSession();
      }
    }
    

    For more details on how to integrate Loupe see Using Loupe with Windows Services

    Add the following dependency to your pom.xml:

    <dependency>
        <groupId>com.onloupe</groupId>
        <artifactId>core</artifactId>
        <version><-- desired version --></version>
    </dependency>
    

    Then rebuild your application to incorporate the agent into your application. With just the core agent you can record metrics and capture diagnostic information about your application.

    For more details on how to integrate Loupe see Developer's Guide - Java -Using Loupe with Java

    Step 2: Configure Your App to Send Data to Loupe Server

    .NET Core uses a different, more flexible, approach to application configuration than .NET Framework applications.  Instead of XML config files .NET Core has an entire extensible configuration subsystem that can be used.  In most situations you'll do a combination of coded configuration and JSON configuration.  For details, see Developer's Guide - Agent Configuration.

    Once you've instrumented an application you'll want to set up a connection with Loupe Server so you can collect data from everywhere your application runs and start managing errors.  Add this configuration to your appsettings.json file to send data to this server automatically in the background.  You'll need to make a few changes to this JSON to have it work:

    • Replace "Your Loupe Service Name" with the name of your Loupe Cloud-hosted Service.  If you don't have one yet, sign up for a free trial service.
    • Replace "Your Product" and "Your Application" with friendly values for your application.  A good analogy for Product is "Office" and Application is "Word", "Excel", and "PowerPoint". 
    {
      "Logging": {
        "IncludeScopes": false,
        "LogLevel": {
          "Default": "Warning"
        }
      },
      "Loupe": {
        "Publisher": {
          "ProductName": "Your Product",
          "ApplicationName": "Your Application",
          "ApplicationType": "AspNet",
          "ApplicationVersionNumber": "1.0.1"
        },
        "Server": {
          "UseGibraltarService": true,
          "CustomerName": "Your Loupe Service Name",
          "AutoSendSessions": true,
          "SendAllApplications": true
        }
      }
    }
    

    Once you've instrumented an application you'll want to set up a connection with Loupe Server so you can collect data from everywhere your application runs and start managing errors.  Add this configuration to your app.config / web.config to send data to this server automatically in the background.  You'll need to make a few changes to this XML to have it work:

    • Replace "Your Loupe Service Name" with the name of your Loupe Cloud-hosted Service.  If you don't have one yet, sign up for a free trial service.
    • Replace "Your Product" and "Your Application" with friendly values for your application.  A good analogy for Product is "Office" and Application is "Word", "Excel", and "PowerPoint". 
    <configuration>
      <configSections>
        <sectionGroup name="gibraltar">
          <section name="publisher" type="Gibraltar.Agent.PublisherElement, Gibraltar.Agent" />
          <section name="server" type="Gibraltar.Agent.ServerElement, Gibraltar.Agent" />
        </sectionGroup>
      </configSections>
      <gibraltar>
        <publisher productName="Your Product" applicationName="Your Application" />
        <server autoSendSessions="True" sendAllApplications="True" useGibraltarService="True" customerName="Your Loupe Service Name"  />
      </gibraltar>
    </configuration> 
    
    Sign into the web UI for Loupe to see an exact, customized snippet of this XML with your server configuration embedded in it.

    Loupe has extensive configuration options to tune what it collects and how that information is presented to the server. Check out Common Agent Configuration Scenarios for more details.

    The Loupe Agent needs a minimal configuration to identify the application, set the logging folder, and connect to a Loupe Server.

    Once you've instrumented an application you'll want to set up a connection with Loupe Server so you can collect data from everywhere your application runs and start managing errors.  You'll need to make a few changes to the configuration examples below to have them work:

    • Replace "Your Loupe Service Name" with the name of your Loupe Cloud-hosted Service.  If you don't have one yet, sign up for a free trial service.
    • Replace "Your Product" and "Your Application" with friendly values for your application.  A good analogy for Product is "Office" and Application is "Word", "Excel", and "PowerPoint". 

    Configuration via Properties File

    Loupe can also be configured using properties files - loupe.properties for the name/value pair text properties format and loupe.xml for the XML file format. The properties file need only be placed on the classpath, and Loupe will detect and utilize it.

    Publisher.ProductName=Your Product
    Publisher.ApplicationName=Your Application
    Publisher.ApplicationVersion=1.0.0
    Server.UseGibraltarService=true
    Server.CustomerName=Your Loupe Service Name
    Server.AutoSendSessions=true
    Server.SendAllApplications=true
    
    <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
    <properties>
        <entry key="Publisher.ProductName">Your Product</entry>
        <entry key="Publisher.ApplicationName">Your Application</entry>
        <entry key="Publisher.ApplicationVersion">1.0.0</entry>
        <entry key="Server.UseGibraltarService">true</entry>
        <entry key="Server.CustomerName">Your Loupe Service Name</entry>
        <entry key="Server.AutoSendSessions">true</entry>
        <entry key="Server.SendAllApplications">true</entry>
    </properties>
    

    Configuration via Code

    Loupe can be configured directly using its configuration object, for example:

    AgentConfiguration configuration = AgentConfiguration.builder()
        .publisher(PublisherConfiguration.builder()
            .productName("Your Product")
            .applicationName("Your Application")
            .applicationVersion(new Version(1, 0, 0)).build())
        .server(ServerConfiguration.builder()
            .useGibraltarService(true)
            .customerName("Your Loupe Service Name")
            .sendAllApplications(true).build())
        .sessionFile(SessionFileConfiguration.builder()
            .folder("C:\\Temp").build())
        .build();
    

    The configuration object can then be injected in an explicit call to start Loupe:

    Log.start(configuration);
    

    Or, if using the loupe-api package:

    Loupe.start(configuration);
    

    Step 3: Run Your Application Anywhere

    Data gets recorded by Loupe and uploaded to the server automatically once each log files is closed. Files get closed when your application exists or when an error is recorded.

    Files get sent to the server in the background on a low-priority thread; let your application run for a minute to give the background task time to start and send data. Once data has been sent to the server, you'll see it show up within a few moments.

    We're Here to Help

    We're committed to making Loupe an indispensable tool for you and your team. If you're not delighted, neither are we. Please email us at Support@OnLoupe.com. or click to chat if you're having trouble.

    Where To Next?

    See Also