Version:

Log from a Relativity application

You can write logs from your custom applications that use agents, custom pages, and event handlers. Use Relativity API helpers to add loggers to your applications. To capture the data that meets your debugging needs, you can change properties captured for the logged events. You can also change the logging level and configure logging to log only for a specific application, log to a specific sink, or disable logging.

Note: You can't log from a standalone console application.

This page contains the following information:

Before you begin

Before using logging in a custom application, make sure logging is enabled in Relativity to write to an appropriate sink. If you want to use the defaults, make sure the default configuration row in the RelativityLogging.Configuration table is set to True (1). This enables logging to the EDDSLogging.RelativityLogs table at the Error (4) level. .

IAPILog interface

The IAPILog interface included in the Relativity API namespace enables logging functionality. These IAPILog interface methods correspond to the available logging levels:

public interface IAPILog {
 
    void LogVerbose(string messageTemplate, params object[] propertyValues);
    void LogDebug(string messageTemplate, params object[] propertyValues);
    void LogInformation(string messageTemplate, params object[] propertyValues);
    void LogWarning(string messageTemplate, params object[] propertyValues);
    void LogError(string messageTemplate, params object[] propertyValues);
    void LogFatal(string messageTemplate, params object[] propertyValues);
    ...
}

When called from the code, the methods logs the events at the specified level and higher when the events occur. For example, the following code logs Debug, Information, Warning, Error, and Fatal-level events. The events may occur when cleaning Kepler Service Host temporary directories.

Logger.LogDebug("Cleaning up any left over files and folders in the Kepler Service Host temporary directories");

Each method can also take an exception object. This outputs the exception and stack trace into a separate field in the database to assist with searching.

public interface IAPILog {
    ...
    void LogVerbose(Exception exception, string messageTemplate, params object[] propertyValues);
    void LogDebug(Exception exception, string messageTemplate, params object[] propertyValues);
    void LogInformation(Exception exception, string messageTemplate, params object[] propertyValues);
    void LogWarning(Exception exception, string messageTemplate, params object[] propertyValues);
    void LogError(Exception exception, string messageTemplate, params object[] propertyValues);
    void LogFatal(Exception exception, string messageTemplate, params object[] propertyValues);
    ...
}

Add loggers using API helpers

The following are examples of logging from an agent, a custom page, and an event handler.

Agent

The following code sample illustrates how to log from an agent. You can find more information about building agents in Lesson 5 - Build a cron job.

public override void Execute()
{
    _logger = Helper.GetLoggerFactory().GetLogger();
    try
    {
        using (var applicationInstallManager = Helper.GetServicesManager().CreateProxy<IApplicationInstallManager>(ExecutionIdentity.System))
        using (var objectManager = Helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.System))
        using (var wikipediaService = Helper.GetServicesManager().CreateProxy<IWikipediaService>(ExecutionIdentity.System))
        using (var tempFileCollection = new TempFileCollection())
        {
            ImportAPI importApi = ImportAPI.CreateByRsaBearerToken(Constants.WEB_SERVICE_URL);
            var manager = new WikipediaArticleManager(applicationInstallManager, objectManager, wikipediaService, importApi,_logger);

            List<int> matchingWorkspaceIDs = manager.GetHelloWikipediaWorkspaceIDs().ConfigureAwait(false).GetAwaiter().GetResult().ToList();
            RaiseMessage($"Found Hello Wikipedia in {matchingWorkspaceIDs.Count} workspaces", (int)AgentMessage.AgentMessageType.Informational);

            foreach (int workspaceID in matchingWorkspaceIDs)
            {
                IEnumerable<ArticleCategory> articleCategories = manager.GetArticleCategories(workspaceID).ConfigureAwait(false).GetAwaiter().GetResult();
                List<Article> articles = manager.GetArticles(articleCategories, Constants.NUMBER_OF_ARTICLES).ConfigureAwait(false).GetAwaiter().GetResult().ToList();
                ImportBulkArtifactJob job = manager.BuildArticleImportJob(workspaceID, articles, tempFileCollection).ConfigureAwait(false).GetAwaiter().GetResult();
                
                job.Execute();
                job.SourceData.SourceData.Close();
                manager.AddOrUpdateArticleReferences(workspaceID, articles).ConfigureAwait(false).GetAwaiter().GetResult();

                RaiseMessage($"Processed {articles.Count}", (int)AgentMessage.AgentMessageType.Informational);
            }
        }
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Failed to process Wikipedia pages.");
        RaiseError(ex.Message, ex.Message);
    }
}

Note: This code sample also demonstrates the use of the RaiseMessage() method of the AgentBase to log information-level events.For more information about AgentBase logging methods, see Basic concepts for agents. For debugging, using IAPILog interface through API helpers is the recommended way of logging from agents.

Custom page

The following code sample illustrates how to log from custom page. It is taken from the template called Relativity Custom Page Form available in Visual Studio after installing NuGet package for Relativity.CustomPages. For more information, see Relativity.CustomPages on the NuGet website.

using Relativity.API;
using Relativity.Services.Objects;
using System;
using System.Net;

namespace CustomPageForm
{
    public partial class Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            IAPILog logger = Relativity.CustomPages.ConnectionHelper.Helper().GetLoggerFactory().GetLogger();

