Adding the Loupe Agent to your Application

The first step is to add the core Loupe Agent to your application via NuGet.  This will automatically put a skeleton for the configuration in your app.config/web.config and add a reference to the latest release of the Loupe Agent.  You can then build on this with additional technology specific agents as you desire.

Configuring the Agent in Code

You can configure all of the agent options without using or even creating an application configuration file.  To do this, you need to subscribe to the Initializing event of the Log object. 

You can also perform all configuration through the application configuration file without using code.  See Developer's Guide - Agent Configuration through Configuration Files for complete details.

Initialization Process

The Initializing event is raised every time an attempt is made to start the Agent and it hasn't started.  Whenever initialization is started, the Agent creates a default configuration and then:

1. Application Configuration File information is loaded first to override the default values for the agent.
2. The Log.Initializing event is raised with the application configuration objects to allow for programmatic manipulation of the configuration.  Event subscribers can also elect to cancel the initialization which will prevent the agent from operating but still allow all API calls to be made safely.
3. The configuration is sanitized to ensure it can be loaded safely and the agent completes its initialization.

/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main()
{
    //Connect to the log initializing event before we do ANYTHING with the agent so we can
    //configure it and even cancel it.
    Log.Initializing += Log_Initializing;
    Log.StartSession();
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    Application.Run(new frmMain());
    Log.EndSession();
}
static void Log_Initializing(object sender, LogInitializingEventArgs e)
{
    //you can use the publisher configuration to override the product & application name
    e.Configuration.Publisher.ProductName = "Override Product";
    e.Configuration.Publisher.ApplicationName = "Override Application";
    //you can also add name/value pairs to be recorded in the session header for improved
    //categorization and analysis later.
    e.Configuration.Properties.Add("CustomerName", "The customer name from our license");
    //you can also use the cancel feature combined with #define to turn off the agent
    //at compile time.
#if (!DEBUG)
    //this is not a debug compile, disable the agent.
    e.Cancel = true;
#endif
}

What Can Trigger Initialization

Initialization can be triggered a few ways:

1. The first time the Log object is used in any way it will attempt to initialize so that it can complete the initial request.
2. Whenever Log.StartSession is called and the agent hasn't already initialized.

Because initialization can be canceled it's possible for this event to be raised multiple times.  Each time initialization is triggered the configuration defaults back to the documented defaults and then any application configuration file information is applied.

What Happens if Initialization is Canceled

If initialization is canceled then the Agent will be accessible but disabled.  In this state:

• No data will be stored.
• The Live Viewer, Packager, and Error Manager will be disabled.
• The SessionSummary information is still available, but won't reflect any overrides that would have come from configuration (such as Product or Application names).

Even though it is disabled, every API call will still succeed and act in a sensible manner.  For example, event metric code can still be called to define metrics and attempt to record them, however no information will be stored.  In this mode the Agent has virtually no overhead and is completely safe.  If the agent is subsequently initialized then all information from that point on will be recorded.  Metrics that were defined earlier in the session can be recorded as if they were defined after it was activated. 

Common Scenarios

While the default configuration values will get you far, to enable Loupe Server and tune how the Agent works you'll want to consult our Developer's Guide - Agent Configuration Common Scenarios.