Yarra LogServer

Yarra LogServer acts as a central monitoring hub for every RDS and ORT client. RDS clients can be configured to report every sequence run on the scanner, enabling reporting and analytics on near-real-time data.

Capabilities

  • Log every sequence on RDS-enabled scanners
  • Parse sequences into discrete exams (by patient name)
  • Parse “Epic-formatted” patient names
  • Catalogue scanners, monitor RDS and scanner health
  • Tag exams with body region information
  • Monitor the ORT clients and other Yarra components

Limitations

  • Only reports patient name, sequence name, begin time, end time of sequence (as reported by the scanner), and scan data file size.
  • Exams can only be “tagged” by running a sequence with the tag information
  • Does not provide comprehensive analysis of the gathered data

Installation

Yarra LogServer is tested and developed under Ubuntu 16.04. It is therefore most likely to work when running on a server on this version of Ubuntu.

YLS is not designed to be made available to the internet at large, and should not be made available outside your internal network. The system uses common-sense security measures to protect patient data, but was not designed to withstand a determined attack across the public internet.

Installation is simple. First, download the most recent yarralogserver package. Install it like this:

All the main drudge work should be done for you by the installation script. It creates a yarra system user, installs two services (YarraLogServer and YarraLogViewer, the latter provides a web administration interface and simple search mechanism).

To verify that it has been installed correctly, visit https://localhost:4444  to open the web interface. You will probably have to click through a scary security warning about the self-signed certificate that the server is using (the server will not respond to unencrypted http requests)

If the login page does not appear, check the health of the yarralogviewer process. Any number of things might have broken it here. If it looks like it’s something we broke, please get in touch.

The next thing to check is the health of the LogServer service. This is the process that accepts and stores the sequence info coming from the RDS clients. Navigate to https://localhost:4443/test, which should give you an empty page, but not error. This verifies that the LogServer is running and accepting connections.

Server Configuration

Web Interface Initial User

To begin with, you won’t have any users set up on the web interface. Click the “register” link and provide your email and set a password. It will send you an email with a link to verify your email address. This email is liable to be eaten by email providers such as gmail, but we find it works just fine in internal email systems. You can skip verifying your own email address by running this command:

Your email address may be verified, but your account isn’t active yet and there are no admin accounts yet that could activate it. The easiest way to activate it is to run this at the command line:

YarraLogServer configuration files (and resources) are  all stored in /opt/yarralogserver/ . The important config files are YarraLogServer.ini  and wthttpd . Depending on your setup, you will want to edit one or both of them.

API Key

You will want to pick an API key. This key needs to be set on all the RDS clients. This is a basic tool to only let RDS clients send information to the database. Set this in the [Server]  section of YarraLogServer.ini.

Ports

By default, LogServer runs under port 4444 and LogViewer under 4443. This can be changed in   YarraLogServer.ini.

Database Connection

YarraLogServer.ini defines two database connection strings, one for the LogServer and one for the LogViewer. They do not need to be changed, but if you want to host the database on another server, this is the place to tell YarraLogServer about it. Make sure they’re both connecting to the same server, though.

SSL Certificate

By default, the installer creates a self-signed certificate that is valid for localhost and places it in /opt/yarralogserver/cert/. This is actually sufficient to get the system working, but you may want to generate a new one to match an internal domain or use one signed by a real CA. You can set the paths to find your cert and the private key in wthttpd . The server will fail to start unless the private key is owned by yarra with 0600 permissions.

RDS Configuration

First, you will need to update RDS to the newest version on each client. You can do this on one client at a time, so it’s best to do it on one client first to test everything is working.

If you are using a self-signed certificate for the server, you will need to install the public certificate on the client so it will trust the server. Place it in the same directory as RDS.exe and rename it logserver.crt.

RDS’s configuration interface has a new tab, “Log Server”, where you can set the LogServer’s address and the API key you chose earlier. The “Push Frequency” specifies how often RDS pushes the sequence data to the server.

LogViewer Administration

Accounts

