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 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 OnEndOfAlgorithm event handler.
Log("My log message"); self.Log("My log message")
Debug Messages
Debug statements are the same as log statements, but Debug 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.
Debug("My debug message"); self.Debug("My debug message")
Error Messages
Error statements are the same as log statements, but Error 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.
Error("My error message"); 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, the program continues executing until the end of the method definition. If you want to quit execution immediately, return after you call Quit.
Quit("My quit message"); self.Quit("My quit message")
Runtime Statistics
Runtime statistics show the performace of your algorithm at a single moment in time.
The following table describes the default runtime statistics:
| Statistic | Description |
|---|---|
| Capacity | The maximum amount of money an algorithm can trade before its performance degrades from market impact. |
| Equity | The total portfolio value if all of the holdings were sold at current market rates. |
| Fees | The total quantity of fees paid for all the transactions. |
| Holdings | The absolute sum of the items in the portfolio. |
| Net Profit | The dollar-value return across the entire trading period. |
| PSR | The probability that the estimated Sharpe ratio of an algorithm is greater than a benchmark (1). |
| Return | The rate of return across the entire trading period. |
| Unrealized | The amount of profit a portfolio would capture if it liquidated all open positions and paid the fees for transacting and crossing the spread. |
| Volume | The total value of assets traded for all of an algorithm's transactions. |
The capacity statistic is only available for live algorithms.
To add a custom runtime statistic, call the SetRuntimeStatistic method with a name and value. The value argument can be a string or a number.
SetRuntimeStatistic(name, value);
self.SetRuntimeStatistic(name, value)
Access Logs and Statistics
The following table describes where you can access the logs and runtime statistics, depending on how to deploy your algorithms:
| Location | Algorithm Lab Algorithms | CLI Cloud Algorithms | CLI Local Algorithms |
|---|---|---|---|
| Backtest results page |  | | |
| Live results page | | | |
| ReadBacktest | | | |
| ReadLive | | | |
| Local log file in your <projectName> / backtests / <timestamp> or <projectName> / live / <timestamp> directory | | |
You can also see our Videos. You can also get in touch with us via Discord.
Did you find this page helpful?
