How to Access and Use OpenAPS Log Files for Troubleshooting and Optimization

OpenAPS (Open Artificial Pancreas System) is a community-driven, open-source artificial pancreas system that automates insulin delivery for people with diabetes. The system runs on small computers like Raspberry Pi or Intel Edison, processing continuous glucose monitor (CGM) data and controlling an insulin pump in real time. While OpenAPS is designed to operate reliably, no system is perfect. Log files are the primary diagnostic tool for understanding what the system is doing, why it made a particular decision, and where things might have gone wrong. Mastering log files is essential for safe operation, effective troubleshooting, and long-term optimization of your setup.

This guide provides a deep, practical look at OpenAPS logs: how to access them, what each section means, how to use them for debugging common issues, and how to leverage log data to fine-tune your system for better glucose outcomes. Whether you are a new user setting up your first rig or an experienced builder looking to squeeze out better performance, understanding logs is a skill that will serve you well.

Accessing OpenAPS Log Files

Before you can analyze logs, you need to get to them. OpenAPS stores log files on the device running the system, typically a Raspberry Pi running Raspbian or a similar Linux-based operating system. Access requires connecting to that device, either locally or over the network.

SSH: The Primary Remote Access Method

Secure Shell (SSH) is the most common and practical way to access OpenAPS logs. With SSH enabled on your rig, you can connect from any computer on the same network using a terminal client. On Windows, popular clients include PuTTY and the Windows Terminal; on macOS and Linux, the built-in ssh command works directly. Once connected with your rig's IP address and credentials, you have full command-line access to browse, view, and transfer log files.

Direct Console Access

If your rig is physically accessible and SSH is not available or not working, you can connect a monitor and keyboard directly to the device. This method is useful for initial setup or when network issues prevent remote access. The same log files are available from the console, and you can use standard Linux commands to navigate and read them.

Transferring Logs with SCP and SFTP

For detailed analysis on a desktop computer, you can copy log files using SCP (Secure Copy) or SFTP (SSH File Transfer Protocol). These tools allow you to download entire log directories or specific files to your local machine. For example, the command scp [email protected]:/var/log/openaps/openaps.log ./ copies the main log file to your current directory. SFTP clients like FileZilla provide a graphical interface for drag-and-drop transfers, which can be more convenient for users who prefer not to use the command line.

Log File Locations and Directory Structure

By default, OpenAPS stores log files in the /var/log/openaps/ directory. The primary log file is openaps.log, which records the main system events, sensor readings, insulin dosing decisions, and errors. In addition, you may find subdirectories or additional log files for specific components:

  • /var/log/openaps/openaps.log – The main system log, containing all core events.
  • /var/log/openaps/oref0.log – Logs from the oref0 algorithm, which handles the decision-making logic.
  • /var/log/openaps/pump.log – Pump-specific communication logs, including commands sent and responses received.
  • /var/log/openaps/cgm.log – Raw CGM data and calibration events.
  • /var/log/openaps/autosens.log – Logs from the autosensitivity detection module, which adjusts basal rates based on observed patterns.

Some setups may also rotate logs automatically, creating compressed archives like openaps.log.1.gz. These contain older entries and can be decompressed with gunzip for review. Understanding the directory layout helps you go directly to the source of a specific issue rather than searching through a single monolithic file.

Understanding the Structure of OpenAPS Logs

OpenAPS log files are plain text files with timestamped entries. Each line typically starts with a date and time in ISO 8601 format, followed by a severity level (INFO, WARN, ERROR, DEBUG), and then a detailed message describing the event. The level of detail depends on the configured logging verbosity, which can be adjusted in the system settings.

Timestamps and Time Zones

Every log entry includes a precise timestamp. It is critical that your rig's clock is accurate and set to the correct time zone. Inconsistent time stamps can make it difficult to correlate log events with actual glucose trends or user actions. Network Time Protocol (NTP) should be enabled to keep the clock synchronized automatically. When reviewing logs, always note the time zone used, especially if you are comparing log data with CGM data from a phone or other device that may use a different time zone.

