book
Checkout our new book! Hands on AI Trading with Python, QuantConnect, and AWS Learn More arrow

Writing Algorithms

Logging

Introduction

Algorithms can record string messages ('log statements') to a file for analysis after a backtest is complete, or as a live algorithm is running. These records can assist in debugging logical flow errors in the project code. Consider adding them in the code block of an if statement to signify an error has been caught.

It's good practice to add logging statements to live algorithms so you can understand its behavior and keep records to compare against backtest results. If you don't add logging statements to a live algorithm and the algorithm doesn't trade as you expect, it's difficult to evaluate the underlying problem.

Log Messages

Log statements are added to the log file while your algorithm continues executing. Logging dataset information is not permitted. Use log method statements to debug your backtests and live trading algorithms.

If you execute algorithms in QuantConnect Cloud, log length is capped by organization tier. If your organization hits the daily limit, contact us.

If you log the same content multiple times, only the first instance is added to the log file. To bypass this rate-limit, add a timestamp to your log messages.

For live trading, the log files of each cloud project can store up to 100,000 lines for up to one year. If you log more than 100,000 lines or some lines become older than one year, we remove the oldest lines in the files so your project stays within the quota.

To record the algorithm state when the algorithm stops executing, add log statements to the on_end_of_algorithm event handler.

Select Language:
self.log("My log message")

Debug Messages

Debug statements are the same as log statements, but debug method statements are orange in the Cloud Terminal. Use these statements when you want to give more attention to a message in the Cloud Terminal. Debug messages can be up to 200 characters in length. If you send multiple debug statements within 1 second, your messages are rate-limited to avoid crashing your browser.

Select Language:
self.debug("My debug message")

Error Messages

Error statements are the same as log statements, but error method statements are displayed in red text in the Cloud Terminal. Use these statements when you want to give the most attention to a message in the Cloud Terminal. Error statements are rate-limited like debug statements.

Select Language:
self.error("My error message")

Quit Messages

Quit statements cause your project to stop running and may log some data to the log file and Cloud Terminal. These statements are orange in the Cloud Terminal. When you call the quit method method, the program continues executing until the end of the method definition. If you want to quit execution immediately, return after you call quit method.

Select Language:
self.quit("My quit message")

Get Logs

The following tables describe how to access the logs of your backtests and live algorithms:

Deployment TargetExecution ModeAccess Tools
QuantConnect CloudBacktest
QuantConnect CloudLive Trading
LocalBacktest
LocalLive Trading

Example

The following examples demonstrate some common practices for logging.

Example 1: On Events And Trading Logic

The following example trades a simple EMA cross trend-following strategy on SPY. We log or debug messages in event handlers and trading logic changes to get information on any event flow.

Select Language:
class LoggingAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        self.set_start_date(2024, 8, 12)
        self.set_end_date(2024, 9, 1)
        self.set_cash(1000000)

        # Request SPY data to trade.
        self.spy = self.add_equity("SPY").symbol
        # Create an EMA indicator to generate trade signals.
        self._ema = self.ema(self.spy, 20, Resolution.DAILY)

        # Warm up the algorithm for indicator readiness.
        self.set_warm_up(20, Resolution.DAILY)

    def on_warmup_finished(self) -> None:
        # Signals on warm-up finished.
        self.log("Warm up finished")

    def on_data(self, slice: Slice) -> None:
        bar = None if self.is_warming_up else slice.bars.get(self.spy)
        if bar:
            # Trend-following strategy using price and EMA.
            # If the price is above EMA, SPY is in an uptrend, and we buy it.
            if bar.close > self._ema.current.value and not self.portfolio[self.spy].is_long:
                self.debug("Trend changes to upwards")
                self.set_holdings(self.spy, 1)
            elif bar.close < self._ema.current.value and not self.portfolio[self.spy].is_short:
                self.debug("Trend changes to downwards")
                self.set_holdings(self.spy, -1)
    
    def on_order_event(self, order_event: OrderEvent) -> None:
        if order_event.status == OrderStatus.FILLED:
            # Log the order details if being filled.
            self.log(f"Order filled - Quantity: {order_event.quantity}")

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: