Version:

As part of the Relativity Services API (RSAPI) Deprecation, content on this page referring to the RSAPI and the Patient Tracker application is in the process of being deprecated and will no longer be supported. For more information and alternative APIs, see RSAPI deprecation process.

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, such as the application presented in Build your first Services API client.

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 from the Patient Tracker application.

Custom page

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;

namespace PatientTracker.CustomPages.Controllers
{
    /// <summary>
    /// This custom page shows how to use a patient artifactID and current workspace artifactID to retrieve information from the RSAPI, and then display a profile page for the patient.
    /// </summary>
    public class PatientController : Controller
    {
        private Relativity.API.IAPILog _logger;

        public static readonly Guid PATIENT_RDO_GUID = new Guid("EDC3AF33-7D25-4897-8285-6E36EA1D4AAE");

        public static readonly Guid FIRST_NAME_FIELD_GUID = new Guid("EB024552-3A1B-40C1-B4DC-5815C3DD3AD3");
        public static readonly Guid LAST_NAME_FIELD_GUID = new Guid("DA73E11E-9D02-4D29-9D3C-F84E66223B2A");
        public static readonly Guid GENDER_FIELD_GUID = new Guid("04E5F293-A4E1-4DF4-8816-F1E6645AE001");
        public static readonly Guid DATE_OF_BIRTH_FIELD_GUID = new Guid("96BC22AF-F2F6-4C92-AD96-CF08BF9AAB4D");
        public static readonly Guid PATIENT_NOTES_FIELD_GUID = new Guid("5702F31B-48AC-4E2A-9000-A48B3E3ABDBF");
        public static readonly Guid PICTURE_FIELD_GUID = new Guid("006F21C0-66C8-46E0-94B2-EF37C6478C2D");

        public ActionResult Index(Int32 patientArtifactID, Int32 workspaceArtifactID)
        {
            //Get the logger from the helper and set the ForContext to this class.
            _logger = Relativity.CustomPages.ConnectionHelper.Helper().GetLoggerFactory().GetLogger().ForContext<HomeController>();

            PatientTracker.CustomPages.Models.PatientModel patient = new Models.PatientModel();
            kCura.Relativity.Client.DTOs.RDO patientRDO = null;

            try
            {
                //Create an instance of the RSAPIClient so we can pull back information about the patient.
                using (kCura.Relativity.Client.IRSAPIClient client = Relativity.CustomPages.ConnectionHelper.Helper().GetServicesManager().CreateProxy<kCura.Relativity.Client.IRSAPIClient>(Relativity.API.ExecutionIdentity.System))
                {
                    _logger.LogInformation("Attempting to pull patient info for {PatientArtifactID} in workspace {WorkspaceID}", patientArtifactID, workspaceArtifactID);

                    //Set the workspace artifactID.
                    client.APIOptions.WorkspaceID = workspaceArtifactID;

                    //Create an instance of the RDO with the Patient RDO GUID and the patient artifactID.
                    patientRDO = new kCura.Relativity.Client.DTOs.RDO(patientArtifactID);
                    patientRDO.ArtifactTypeGuids.Add(PATIENT_RDO_GUID);
                    patientRDO.Fields = kCura.Relativity.Client.DTOs.FieldValue.AllFields;

                    //Get the patient RDO from the RSAPI.
                    patientRDO = client.Repositories.RDO.Read(patientRDO).Results[0].Artifact;

                    //Set properties on the patient model.
                    patient.FirstName = patientRDO.Fields.Where(x => x.Guids.Contains(FIRST_NAME_FIELD_GUID)).Single().ValueAsFixedLengthText;
                    patient.LastName = patientRDO.Fields.Where(x => x.Guids.Contains(LAST_NAME_FIELD_GUID)).Single().ValueAsFixedLengthText;
                    patient.DateOfBirth = patientRDO.Fields.Where(x => x.Guids.Contains(DATE_OF_BIRTH_FIELD_GUID)).Single().ValueAsDate.Value;
                    patient.PatientNotes = patientRDO.Fields.Where(x => x.Guids.Contains(PATIENT_NOTES_FIELD_GUID)).Single().ValueAsLongText;

                    //Construct a download request used to get a proper download url for the file to be downloaded.
                    kCura.Relativity.Client.DownloadURLRequest pictureFieldDownloadRequest = new kCura.Relativity.Client.DownloadURLRequest(client.APIOptions);
                    Uri currentUrl = Request.Url;
                    pictureFieldDownloadRequest.BaseURI = new Uri(String.Format("{0}://{1}/", currentUrl.Scheme, currentUrl.Host));
                    pictureFieldDownloadRequest.Target.FieldGuid = PICTURE_FIELD_GUID;
                    pictureFieldDownloadRequest.Target.ObjectArtifactId = patientArtifactID;

                    //Set the picture file path on the patient model.
                    patient.PicturePath = client.Repositories.RDO.GetFileFieldDownloadURL(pictureFieldDownloadRequest).URL;
                }
            }
            catch (System.Exception ex)
            {
                patient.PatientNotes = "EXCEPTION: " + ex.ToString();

                //Log an error.
                _logger.LogError(ex, "There was an issue pulling back patient info.");
            }
            return View(patient);
        }
    }
}

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.

Community Updates
Aero Developer FAQ	Evolving the Platform	Most recent release notes
Learn more	Learn more	Learn more

Additional Resources

Access Third-Party Tools with GitHub			Create .NET Apps Faster with NuGet
Visit github			visit nuget