Severity Levels and What They Mean

  • INFO: Normal operational messages. These record sensor readings, insulin doses, and routine algorithm decisions. INFO messages are the most common and help you understand what the system is doing at any given time.
  • WARN: Warnings indicate potential issues that did not cause a failure but may need attention. Examples include a sensor reading that is slightly outside expected range, a pump communication that required a retry, or a calibration that was skipped due to insufficient data.
  • ERROR: Errors represent failures that prevented the system from completing an action. Common errors include pump communication failures, sensor disconnections, or algorithm timeouts. Errors should be investigated promptly, as they can lead to missed insulin doses or incorrect dosing decisions.
  • DEBUG: Debug messages are highly detailed and are typically only enabled when troubleshooting a specific issue. They can produce a large volume of data and may contain low-level details that are not needed for routine review.

Log Rotation and Retention

To prevent log files from consuming all available disk space, OpenAPS typically implements log rotation. Older log files are compressed and eventually deleted after a configurable number of rotations. By default, logs may be kept for 7 to 30 days, depending on the configuration. If you need to retain logs for longer periods for trend analysis or auditing, you can adjust the rotation settings in the /etc/logrotate.d/openaps configuration file or implement a custom backup script to archive logs to external storage.

Interpreting Key Log Events

Knowing what to look for in logs turns raw data into actionable insights. Here are the most important event types and how to interpret them.

Sensor Data and Calibrations

CGM readings are the foundation of OpenAPS decision-making. Log entries for sensor data include the glucose value, the time it was recorded, and any calibration information. A typical entry looks like: INFO: Received CGM reading 142 mg/dL at 14:32:05. Calibration events are also logged, showing when a fingerstick value was entered and how the system adjusted its sensor readings accordingly. Look for patterns of frequent calibrations or entries where the system rejects a calibration because the values are too far apart. These can indicate sensor drift or calibration errors.

Insulin Delivery Events

Every insulin dose is logged, including boluses, temporary basal rates, and scheduled basal delivery. Entries include the type of delivery, the amount in units, and the duration for temporary rates. For example: INFO: Temp basal set at 1.2 U/hr for 30 minutes or INFO: Bolus delivered 0.5 U at 18:15:22. By cross-referencing these entries with glucose trends, you can evaluate whether the system is responding appropriately to highs and lows. Unexpectedly large doses or missed deliveries are easily spotted in the log sequence.

Algorithm Decisions

The oref0 algorithm makes decisions about basal adjustments, bolus recommendations, and high/low alerts based on current and predicted glucose levels. These decisions are logged with explanatory text that reveals the reasoning behind each action. For instance: INFO: Predicted BG in 30 minutes: 160 mg/dL – increasing basal to 1.5 U/hr. Reading these entries helps you understand whether the system's predictions align with actual outcomes. Persistent discrepancies may indicate that the model parameters need adjustment.

Error and Warning Messages

Errors and warnings are the most actionable entries for troubleshooting. Pump communication errors are among the most common, often appearing as: ERROR: Pump comms failed – retry 3/5 or WARN: Pump response timeout. These can be caused by radio interference, low pump battery, or physical distance between the rig and the pump. Sensor errors, such as ERROR: Sensor data stale – no reading for 10 minutes, indicate a loss of CGM connection that can lead to missed data and potentially incorrect dosing. All errors should be investigated and resolved before relying on the system for automated insulin delivery.

Troubleshooting with Log Files

Log files are the primary tool for diagnosing problems in an OpenAPS system. A systematic approach to log analysis can quickly identify the root cause of most common issues.

