Product list and troubleshooting

This chapter is a “first aid manual” for simulating live trading: where the log is, which file to check first, and the order in which to troubleshoot common problems.

Dear user, Live will leave several types of fixed “output” on your disk. Treat them as four dedicated folders, and when problems arise, follow these folders to find the correct output; this is much more efficient than blindly searching through massive amounts of output.

0. 适用场景

You are already running in live mode and are experiencing issues such as submission failure, order rejection, abnormal status, or inconsistencies in orders in transit.
You want to locate the problem in a fixed order to reduce repeated restarts.
You need to verify the log path, rotation strategy, and whether broker_order_id is written back.

1. 核心概念：四键产物

Qteasy provides each Live account with four fixed key names for the path (the path is still valid even if the file does not exist). In the observability design of the Live subsystem, these four types of artifacts correspond to “how the system runs, transaction details, anomaly recovery, and risk control audit” respectively. When troubleshooting, please first determine which category the problem belongs to, and then open the corresponding file, rather than searching the entire log.

The meaning of each column: Key name: The dict key returned by list_live_trade_artifacts / CLI artifacts; What it is: The file type; When to open it: The typical trigger scenario.

How to use: Press :doc:3-risk-and-order-lifecycle to determine the order rejection type → check risk_log for risk control, check trade_log for transactions; check sys_log for startup/access control/trace.

Key name	What is it?	When should it be turned on?
`sys_log`	System operation log	Task scheduling, access control activation, trace, general error reporting
`trade_log`	Transaction Details CSV	Details of transactions, fees, and changes in positions
`break_point`	Resume file from breakpoint (key name is `break_point`)	How to restore Trader status after an abnormal exit?
`risk_log`	Risk control order rejection audit (*.risk.log)	Prioritize when risk control rejection is suspected**

Examples (API and CLI):

import qteasy as qt
arts = qt.list_live_trade_artifacts(account_id=1, data_source=qt.QT_DATA_SOURCE)
print(arts['sys_log'], arts['trade_log'], arts['break_point'], arts['risk_log'])
# 若 CLI 提示 risk 拒单，可单独打开：
print(arts['risk_log'])

You can also get the same four-key path by typing artifacts (alias ls-artifacts) in the Trader Shell.

Path Rules (Brief):

Relative paths are supported relative to the Qteasy root directory; absolute paths are also supported relative to the ~/... home directory.
The paths sys_log_file_path and trade_log_file_path can be modified at runtime using qt.configure(...) and will take effect immediately.

2. 日志轮换

Long-term live logging accumulates CSV and risk logs. Qteasy cleans up expired files by trade_log_keep_days (default 3 days).

API: qt.rotate_trade_logs(days=None)
**CLI: rotatelogs (alias rotate-logs), optional --days N

Cleanup scope (within the current transaction log directory):

trade_log_*.csv / trade_summary_*.csv / value_curve_*.csv
*.risk.log

Each time a new Python process imports qteasy, it will automatically rotate once; you can also manually execute the above command during operation and maintenance.

3. 建议排错顺序（决策树）

Please ask yourself the following questions in order, avoiding skipping steps:

Step 1 — Is there an English rejection reason displayed on the interface?

Yes, and it follows the risk control path (Step 3), similar to Order rejected by risk rule [...].
If you encounter errors such as Order submission failed, proceed to the submission/connection path (Step 4).
No obvious error message but incorrect behavior → Step 6

Step 2 — Open artifacts and confirm that the four paths are writable and that the file is growing.

Step 3 — Risk Control Rejection

Check risk_log andrule_id`
No new order line should appear (unlike counter rejections)

Step 4 — Counter Service / Connection

The broker status: is_connected indicates whether it is true (in the simulator, this means the adapter layer can handle the request).
Order table: Does it contain any orders with rejected entries and an empty broker number (order rejected at the counter)?

Step 5 — Inconsistent Transit Documents

In DEBUG mode: run --task diagnose_pending_orders
Or use Shell: reconcile to view the JSON.

Step 6 — Is the configuration as I expect?

liveconfig --detail checks the snapshot.

**Step 7 — Compare the trade_log with the order status sequence, and use the final status in the log as the standard.

4. 高频故障剧本

Each section follows the same sequence: Phenomenon → What to check first → Common causes → Next step.

A. Order rejected by risk control.

Issue: CLI rejection due to English error; submission result is empty {}
First check: risk_log containing ` Order table no new line
Common Reasons: Exceeding the single transaction limit, not being on the whitelist, outside of trading hours, etc.
Next Steps: Adjust rules or order parameters, and retest in the same scenario; see :doc:3-risk-and-order-lifecycle for details.

