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

The most common way of injecting configuration via code is to create an AgentConfiguration object and pass it to Log.StartSession.  Loupe will then use this configuration as its baseline, sanitize it, and then start. 

If you want to override configuration values at runtime via code you can subscribe to the Initializing event of the Log object.  This event is raised whenever the Agent attempts to initialize and lets you override configuration settings before they are final and cancel initialization if you want to.

You can also perform all configuration through files or environment variables using the .NET Core configuration builder without using code.  See Developer's Guide - Agent Configuration through Configuration Builder 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 (or uses the supplied configuration) and then:

1. 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.
2. The configuration is sanitized to ensure it can be loaded safely and the agent completes its initialization.

class CodeConfigProgram
{
    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    static void Main(string[] args)
    {
        //create an AgentConfiguration object, specifying everything you want to override.
        var loupeConfig = new AgentConfiguration
        {
            Publisher = new PublisherConfiguration
            {
                ProductName = "Loupe",
                ApplicationName = "Agent Text",
                ApplicationType = ApplicationType.Console,
                ApplicationDescription = "Console test application for .NET Core",
                ApplicationVersion = new Version(2, 1)
            },
            Server = new ServerConfiguration
            {
                UseGibraltarService = true,
                CustomerName = "Your_Service_Name"
            }
        };
        Log.StartSession(loupeConfig, "Starting Loupe Console");
        try
        {
            //Here is the body of your console application
        }
        catch (Exception ex)
        {
            Log.RecordException(ex, "Main", false);
            Log.EndSession(SessionStatus.Crashed, "Exiting due to unhandled exception");
        }
        finally
        {
            Log.EndSession(SessionStatus.Normal, "Exiting test application");
        }
    }
}

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 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.