tick-collection-ops

MT5 ティック収集の運用

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターが変化している、または回避策が必要になった場合は、先送りせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

⚠️ ホストの変更 — 2026-08-07

MetaTrader 5 は現在、 では動作しません。 現在はデモ口座を使用し、ブローカーの VPS（Tailscale ホスト mt5-host、<tailscale-ip>、Windows）のみで動作しています。Mac ローカルの Wine テスト環境は 2026-08-06 に削除されました。 の Wine ターミナルと、その xvfb／xfce／x11vnc デスクトップおよび fxview-sidecar は廃止中です。

VPS の構成は Linux の systemd ではなく、Windows のスケジュールされたタスクです：

項目	（廃止済み）	ブローカー VPS（現行）
ターミナル	Wine 上の mt5.service、DISPLAY=:99	terminal64.exe、ネイティブ Windows、実セッション
ティックリング	/dev/shm/tick_ring_<SYM>	C:\odb-tickrings\tick_ring_<SYM>
リング → バス	—	odb-tapegateway.exe → タスク OdbTickRingToNatsTapeGateway
バス	—	nats-server.exe :4222 → タスク OdbTapeBusNatsJetStreamServer
注文	—	order-service :50060 → タスク ODB-MT5-OrderService
シンボル	EUR/GBP/XAU/XAG	EUR/GBP/XAU のみ（2026-05-26 の指示により銀は対象外）
サービス制御	systemctl	Get-ScheduledTask / Start-ScheduledTask

ssh <mt5-host> で接続します。PowerShell を SSH 経由で実行すると、シェルのクォート処理によって $_ が失われます。コマンドは powershell -NoProfile -EncodedCommand <base64-utf16le> を使って Base64 エンコードして渡してください。

以下の内容はすべて、引き続き Linux／Wine 環境でのデプロイについて説明しています。 EA、tick_writer.dll のリング形式、ギャップ検出の考え方に変更はなく、現在も正式な情報であるため、残されています。変更されたのはホストとサービスマネージャーのみです。新しい Linux MT5 環境の構築には使用しないでください。

正式な参照先：<research-repo>/docs/adr/<date>-retire-<host>-as-a-metatrader-host.md および docs/decision-register-<topic>.md。

Wine 経由で Linux 上で動作するゼロギャップのティック収集システムを運用、監視し、トラブルシューティングします。

このスキルを使用する場面

以下の場合にこのスキルを使用します。

• でティック収集をデプロイまたは再起動する
• ティックのギャップやデータ欠損を診断する
• Wine または MT5 の問題をトラブルシューティングする
• systemd サービスの構成を把握する
• クラッシュリカバリーファイルを調査する
• ティック収集の状態を確認する

システムアーキテクチャ

TickCollector EA (MQL5)  -->  tick_writer.dll (Rust)  -->  Parquet files
     OnTick() callback         C-ABI FFI                   ZSTD compressed
     CopyTicksRange()          Buffered writes              One file per day
     Watermark dedup            Row group flush

• TickCollector EA は、ヘッドレス Linux（）上で Wine 経由で MT5 上で動作します
• EA は OnTick() コールバックと OnTimer() のフォールバック（1 秒間隔）を使って、すべてのティックを取得します
• ティックは EA 内でバッファリングされ、C-ABI FFI を介して Rust DLL（tick_writer.dll）にフラッシュされます
• Rust DLL は ZSTD レベル 3 の圧縮で Parquet ファイルを書き込みます
• チャートごとにシンボルごとの EA インスタンスを 1 つ実行します — これは極めて重要な制約です（EA が扱うシンボルは 1 つのみ）

本番環境の構成

リソース	パス
Git リポジトリ	~/eon/mql5/
Wine プレフィックス	~/.mt5/
MT5 のインストール先	~/.mt5/drive_c/Program Files/MetaTrader 5/
EA のソース	{repo}/mql5_ea/TickCollector.mq5
DLL（Windows）	{mt5}/MQL5/Libraries/tick_writer.dll
ティックデータ	{mt5}/tick_data/（ODB キャッシュへのシンボリックリンク）
systemd ユニット	systemd ユーザーユニット：xvfb、xfce、x11vnc、mt5

Systemd サービスチェーン

xvfb (virtual framebuffer)
  --> xfce (desktop environment)
    --> x11vnc (VNC access)
      --> mt5 (MetaTrader 5 via Wine)

すべてユーザーレベルの systemd ユニットです。MT5 はディスプレイスタックに依存します。チェーンは順番に起動する必要があります。最初に xvfb、最後に mt5 を起動します。

日次ファイルローテーション

• 取引日ごとに新しい Parquet ファイルが作成されます
• ファイル名のパターン：{SYMBOL}_{YYYYMMDD}.parquet
• EA は日付の変化を検知し、tw_close（現在のファイルを確定）と tw_init（新しいファイルを開く）を呼び出します
• 取引日は日曜日の市場オープンから月曜日の市場オープンまでです（外国為替市場の取引時間）

クラッシュからの復旧

EA の再起動時：