B. Submission failed (not due to risk control)

Issue: No valid submission record, or local verification error.
First check: broker status, cash/position adequacy, and sys_log error stack.
Common causes: Not connected, invalid field, insufficient resources
Next step: Retry after repairing the connection or field.

C. Counter handling of rejected orders

Impact: The order table has rows where status=rejected and broker_order_id is empty.
First check: trace, and the reason returned by the processing department.
Common Reason: The simulated brokerage firm’s rules do not accept this order (unrelated to risk control).
Next Step: Refer to the rejection list in the :doc:6-trader-snapshot-gate document, and do not confuse it with risk control.

D. Long-term partial-filled

Phenomenon: Orders are consistently only partially fulfilled.
First check: Cumulative trading volume vs. number of orders.
Common Reasons: The required returns have not yet been fully realized; or market conditions are causing slow transactions in batches.
Next Step: Determine whether the transaction feedback should be used to update the status to filled.

E. The post-market status is uncertain.

Issue: It’s unclear how to handle pending orders after the market closes.
First check: post_close related traces, reconcile JSON.
Next Step: Verify the cancellation order and final status.

F. broker_order_id / In-transit order exception

When the local order status, brokerage order number, or in-transit order list do not match, the phenomena are varied but can all be categorized into the following tables. This table is in the live 5-C observable category, consistent with the diagnostic fields of :doc:6-trader-snapshot-gate; the remote columns on the simulator are often empty, which is normal.

The meaning of each column: Phenomenon is the contradiction you observe; First Check is the primary source of evidence; Next Step is a suggested action (primarily a read-only diagnosis, not automatically modified).

How to use: Match the “phenomenon” line → Execute “Check First” → If still unclear, run --task diagnose_pending_orders in DEBUG.

Phenomenon	Check first	Next Step
Risk control rejects orders	`risk_log` contains no new order lines.	Adjusting rules
Counter rejection	Order rejected, broker empty.	trace / reason
Submitted but no broker ID	Acceptance ACK and Write-back	:doc:`4-broker-adapter-and-integration`
Inconsistency between local and remote transit	DEBUG: `run --task diagnose_pending_orders`	Read-only diagnostics; simulator remote end is often empty.

CLI helpers: reconcile, gate.

G. Inconsistency between the interface and the logs

Issue: The CLI prompts and subsequent log checks seem contradictory.
First check: Align all records of the same order ID in time sequence.
Next step: Conduct a post-mortem analysis based on the final state of the log.

5. 运维建议

Regularly check the transaction log directory usage; if necessary, use rotatelogs --days N.
Save the output of liveconfig --detail on critical runtime days as a screenshot or text.
Long-distance running or pre-release reference: doc:7-manual-smoke-live-grid-roadmap

6. 快速检查清单

Account correct
Configuration takes effect (liveconfig)
Does the risk control system reject the application (risk_log)?
Can the brokerage firm handle this (broker status)?
Should broker_order_id be written back upon successful processing?
Four-key paths are readable (artifacts)

7. 常用英文提示与中文含义

Order rejected by risk rule [MAX_ORDER_QTY]: order quantity exceeds limit

Meaning: Local risk control rule MAX_ORDER_QTY rejected – quantity exceeded limit. Check risk_log; it wasn’t a brokerage firm rejecting the order.

<RISK REJECTED> rule_id='MAX_ORDER_QTY' reason='...' symbol='000001.SZ' ...

Meaning: Same as above, structured risk control log lines, making them easy to search.

Order submission failed.

Meaning: The submission process failed (not a counter rejection after risk control approval). Check the connection and sys_log.

[NOT_IMPLEMENTED] sync_from_broker is reserved for QMT broker integration (S2.1-b).

Meaning: The sync command has not yet achieved actual remote synchronization. This is an expected message and not a runtime failure.

8. 相关跳转

Startup and Configuration: :doc:2-configuration-and-run
Lifecycle: :doc:3-risk-and-order-lifecycle
Snapshot/Access Control/Order Rejection: :doc:6-trader-snapshot-gate
Manual smoke: :doc:7-manual-smoke-live-grid-roadmap
CLI Reference: :doc:8-cli-trader-capability-matrix
Broker: :doc:4-broker-adapter-and-integration
Practical tutorial: tutorials/8-live-trade-risk-and-broker-walkthrough.md