            try
            {
                // Update Security Protocol
                ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

                //Gets the user ID.
                int userArtifactId = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.ArtifactID;
                //Gets the user ID to use for auditing purposes.
                int userAuditArtifactId = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.AuditArtifactID;
                //Gets the user workspace artifact ID to use for auditing purposes.
                int userAuditWorkspaceUserArtifactId = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.AuditWorkspaceUserArtifactID;
                //Gets the email address of the current user.
                string userEmailAddress = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.EmailAddress;
                //Gets the first name of the current user.
                string firstName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.FirstName;
                //Gets the last name of the current user.
                string lastName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.LastName;
                //Gets the full name of the current user.
                string fullName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.FullName;
                //Gets the current user workspace artifact ID.
                int currentUserWorkspaceArtifactId = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.WorkspaceUserArtifactID;

                //Get GUID for an artifact
                int testArtifactId = 1234567;
                Guid guidForTestArtifactId = Relativity.CustomPages.ConnectionHelper.Helper().GetGuid(currentUserWorkspaceArtifactId, testArtifactId);

                //Get a dbContext for the EDDS database
                IDBContext eddsDbContext = Relativity.CustomPages.ConnectionHelper.Helper().GetDBContext(-1);

                //Get a dbContext for the workspace database
                IDBContext workspaceDbContext = Relativity.CustomPages.ConnectionHelper.Helper().GetDBContext(currentUserWorkspaceArtifactId);

                //The Object Manager is the newest and preferred way to interact with Relativity instead of the Relativity Services API(RSAPI). 
                using (IObjectManager objectManager = Relativity.CustomPages.ConnectionHelper.Helper().GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.CurrentUser))
                {

                }

                logger.LogVerbose("Log information throughout execution.");
            }
            catch (Exception ex)
            {
                //Your custom page caught an exception
                logger.LogError(ex, "There was an exception.");
            }
        }
    }
}

Add custom metadata to loggers

In many cases, you may need to record additional details for your events, for example, to make them easier to identify. With Relativity you can add custom properties (metadata) to your logs. This can be done in the following ways:

Create a logger scoped for a class to add the class properties to the metadata.
```
var myClassLogger = _logger.ForContext<MyClass>();
```

Pass an arbitrary string key-value pair to identify messages from a specific logger.
```
var myLogger = _logger.ForContext(“CodeLocation”, “ZiggyStation”);
```

Associate a code block with a logger through using statement. The following example demonstrates how to add a JobID property to the messages logged by the code running inside the using statement block.
```
using (_logger.LogContextPushProperty("JobId", 12345))
{
    _logger.LogWarning("Any usage of _logger
    within this using context will now have the JobID property.");
}
```

Best practices

The following are the recommended best practices when using logging in your applications:

Create a scoped logger for each class. See examples in Add loggers using API helpers.
Always prefer structured data over string concatenation. Relativity logging events are associated with message templates.
Treating the string parameter to log methods as a message, as in the example below, will degrade performance and consume cache memory.
```
// Don't:
Relativity.Logging.Log.Logger.LogDebug("Enabling agent" + Me.Name);					
```
Instead, always use template properties to include variables in messages. Properties are passed in enclosed in braces:
```
// Do:
Relativity.Logging.Log.Logger.LogDebug("Enabling agent {AgentName}", Me.Name);					
```

If you have an object where all properties can be displayed in a log, you can use the @ symbol to declare a message param as a destructured object. Examples of properties that must never be displayed in the logs are passwords or decrypted text that is normally encrypted. A destructured object in a message template will deserialize the object into JSON and put the results in the message output and in the metadata.

This example shows what happens when you destructure a class object. Any objects that implement IEnumerable, like arrays, lists, tuples, dictionaries, etc., are destructured to JSON even without the @ symbol. Destructuring data types like strings or integers does not deserialize to a JSON string.

 //Sample class
namespace MySampleNamespace
{
    public class MyObject
    {
        public string Description { get; set; }
        public int Value { get; set; }
    }
}
 
//Sample Logging Code
MyObject testObject = new MyObject()
{
    Description = "This is my object",
    Value = 100
};
 
//To get a destructured object put the @ symbol before the name of your message param name: {@...}
Relativity.Logging.Log.Logger.LogDebug("Testing MyObject destructured - {@DeserializedMyObject}", testObject);
 
//If you do not put the @ symbol the object will be outputted as if you did testObject.ToString()
Relativity.Logging.Log.Logger.LogDebug("Testing MyObject not destructured - {NonDeserializedMyObject}", testObject);
 
//Destructuring simple data types results in a non JSON serialized output, just like if
string myString = "My Test String";
Relativity.Logging.Log.Logger.LogDebug("Testing myString destructured - {@MyString}", myString);

This is the output of the code:

With the @ symbol
Message: Testing MyObject destructured - MyObject { Description: "This is my object", Value: 100 }
Without the @ symbol
Message: Testing MyObject destructured - "MySampleNamespace.MyObject"
Simple data type with the @ symbol
Message: Testing myString destructured - "My Test String"

Log all exceptions by adding loggers to try-catch statements.
Log all calls to Relativity REST services.
Log all calls when using the service interfaces instantiated through ServiceFactory, for example, permissions and saved search APIs.
Log any direct SQL access.
Pay attention to the logging levels and don’t overuse logging. Logging can have a significant impact on your disk, database, processor, and network resources.