Administrators are often tasked with troubleshooting issues in their institution’s Blackboard Learn environment. To help you get a full picture of what’s happening during a troublesome issue, Blackboard Learn generates logs for you to reference. These logs are saved to your institution’s local file storage for quick reference and reliable storage. You can download the files as needed or use file permissions to share with others.

Access logs

You can find system logs in the Content Collection. From the Administrator Panel, select Manage Content in the Content Management section. Select internal > logs. Logs are stored in a folder structure by year, month, day, and hour. Navigate through the folder tree to find the exact log you’re seeking.

Log transfer and retention

The hour folder uses the Universal Time Coordinated (UTC) hour. Logs are transferred to the local file system once per hour, but on a four-hour delay. For example, if the current hour is 4 then during this hour logs from hour 0 will be transferred.

Logs are stored in your institution's local file storage, so you're able to determine and apply your own retention policies for logs.

Log format

Logs contain one hour of log data per Blackboard Learn node and are stored in a compressed format. If three nodes run in an hour, you will see three files.

The logs are compressed using gzip. You can decompress these files with tools such as 7Zip for Windows or unzip for Mac or Linux. When decompressed, the result is a text file containing log events stored in JSON objects. Each JSON object starts and ends with a curly brace and has the following fields:

  • path, which shows the file on the Blackboard Learn server where the event originated
  • @timestamp, the time the event occurred
  • clientId
  • version
  • host, the IP address for the Blackboard Learn node where the event originated
  • message, the information Blackboard Learn included in the log file about the event

Format logs to be more readable

Log files are stored as JSON files, which can be difficult to read if you’re unfamiliar with the format. You can reformat the file to make it more readable.

Before you start, download and install Python 3. If you are using a Mac or Linux computer, you may already have Python 3 installed.

To check what version of Python you may have installed, open the Terminal and run the command python --version. If you receive an error, or an earlier version of python is installed, try python3 --version.

If python or python3 works, use it in the commands below.

To begin, download the convertLogs.py script using the link below. The attachment is a plain text file. To use it as a Python script, edit the file extension to use .py after you download it to your computer. Make note of where the script is saved, for example, ~/Downloads/scripts. You'll need to know the path when you execute the script in the steps below.

If you're using Windows, use the Powershell terminal in the steps below.

To download and convert one hour of logs:

  1. Log into Blackboard Learn as an administrator.
  2. Go to Administrator Panel > Manage Content.
  3. Find the log folder you want to download. For example, /internal/logs/2019/03/03/12.
  4. Download a log file from one of the hour folders.
  5. In the terminal window, execute the script. Run python ~/Downloads/scripts/convertLogs.py -f ~/Downloads/Logs -o ~/LearnLogs.
    • The –f parameter must be a folder path. This is where the unformatted logs are currently saved.
    • The –o parameter must be an empty folder. This is where the formatted logs will be saved. The script will create the folder if it doesn't exist.

To download and convert multiple hours of logs:

  1. Log into Blackboard Learn as an administrator.
  2. Go to Administrator Panel > Manage Content.
  3. Find the log folder you want to download. For example, /internal/logs/2019/03/03/12.
  4. Select the hours you want to download I.e. 11, 12, 13.
  5. Select Download Package and save it to a local folder. This will create a zip file with logs.
  6. Extract the zip file using your computer's built-in decompressing program. For Windows. right-click on the zip file and choose Extract All.
  7. In the terminal window, execute the script. Run python ~/Downloads/scripts/convertLogs.py -f ~/Downloads/Logs -o ~/LearnLogs.
    • The –f parameter must be a folder path. This is where the unformatted logs are currently saved.
    • The –o parameter must be an empty folder. This is where the formatted logs will be saved. The script will create the folder if it doesn't exist.