Using External Logging

External Logging gives Relativity application developers complete control over their logging. Developers instrument the application with the logging framework of their choice (for example Serilog and ILogger) and send the logs to a service that they control (such as New Relic, Datadog, or Seq). External logging provides:

  • Quasi-realtime access to logs,
  • Better control over filtering logs, and
  • Possibility to send telemetry other than logs (e.g. metrics or traces).

In most cases, external logging is the preferred logging solution for production application over using the IAPILog Interface for logging.

Prerequisites

With External Logging, you are responsible for the content of the logs and their storage. As a consequence, you must be aware of the legal requirements surrounding the collection and treatment of the logs. For example, you must inform customers of the external data flow, the content of the logs, and how the storage respects data handling legislation.

To use External Logging, you must have access to a service ("logging service") to accept, store, and query the generated telemetry. This may be a service and deployed within the developer's data center (for example Seq) or a commercial vendor (such as New Relic, Datadog). The service you choose will determine what logging frameworks and sinks will be available to you.

Scope

When using External Logging, any logs sent to your custom logging provider in your application will be forwarded to your logging service. Depending on the capabilities of your logging service, you may also be able to configure and instrument your application to send metrics and traces in addition to logs. The ADS framework (via the default logger or logging helper) will never send data to your logging provider. ADS framework logs will not be forwarded to your logging service; you must still access those through the Log Extractor, if necessary.

Data Security

  • Do not log any secrets (access tokens, passwords), names, private information, and sensitive information.
  • Log only data and telemetry data created by your application.
  • Do not log data owned by the end-user; for example, data from RelativityOne database, file content, file paths, or names.
  • Log only minimally necessary data.
  • Let the data owner know what data your application is logging externally.

Note: An allow-list filters network access for the Government RelativityOne environment, including outbound traffic. If you choose New Relic for your vendor, the relevant endpoints are already present in the allow-list. If you choose a different vendor, you must open a ticket with Customer Support to add new allow-list entries.

Logging Instance Settings

Your application must provide instance settings that allow customers to control your application's logging. At a minimum, the application should provide:

  • LoggingLevel: Enum with defined logging levels. Must include "none" value to turn off logging completely. The "none" value must be the default.
  • LoggingEndpoint: Text value with the endpoint where logs should be sent. The Default value should be a valid external logging service.
  • LoggingToken: Encrypted text value with the token to use to access the external logging service. Default value is empty. See documentation for Storing and using external API credentials.

Additional instance settings can be provided to control other aspects of the logging, as necessary.

All the instance settings should be created in a section specific to the application, e.g. "MyCustomApplication". See the documentation for the Instance Setting Manager to create an Instance Setting. The instance settings should be created when installing the application via a post install Event Handler. The Event Handler should be configured to run only once to avoid resetting instance setting values on application upgrades. RunTarget should be set to Instance.

Note: You should follow best practices with the LoggingToken and rotate it periodically, e.g. every 90 days.

Logging Packages

You must add the packages to your application that allow you to send logs to your logging provider. These packages need to be declared as application dependencies. If they or any transitive dependencies conflict with ADS platform dependencies, then you will need to internalize your dependencies. You might consider using ILRepack or ILMerge (archived, 19 March 2021) to do so.

Logging

When initializing your application, you must also initialize your custom logging provider. Read the logging instance settings and use their values to create your logger. You will need to expose that logger, likely through a global singleton value, to the rest of the application.

Add logging statements throughout code to capture necessary operational information. Pay particular attention to the assigned log level for each message. Details of the API will depend on the logging framework you have chosen, but most will provide functions like logger.error(exception, message).

Note: Be sure to flush your logging provider when the application terminates. You may not receive all logs otherwise.

Troubleshooting

If you are not receiving logs from your application:

  • Check that your application does not have any dependencies that conflict with the ADS platform dependencies. Conflicts will cause the application to fail.
  • Verify that logging levels, endpoints, and tokens are all correct.
  • Ensure that your logging service is working correctly.
  • Check that ADS framework logs (from the LogExtractor) do not indicate any problems.