Anyone can register an account, but accounts are disabled by default. An administrator can enable an account from the users section of the Admin page, and can promote accounts to admin status.

The Data Model

It is probably important here to explain something about the data model. An individual sequence run on a scanner (ex: AX T1 POST) is called a scan. Multiple sequences run on a patient in a row is an exam. An exam is associated with protocol if a protocol tagging scan has been run. An event is a piece of information sent from an RDS client, such as “Boot”, “Shutdown” and “RawDataStorage.” A scanner corresponds to the actual scanner.

Scanners

On the Scanners page, you can see a list of every scanner that has sent information to the LogServer. The Serial is filled in for you, but you should assign each one a human-readable name. You can also set fields such as Unit, Field Strength, Address and Phone Number that relate to the scanner itself. To edit a field, double click the table cell, make your changes, and press enter.

The Openings page lets you define opening hours for each scanner per day of week. This can be useful when calculating, for instance, how much of the working day is spent running sequences.

Protocols

The Protocols page allows you to edit the Section, Region, Bodypart and Variant for each protocol that the LogServer has seen so far. It is designed so that you can catch typos and fix them without editing the actual sequence. For instance, if an exam is tagged NUERO_HEAD_BRAIN_SEIZURE  you can edit the associated section to “Neuro” and the exams tagged with the typoed section name will now be associated with the correct one. You could then update the tag on the scanner when you get a chance.

Scanner Setup

Epic Patient Names

Our workflow uses patient names that come out of Epic’s database system. Yarra LogServer special-cases names that appear to be in the format:

The last digits are the patient’s birthday and are parsed and stored separately. This is not required.

 Tagged Exams

Because Yarra LogServer only gets access to the sequence names, it doesn’t have an information about the protocol or any information about what kind of scan is being run. It is often important to be able to differentiate between different protocols.

To enable this, we have developed a “dummy” sequence that exists entirely to provide protocol information to the Yarra LogServer. The naming scheme for this sequence looks like

For instance, you might code a brain scan for seizures like:

Tags are designed to be “addons” to specify attributes of an exam, and can be anything you find useful to track that doesn’t fit the section/region/etc schema.

Long Patient Names

Long patient names combined with long sequence names can cause RDS to be confused in rare cases. It’s important to make sure that for every patient examined, there is at least one sequence run with fewer than 31 characters in its name. Usually this would be an adjustment scan or a scout scan.

Simple Dashboards with Redash

To get you up and running quickly, we have built some dashboards with Redash, an open-source data visualization tool. Our dashboards are tested to work on Redash version 2.0.1.b3080, so it is best to first install our dashboards with this version of Redash and then upgrade Redash to the newest version.

These instructions assume you are running Redash on the same machine as YarraLogServer, and will not work with an existing Redash installation.

To get started, first install Redash 2.0.1.b3080. It might be prudent to run the provisioning script that was released with v2.0.1 rather than the one on the master branch.

Invoke the provisioning script like this:

and create your administrator account. To insert our dashboards, run:

It will prompt you for a password for a database role that Redash will use to query the YarraLog database.

Verify that it has worked by logging into your Redash instance at localhost, navigating to the “Dashboards” page, and loading a dashboard. There may be no data but there should at least be no error messages.

Now, you should upgrade to the latest Redash by following the official upgrade instructions.

Download and Source Code

License Information

The Yarra framework is provided free of charge for use in research applications. It must not be used for diagnostic applications. The author takes no responsibility of any kind for the accuracy or integrity of the created data sets. No data created using the framework should be used to make diagnostic decisions. The source code is provided under the GNU General Public License (GPL).

The Yarra framework, including all of its software components, comes without any warranties. Operation of the software is solely on the user’s own risk. The author takes no responsibility for damage or misfunction of any kind caused by the software, including permanent damages to MR systems, temporary unavailability of MR systems, and loss or corruption of research or patient data. This applies to all software components included in the Yarra software package.

Binary Package

Yarra LogServer 0.8

Source Code Access

YLS Page on Bitbucket