Step-by-Step Troubleshooting Process

  1. Identify the time frame of the issue. If you noticed a problem at a specific time, start by pulling log entries from around that period. Use grep with a timestamp pattern to narrow the search.
  2. Search for ERROR and WARN entries. Use grep -E 'ERROR|WARN' openaps.log to extract all warnings and errors. These are the most likely indicators of a problem.
  3. Check for missing data. Look for gaps in sensor readings or insulin deliveries. A gap of more than 5-10 minutes in sensor data, or a missing hourly log entry for pump status, can signal a communication failure.
  4. Correlate with CGM and pump history. Compare log entries with the actual CGM trace and pump history from your insulin pump. Discrepancies between what the log reports and what the pump shows can indicate a log that is out of sync, or a command that was sent but not executed.
  5. Review algorithm decisions. For issues with glucose control, examine the algorithm's predictions and the resulting insulin adjustments. Look for patterns where the system consistently overcorrects or undercorrects.
  6. Check for configuration errors. Errors that occur immediately after a configuration change are often caused by incorrect settings in the preferences or pump profile. Review the log around the time of the change to see if a specific parameter triggered the issue.

Common Issues and Their Log Signatures

Missed insulin doses: Look for sequences where a bolus or temp basal was requested but never confirmed. The log may show INFO: Bolus requested 0.5 U followed by ERROR: Pump comms failed without a subsequent confirmation entry. In such cases, the dose was not delivered, and the system may not retry automatically. You should verify the pump history and manually deliver the missed dose if necessary.

Sensor data gaps: If the CGM stops transmitting, the log will show WARN: No sensor data for 10 minutes followed by escalating severity as the gap lengthens. This can be caused by a dead sensor, a disconnected transmitter, or radio interference. Check the sensor and transmitter status, and replace the sensor if needed.

Pump communication failures: Repeated ERROR: Pump comms failed entries suggest a physical or radio issue. Move the rig closer to the pump, replace pump batteries, or check for sources of interference like other wireless devices. The log will show the number of retry attempts, and if all retries fail, the system may enter a safety mode.

Autosens overrides: If you notice the system delivering more or less insulin than expected, check the autosensitivity logs. An INFO: Autosens ratio: 1.2 indicates that the system has detected a pattern of higher sensitivity and is adjusting basal rates accordingly. If the ratio seems extreme or does not match your observations, you may need to adjust the autosens settings or provide more consistent data.

Optimizing Your OpenAPS System Using Log Data

Beyond troubleshooting, log files provide the historical data needed to fine-tune your system for better glucose control. By reviewing logs regularly, you can identify patterns and make informed adjustments.

Fine-Tuning Basal Rates and Bolus Profiles

Comparing expected versus actual glucose outcomes after meals and overnight can reveal whether your basal rates and bolus profiles need adjustment. If you see a pattern of highs after meals, check the log to see whether the system's bolus recommendations matched what was actually delivered. Look for entries like INFO: Meal bolus recommended 3.0 U and then verify that the pump delivered that amount. If the system consistently recommends more insulin than what is delivered, your pump settings may need updating. Similarly, overnight basal rates can be refined by examining the log for periods of stable glucose and noting the basal rate in effect. Over time, you can build a more accurate profile that reduces the need for automated corrections.

Calibration Optimization

Frequent or erratic calibrations can degrade system performance. Review log entries for calibration events and note the values and timestamps. If you see calibrations that are rejected or that cause large sensor adjustments, consider calibrating at more stable times, such as when glucose is not rising or falling rapidly. The log can help you identify the best times to calibrate for your specific sensor and body chemistry. Also, look for patterns of drift in sensor readings. If the sensor consistently reads low or high compared to fingersticks, you may need to adjust the calibration curve or replace the sensor.

Adjusting Alert Thresholds

OpenAPS allows you to configure alerts for high and low glucose, missed data, and system errors. By reviewing logs, you can see how often these alerts would have been triggered and whether the thresholds are set appropriately. If you are receiving too many false alarms, the log can help you identify the conditions that trigger them, allowing you to adjust thresholds to reduce noise without compromising safety. For example, if the log shows frequent WARN: Predicted low in 20 minutes alerts that do not materialize, you may want to adjust the prediction horizon or threshold value.