1. EA は tw_get_last_time_msc を呼び出し、最後の Parquet ファイルのフッターから再開時のウォーターマークを読み取ります
2. ウォーターマークは最後に書き込まれたティックのタイムスタンプです。そこから再開します
3. 今日の日付のファイルがすでに存在する場合、新しいファイルには _1、_2 のサフィックスが付きます（上書きはしません）
4. すべての復旧セグメントは、フッターを含む有効な完全な Parquet ファイルです
5. 再開時のウォーターマークによって、再起動後のティックの重複を防ぎます
6. シャットダウンから再起動までのギャップは、ウォーターマークを起点に CopyTicksRange でバックフィルされます

Rust DLL は、破損または不完全なファイルを復旧しようとせず、_partial サフィックスを付けて名前を変更します。

ギャップの検出

DuckDB を使用して、連続するティック間のギャップを確認します。

WITH ticks AS (
    SELECT time_msc,
           lead(time_msc) OVER (ORDER BY time_msc) - time_msc AS gap_ms
    FROM read_parquet('{base_path}/FXVIEW_{SYMBOL}/{YYYY}/{SYMBOL}_{YYYYMMDD}.parquet')
)
SELECT time_msc, gap_ms,
       make_timestamp(time_msc * 1000) AS ts
FROM ticks
WHERE gap_ms > 60000  -- gaps > 1 minute
ORDER BY gap_ms DESC;

結果の解釈：

• 週末のギャップは正常です（金曜日の市場クローズから日曜日の市場オープンまで）
• 取引時間中のギャップは、収集の中断を示しています
• 1 分未満のギャップは、取引が少ない時間帯には正常です
• 関連する再起動イベントがないか、systemd ジャーナルを確認してください

Wine に関する注意点

以下は重大なアンチパターンです。違反すると、警告なしにクラッシュしたりデータが失われたりします。

• MQL5 で %I64u または %I64d の書式指定子を絶対に使用しないでください。Wine が警告なしにクラッシュします。代わりに IntegerToString() を使用してください。
• Wine はファイルアクセス時にシンボリックリンクをたどれません。EA と DLL の配置には物理ファイルのコピーを使用してください
• ヘッドレス Linux では Xvfb 仮想フレームバッファーが必要です。モニターが接続されていなくても、MT5 GUI にはディスプレイが必要です
• compile.sh はコンパイルに Wine CLI を使用します。MetaEditor GUI は不要です
• Wine 上では、コンパイルが成功しても MetaEditor は終了コード 1 を返します。代わりにコンパイルログを確認してください
• コンパイルログは UTF-16LE です。読み取るには iconv -f UTF-16LE -t UTF-8 を使用してください
• DISPLAY=:99 を設定する必要があります（Xvfb の仮想ディスプレイ番号）

デプロイパイプライン

デプロイ全体には /mql5:mql5-ship スラッシュコマンドを使用します。

• EA ソースの変更には --ea-only
• Rust DLL の変更には --dll-only
• パイプライン全体：commit -> push -> で pull -> compile -> validate

詳細なデプロイ手順（SSH コマンド、ファイルのコピー、コンパイル）は headless-mt5-remote ローカルスキルに記載されています。内容の乖離を避けるため、ここでは重複して記載しません。

監視コマンド

MT5 サービスの状態を確認

systemctl --user status mt5

今日のティックファイルを確認

ls -la ~/.cache/opendeviationbar/ticks/FXVIEW_EURUSD/$(date +%Y)/

最新ファイルのティック数をカウント

duckdb -c "SELECT count(*) FROM read_parquet('path/to/file.parquet')"

復旧セグメントを確認

ls ~/.cache/opendeviationbar/ticks/FXVIEW_EURUSD/$(date +%Y)/*_[0-9].parquet 2>/dev/null

systemd サービスチェーンを表示

systemctl --user list-units --type=service | grep -E "xvfb|xfce|x11vnc|mt5"

MT5 ジャーナルでエラーを確認

journalctl --user -u mt5 --since "1 hour ago" --no-pager

スコープの境界

• このスキル： 運用、監視、トラブルシューティング
• headless-mt5-remote ローカルスキル： デプロイ手順（SSH、ファイルコピー、コンパイル）
• fxview-parquet-consumer スキル： データの利用パターン（スキーマ、DuckDB クエリ）

トラブルシューティング

問題	原因	解決策
MT5 サービスが起動しない	ディスプレイスタックが起動していない	まず xvfb を起動し、次に xfce、x11vnc、mt5 を起動します
EA がティックを収集しない	シンボルが Market Watch にない	MT5 でシンボルのチャートを開き、EA を再度アタッチします
PrintFormat で Wine がクラッシュする	%I64u/%I64d の指定子を使用している	IntegerToString() に置き換えます
DLL の読み込みに失敗する	tick_writer.dll がない	DLL を MQL5/Libraries/ にコピーします（物理コピー）
ティックデータに欠落がある	EA の再起動またはネットワークの問題	journalctl を確認し、リカバリーセグメントが存在することを確認します
リカバリーファイル _1_2	再起動後の通常の状態	すべてのセグメントは有効です。DuckDB で統合します
コンパイルログが読めない	UTF-16LE エンコーディング	iconv -f UTF-16LE -t UTF-8 を使用します
Xvfb が実行されていない	サービスがクラッシュしたか、有効化されていない	systemctl --user start xvfb

実行後の振り返り

このスキルの実行が完了したら、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して一致させます。
3. 回避策が必要でしたか？ — 別のフラグや追加の手順など、臨機応変な対応が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づく更新はしないでください。