Log from a Relativity application
- Notes:
- To access logs for a custom application, you can use the log extractor available through the RelativityOne UI. For more information, see Log Extractor on the RelativityOne documentation site.
- You can't log from a standalone console application.
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
Logging is built into the Relativity infrastructure and can be accessed using the API helpers. You can call the loggers from applications components, such as agents, custom pages, and event handlers.
The following code sample demonstrates how to call a default logger from an agent:
- Instantiate the logger. Copy
private Relativity.API.IAPILog _logger;
_logger = this.Helper.GetLoggerFactory().GetLogger().ForContext<MyAgent>();Note: It is recommended to always scope a logger to a class using the ForContext<T>() method.
- Call the logger.Copy
_logger.LogDebug(“Enabling agent {AgentName}”, Me.Name);
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.
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 preferred way to interact with Relativity.
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.");
}
}
}
}The following code sample illustrates how to log from an event handler. You can find more information about implementing event handlers in Lesson 4 - Validate object changes.
public override Response Execute()
{
var retVal = new Response();
try
{
var serviceManager = Helper.GetServicesManager();
Logger.LogVerbose($"Start '{nameof(Execute)}' method");
using (var objectManager = serviceManager.CreateProxy<IObjectManager>(ExecutionIdentity.System))
using (var wikiService = serviceManager.CreateProxy<IWikipediaService>(ExecutionIdentity.System))
{
var job = new ValidateArticleCategoryEventHandlerJob(this.ActiveArtifact, this.Logger, wikiService, objectManager, this.Helper);
retVal = Task.Run(async () => await job.ExecuteAsync()).ConfigureAwait(false).GetAwaiter().GetResult();
}
Logger.LogDebug($"{nameof(retVal)}: {retVal}", null, retVal);
}
catch (Exception ex)
{
retVal.Success = false;
retVal.Message = $"{ex}";
Logger.LogError($"An error occured in '{nameof(Execute)}' method", ex, ex);
}
finally
{
Logger.LogVerbose($"End '{nameof(Execute)}' method");
}
return retVal;
}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.Copy
var myClassLogger = _logger.ForContext<MyClass>();
- Pass an arbitrary string key-value pair to identify messages from a specific logger.Copy
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.Copy
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.Copy// 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:
Copy// 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.
Copy//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:
CopyWith 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.
Data Logging Security
Follow good security practices when writing and retrieving logs to minimize data exposure:
- Consult the data owner on data disclosure before logging.
- Log data according to the data owner's data policy (Relativity recommends logging only the identifiers. Avoid logging names, private information, and sensitive information).
- Log only minimally necessary data.
- Notify Relativity support if a data exposure incident is identified.
