Telemetry and metrics

Relativity includes functionality for collecting performance, usage, and billing data. You can use performance metrics for monitoring and troubleshooting the applications in your environment. Usage metrics are automatically transmitted to Relativity for analysis and application enhancement purposes. Relativity also collects billing data including the number of active users in your environment.

Telemetry is a required Relativity application that collects metrics:

  • System usage metrics – Telemetry collects system usage metrics and securely sends the data to Relativity to improve the quality and performance of Relativity applications.
  • Billing data – Telemetry also collects and sends billing data to Relativity.
  • Performance metrics – Telemetry provides you with the ability to aggregate performance-related metrics, so you can view reports through any Application Performance Monitoring (APM) tool that integrates with StatsD. For this purpose, you can use any enterprise-level APM tool, which provides an out-of-the-box or custom plugin for StatsD. Telemetry doesn’t transmit performance-related metrics to Relativity.

Telemetry collects billing data and system usage metrics with the Case Statistics Manager agent. For more information, see Case Statistics Manager. For a list of collected metrics, see the Relativity metrics reference.

This page contains the following information:

See these related pages:

Configuring telemetry

All versions of Relativity:

  • Case Statistics Manager agent must be running.
  • The server hosting the Telemetry Metrics Transmission agent must be able to send outbound HTTPS requests to update.kcura.com. If necessary, make necessary changes to your firewall settings.
  • The Telemetry Metrics Transmission agent must be running. It is automatically added to the Agents tab at the instance level. The agent uses the same setup as your Case Statistics Manager agent server and resource pool configuration.

Relativity versions before 9.5.196.102:

  • Port 8195 on the Telemetry Host agent server must be available for inbound Relativity traffic (from your internal network).
  • The Telemetry Host agent must be running. It is automatically added to the Agents tab at the instance level. The agent uses the same setup as your Case Statistics Manager agent server and resource pool configuration.

Starting with 9.5.162.111, you can use the Telemetry Smoke Test Relativity script to verify that telemetry is properly configured in your environment. For more information, see Telemetry Smoke Test.

Configuring metrics collection

You can configure the metrics that you want to collect by updating specific values for instance settings, and running scripts to enable the collection of metrics for specific applications.

Enabling metrics categories

Depending on the version of Relativity, you can enable specific metrics categories and exclude the ones you don't need.

The settings in the EDDSMetrics.Whitelist table control whether Relativity collects metrics for a specific application, for example, Processing. This table is added to your Relativity environment when you install Relativity. It contains all enabled metrics categories. For more information about configuring metrics, contact Relativity Client Services at support@relativity.com.

Obfuscating metrics

If your company does not need us to include user, case, matter, or client names on your Relativity invoices for your own billing or record-keeping purposes, you can use Relativity instance settings to obfuscate them. Common reasons for not obfuscating include billing users and/or workspaces to your customers and ease of managing your user base. We recommend that you consult with your finance/billing department and those who manage your Relativity user base before making changes to the default values.

The instance settings are as follows:

Configuring APM

If you want to collect performance metrics and report on them through your APM tool, you must set up the StatsD service in your environment. You must also update these instance settings to enable Relativity to communicate with StatsD:

  • StatsDHostAddress – the IP address or host name of the StatsD service.
  • StatsDPort – the port number of the StatsD service.

Beginning with 9.5.133.118, you must also install and start the APM Transmission agent to enable performance metrics.

Telemetry lockout

Telemetry is used to collect and transmit billing data to Relativity. This functionality exists in parallel with Case Statistics Manager. For more information, see Case Statistics Manager.

Note: Failure to transmit telemetry billing data to Relativity causes Relativity access to be disabled after seven (7) days. Telemetry lockout is similar to Case Statistics Manager lockout. If your security setup doesn't allow access to public internet, contact Relativity support to configure offline-billing.

A notification of metrics transmission failure is displayed in Alerts:

Metrics transmission failure can be caused by network access problems. It can also be caused by Relativity services failures on the telemetry agent server.

To troubleshoot metrics transmission failure:

  • Review Relativity logs. Look for error related to Metrics Transmission Agent. In most cases, the error message and the exception stack trace can point you to the cause of the failure. You can also use the Errors tab in Relativity.
  • Verify that port 8195 on the telemetry agent server is open to inbound Relativity traffic (Relativity versions before 9.5.196.102).
  • Verify that your network firewall rules allow outbound HTTPS traffic from the Telemetry Transmission agent server to update.kcura.com.
  • Verify that Relativity services are running properly on the Telemetry agent server and that metrics are being logged.
  • Verify that your network firewall rules allow outbound internet traffic from the telemetry agent server to the Relativity billing server.
  • After you identified and corrected the problem, the telemetry agent will be automatically rerun and Relativity access will be restored. Note that the Metrics Transmission Agent must be set to Active and the Relativity Agent Manager service must be running.