Long-Term Performance Analysis

Archiving logs over weeks or months enables long-term trend analysis. You can track metrics such as time-in-range, average glucose, insulin sensitivity changes, and system reliability. Tools like logwatch or custom Python scripts can parse log files and generate summary reports. By comparing logs across seasons or lifestyle changes, you can see how your system adapts and make proactive adjustments before issues arise. This is especially valuable for identifying gradual changes in insulin sensitivity that might otherwise go unnoticed until they cause a problem.

Automating Log Analysis and Monitoring

Manually reading log files every day is not practical. Fortunately, there are several ways to automate log monitoring and alerting.

Setting Up Logwatch or Similar Tools

Logwatch is a log analysis tool that can be configured to run daily and email a summary of important events. By creating a custom Logwatch filter for OpenAPS logs, you can receive a daily report of warnings, errors, and notable events. This allows you to stay informed without manually scrolling through hundreds of lines of log entries. The report can highlight issues that need attention, such as repeated communication errors or sensor gaps, and provide peace of mind that the system is running normally.

Creating Custom Bash or Python Scripts

For more detailed analysis, you can write scripts that parse log files and generate graphs or statistics. For example, a Python script using matplotlib can plot insulin delivery over time alongside CGM readings, making it easy to visually correlate events. Scripts can also calculate metrics like percentage of time spent in a target glucose range, average number of errors per day, or the frequency of autosens adjustments. By running these scripts periodically and storing the output, you build a historical record that helps track system performance and changes over time.

Setting Up Real-Time Alerts

For critical events, real-time alerts can be sent via email, SMS, or messaging platforms like Telegram or Slack. A simple script that monitors the log file for new ERROR or WARN entries can trigger a notification when a problem occurs. For example, you can use tail -f openaps.log | grep --line-buffered 'ERROR' to pipe new errors into a notification script. This ensures that you are aware of issues as soon as they happen, rather than discovering them later during a log review. Real-time alerts are especially valuable for issues that require immediate action, such as a pump communication failure that could lead to missed insulin delivery.

Security and Privacy Considerations

Log files contain highly sensitive personal health information, including glucose readings, insulin doses, timestamps, and sometimes location data if the rig has GPS logging enabled. Protecting this data is essential for both legal and personal reasons.

Encrypting Logs at Rest and in Transit

When log files are stored on the rig, they should be protected by the device's overall security, including strong passwords and encrypted file systems. When transferring logs via SCP or SFTP, the data is encrypted in transit, which is good practice. Avoid transferring logs over unencrypted protocols like FTP or HTTP. If you archive logs to a cloud service or external drive, consider encrypting the archive with a tool like gpg or using an encrypted zip file.

Limiting Access to Log Files

Only grant access to log files to people who need it, such as the system user and any trusted caregivers. Avoid sharing raw log files with others, including on public forums, unless you have removed or anonymized all personally identifying information. If you need to share log excerpts for troubleshooting help, carefully review the content and remove any data that could identify you, such as your name, exact location, or pump serial numbers.

Retention and Disposal Policies

Establish a clear policy for how long you keep log files and how they are disposed of when no longer needed. While long-term logs are valuable for trend analysis, they also represent a privacy risk if the device is lost or stolen. Regularly purge old logs that are no longer needed, and ensure that when you decommission a rig, the log files are securely wiped. Using full-disk encryption on the rig can protect data in case of theft.

Conclusion

OpenAPS log files are more than just a record of events; they are a window into the inner workings of your automated insulin delivery system. By learning how to access, read, and analyze these logs, you gain the ability to diagnose problems, optimize performance, and ultimately achieve better glucose control. The skills and techniques described in this guide will help you move from reactive troubleshooting to proactive system management, ensuring that your OpenAPS rig operates safely, reliably, and effectively. Make log review a regular part of your routine, and over time, you will develop an intuitive understanding of how your system behaves and how to keep it performing at its best.