MQL5ファイル操作・CSVログ出力完全ガイド｜Filesフォルダ・FileOpen・文字コードの基本

MQL5でEAを開発・検証する時、Expertsログだけでは確認しきれない情報があります。シグナル判定、フィルター通過、ロット計算、OrderCheck結果、OrderSend結果、決済理由、通知結果、外部連携結果などを、後から集計・比較・検証したい場合は、CSVログとして保存しておくと便利です。

ただし、FileOpenやFileWriteを使ってCSVを出力するだけでは、実務で使いやすいログにはなりません。保存場所、ファイル名、区切り文字、文字コード、ヘッダー行、追記方式、日別ファイル、ログ肥大化、バックテスト時の保存先、機密情報の扱いまで整理する必要があります。

この記事では、MQL5のファイル操作とCSVログ出力について、FileOpen、FileWrite、FileClose、Filesフォルダ、Commonフォルダ、FILE_CSV、FILE_ANSI、FILE_UNICODE、ログ設計、EA検証記録、バックテスト記録、通知・外部連携前のローカル保存、機密情報保護を実務目線で整理します。

この記事は、MT5 / MQL5のEA開発、検証補助、ログ確認、CSV記録、外部連携前のデータ整理を目的とした技術記事です。特定の売買判断、利益、勝率、損失回避、推奨ロット、推奨銘柄を案内するものではありません。

この記事で確認すること

MQL5でCSVログを出力する理由

EAの動作確認では、ExpertsログやJournalログを確認することが基本です。しかし、長期間の検証、複数条件の比較、フィルターごとの停止回数、注文結果の集計、バックテスト条件別の比較を行う場合、テキストログだけでは扱いにくいことがあります。

CSVログを出力しておくと、Excel、Google Sheets、Python、集計ツールで後から分析しやすくなります。たとえば、どのフィルターで止まった回数が多いか、OrderCheckで失敗した理由は何か、曜日や時間帯でシグナル発生数が違うか、バックテスト条件ごとの結果がどう変わるかを確認しやすくなります。

特にEA設計パターンで signal、filter、risk、execution、exit を分けている場合、それぞれの段階をCSVへ記録すると、EAが注文しない理由や、検証条件ごとの違いを追いやすくなります。

ExpertsログとCSVログを分ける

Expertsログは、EAの動作をその場で確認するために使いやすいログです。初期化成功、ハンドル作成失敗、OrderSend失敗、OnTimer動作など、EAの状態確認に向いています。一方で、行ごとの形式が自由なため、後から集計するには加工が必要です。

CSVログは、列を固定して保存するため、後から集計しやすい形式です。日付、銘柄、時間足、イベント種別、シグナル、フィルター結果、ロット、価格、retcode、コメントなどを列にしておけば、表計算ソフトで並べ替えや集計ができます。

実務では、Expertsログに原因追跡用の要約を出し、CSVログに検証・集計用の構造化データを出すのが扱いやすいです。どちらか一方だけに寄せるのではなく、役割を分けて使います。

保存場所：FilesフォルダとCommonフォルダ

MQL5でファイルを扱う時は、保存場所を理解しておく必要があります。通常のFileOpenでは、MT5データフォルダ内のMQL5\Files配下が使われます。FILE_COMMONを指定すると、複数のMetaTraderから共通で使えるCommon Files領域を利用できます。

EAごと、端末ごとにログを分けたい場合は通常のFilesフォルダが扱いやすいです。複数MT5間で共通のログや設定ファイルを使いたい場合はCommonフォルダが候補になります。ただし、Commonフォルダを使う場合は、複数EAや複数端末から同じファイルへ同時アクセスしないように注意が必要です。

ファイルが見つからない場合は、EAを動かしているMT5のデータフォルダを確認します。複数のMT5を使っている場合、別の端末データフォルダを見ていることもあります。

FileOpenの基本

FileOpenは、MQL5でファイルを開くための関数です。CSVログを出力する場合は、FILE_WRITE、FILE_READ、FILE_CSV、FILE_ANSI、FILE_COMMONなどのフラグを組み合わせて使います。

FileOpenに失敗した場合は、INVALID_HANDLEが返ります。その場合はGetLastErrorをログに出し、ファイル名、保存場所、権限、テスター環境、同時アクセスを確認します。

int OpenCsvFile(string file_name)
{
   ResetLastError();

   int handle = FileOpen(file_name,
                         FILE_READ | FILE_WRITE | FILE_CSV | FILE_ANSI,
                         ',');

   if(handle == INVALID_HANDLE)
   {
      PrintFormat("CSV_OPEN_FAIL file=%s last_error=%d",
                  file_name,
                  GetLastError());
      return INVALID_HANDLE;
   }

   PrintFormat("CSV_OPEN_OK file=%s handle=%d", file_name, handle);
   return handle;
}

この例では、CSV形式、ANSI文字コード、半角コンマ区切りでファイルを開いています。既存ファイルへ追記する場合は、FileSeekで末尾へ移動してからFileWriteを行います。

FileOpenフラグの考え方

FileOpenでは、どのような形式でファイルを開くかをフラグで指定します。CSVログでは、FILE_CSVとFILE_WRITEを使うことが多いです。既存ファイルの末尾に追記したい場合は、FILE_READも組み合わせて使うと扱いやすくなります。

文字コードは環境や確認方法によって扱いが変わります。日本語を含むCSVをExcelで確認する場合、文字化けの可能性があるため、実際の環境で表示確認を行ってください。ログ内の項目名を英数字中心にしておくと、文字化けや列崩れのリスクを減らせます。

FileWriteでCSVへ出力する

FileWriteは、開いたファイルへデータを書き込むために使います。FILE_CSVで開いたファイルに対してFileWriteを使うと、引数ごとに列として出力されます。

CSVログでは、最初にヘッダー行を出し、その後にデータ行を追加していく構成が扱いやすいです。ヘッダー行には、time、symbol、timeframe、event、signal、reason、price、volume、retcodeなど、後から集計したい列を並べます。

void WriteCsvHeader(int handle)
{
   FileWrite(handle,
             "server_time",
             "symbol",
             "timeframe",
             "event",
             "signal",
             "reason",
             "price",
             "volume",
             "retcode",
             "comment");
}

void WriteCsvLogRow(int handle,
                    string event_name,
                    string signal_name,
                    string reason,
                    double price,
                    double volume,
                    int retcode,
                    string comment)
{
   FileWrite(handle,
             TimeToString(TimeCurrent(), TIME_DATE | TIME_SECONDS),
             _Symbol,
             EnumToString((ENUM_TIMEFRAMES)Period()),
             event_name,
             signal_name,
             reason,
             DoubleToString(price, _Digits),
             DoubleToString(volume, 2),
             retcode,
             comment);
}

この例では、CSVのヘッダー行とデータ行を分けています。event列には、SIGNAL、FILTER、RISK、ORDER、EXIT、ERRORなどを入れると、後からイベント種別で集計しやすくなります。

追記方式とヘッダー行の扱い

CSVログでは、EA起動ごとに新規ファイルを作る方法と、既存ファイルに追記する方法があります。検証単位でファイルを分けたい場合は新規ファイル、日別に継続記録したい場合は追記方式が扱いやすいです。

追記方式では、ファイルが空の場合だけヘッダー行を書き、既存ファイルにデータがある場合は末尾へ移動してデータ行だけ追加します。ヘッダー行が毎回増えると、後から集計しにくくなります。

int OpenCsvForAppend(string file_name)
{
   ResetLastError();

   int handle = FileOpen(file_name,
                         FILE_READ | FILE_WRITE | FILE_CSV | FILE_ANSI,
                         ',');

   if(handle == INVALID_HANDLE)
   {
      PrintFormat("CSV_OPEN_FAIL file=%s last_error=%d",
                  file_name,
                  GetLastError());
      return INVALID_HANDLE;
   }

   bool is_empty = (FileSize(handle) == 0);

   FileSeek(handle, 0, SEEK_END);

   if(is_empty)
      WriteCsvHeader(handle);

   PrintFormat("CSV_READY file=%s empty=%s",
               file_name,
               is_empty ? "Y" : "N");

   return handle;
}

この例では、FileSizeで空ファイルかどうかを確認し、空の場合だけヘッダー行を書いています。その後、FileSeekで末尾へ移動して追記できるようにしています。

CSVファイル名の設計

CSVログのファイル名は、後から見た時に内容が分かるように設計します。EA名、銘柄、時間足、日付、検証IDなどを含めると、ファイルを探しやすくなります。

ただし、ファイル名に口座番号、個人情報、token、Webhook URLなどを含めてはいけません。共有する可能性があるログファイルには、機密情報を入れない設計にしてください。

string BuildDailyCsvFileName(string prefix)
{
   MqlDateTime dt;
   TimeToStruct(TimeCurrent(), dt);

   string file_name = StringFormat("%s_%s_%s_%04d%02d%02d.csv",
                                   prefix,
                                   _Symbol,
                                   EnumToString((ENUM_TIMEFRAMES)Period()),
                                   dt.year,
                                   dt.mon,
                                   dt.day);

   return file_name;
}

この例では、prefix、銘柄、時間足、日付を含めたファイル名を作成しています。日別ファイルにすると、ログ肥大化を抑えやすくなります。

EA検証ログの列設計

EA検証用のCSVログでは、後から何を確認したいかによって列を決めます。単に価格や注文番号だけを保存しても、なぜエントリーしたのか、なぜ見送ったのかを確認できません。

signal、filter、risk、execution、exitを分けているEAでは、各段階の結果を列にして保存すると、検証時に分析しやすくなります。

SIGNAL / FILTER / RISK / ORDER / EXIT をCSVで分ける

EAが注文しない理由を確認するには、どの段階で止まったかを記録する必要があります。シグナルが出ていないのか、フィルターで止まったのか、リスク確認で止まったのか、OrderSendで失敗したのかを分けて保存します。

CSVのevent列にSIGNAL、FILTER、RISK、ORDER、EXITを入れておくと、後からイベント種別ごとの件数を集計できます。reason列には、NO_SIGNAL、SPREAD、TIME_FILTER、BAD_VOLUME、NOT_ENOUGH_MARGIN、ORDER_RETCODEなどを入れると原因別に確認できます。

バックテストでCSVを出力する時の注意

ストラテジーテスターでCSVログを出力する場合、通常の実チャートとは保存場所や確認手順が異なることがあります。テスター実行後にファイルが見つからない場合は、テスター用のFilesフォルダや、実行しているMT5のデータフォルダを確認してください。

バックテストでは、全ティックや1分OHLCなどのモデル、対象期間、スプレッド、銘柄、時間足、setファイルが結果に影響します。CSVログには、検証条件を識別できる情報を入れると、後から比較しやすくなります。

ただし、バックテスト中に毎ティック大量のCSV出力を行うと、テスト速度が低下したり、ファイルが肥大化したりします。必要なイベントだけを出力する、詳細ログON/OFFをinputで切り替える、日別または検証ID別にファイルを分けると扱いやすくなります。

input bool InpEnableCsvLog = true;
input bool InpVerboseCsvLog = false;

void LogSignalEvent(string signal_name, string reason)
{
   if(!InpEnableCsvLog)
      return;

   if(!InpVerboseCsvLog && reason == "NO_SIGNAL")
      return;

   int handle = OpenCsvForAppend(BuildDailyCsvFileName("eaf_signal_log"));

   if(handle == INVALID_HANDLE)
      return;

   WriteCsvLogRow(handle,
                  "SIGNAL",
                  signal_name,
                  reason,
                  SymbolInfoDouble(_Symbol, SYMBOL_BID),
                  0.0,
                  0,
                  "");

   FileClose(handle);
}

この例では、CSVログのON/OFFと詳細ログON/OFFを分けています。通常検証では重要イベントだけを出し、詳細検証時だけNO_SIGNALなどの細かいログを出す設計です。

OnInit、OnTimer、OnDeinitとCSV出力

CSVログ出力は、イベント処理と組み合わせて設計します。OnInitではログ設定やファイル作成可否を確認します。OnTickではシグナルや注文に関係するイベントを記録します。OnTimerでは定期監視や通知キューの状態を記録できます。OnDeinitでは終了理由や最終状態を記録できます。

ただし、ファイルを開きっぱなしにする設計と、必要な時だけ開いて閉じる設計にはそれぞれ注意点があります。必要な時だけ開いて閉じる方が単純ですが、頻度が高いと負荷が増えます。開きっぱなしにする場合は、OnDeinitで必ず閉じる必要があります。

ログ肥大化対策

CSVログは便利ですが、出力しすぎるとファイルが肥大化します。特にOnTickで毎ティック出力する設計は、バックテストでも実運用でもログ量が増えやすくなります。

ログ肥大化を防ぐには、イベント単位で出力する、エラー時だけ出力する、詳細ログON/OFFを用意する、日別ファイルに分ける、最大行数や最大ファイルサイズを意識するなどの対策が必要です。

文字コードと区切り文字の注意点

CSVログでは、文字コードと区切り文字にも注意が必要です。日本語を含むCSVをExcelで開くと、環境によって文字化けすることがあります。また、区切り文字が半角コンマの場合、コメント内にコンマが含まれると列崩れの原因になることがあります。

実務では、CSVの列名やreasonを英数字中心にすると、文字化けや集計時のトラブルを減らせます。日本語コメントを出す場合は、実際にExcelやGoogle Sheetsで開いて確認してください。

また、ログ項目に改行、タブ、カンマ、引用符が含まれると、後から集計しにくくなる場合があります。comment列は短くし、必要なら詳細はExpertsログ側に出す設計が扱いやすいです。

機密情報をCSVに出さない

CSVログは、検証依頼やサポート時に共有される可能性があります。そのため、口座番号、氏名、メールアドレス、パスワード、APIキー、Webhook URL、token、ライセンスキーなどの機密情報を出力してはいけません。

外部連携や通知機能を検証する場合でも、ログに出すのは送信種別、送信結果、HTTPステータス、エラー種別程度に抑えます。Webhook URL全体やAPIキーをそのまま出すと、第三者に悪用される危険があります。

Google Sheets連携前のローカル記録として使う

EAの検証記録をGoogle Sheetsへ送信する場合でも、まずはローカルCSVへ記録する設計が有効です。WebRequestや外部サービス連携は、通信エラー、URL設定、権限、レート制限、レスポンス形式などの影響を受けます。

ローカルCSVへ保存しておけば、外部送信に失敗しても、EA側で何が起きたかを後から確認できます。外部連携は便利ですが、EA本体の検証ログを完全に外部サービスへ依存させない方が安全です。

実務では、EA内部でイベントを生成し、CSVへ保存し、必要に応じてOnTimerで外部送信するように分けると扱いやすくなります。CSVは検証用の正本、外部シートは共有・閲覧用と考えることもできます。

よくある不具合と確認ポイント

MQL5のファイル操作では、ファイルが作成されない、CSVが空になる、ヘッダーが毎回増える、文字化けする、バックテスト後にファイルが見つからない、ログが大きくなりすぎる、といった不具合が起きることがあります。

開発依頼前に整理するCSVログ仕様

EAや検証補助ツールでCSVログ出力を依頼する場合は、何を記録したいのかを事前に整理してください。単に「ログをCSVに出したい」だけでは、必要な列、出力タイミング、保存場所、ファイル名、文字コード、ログ量、機密情報の扱いが不明です。

特に、バックテスト検証用なのか、実運用の記録用なのか、サポート確認用なのかで設計が変わります。検証用なら詳細なシグナル・フィルター情報が必要ですが、実運用ではエラーや注文結果中心に絞る方が扱いやすい場合があります。

実務チェック表

よくある質問

MQL5でCSVログを出すには何を使いますか？

主にFileOpen、FileWrite、FileCloseを使います。CSV形式で出力したい場合は、FileOpenでFILE_CSVを指定し、FileWriteで列ごとの値を書き込みます。

CSVログはExpertsログの代わりになりますか？

完全な代わりではありません。Expertsログはその場の原因追跡に向いており、CSVログは集計や検証比較に向いています。両方を役割分担して使うのが実務的です。

バックテストで出力したCSVが見つからない時はどうしますか？

通常のMQL5\Filesではなく、テスター側のFilesフォルダに出力されている場合があります。実行しているMT5のデータフォルダ、テスター環境、FILE_COMMONの有無を確認してください。

CSVが文字化けする場合はどうしますか？

文字コードと表示ソフト側の読み込み設定を確認します。ログ項目名やreasonを英数字中心にすると、文字化けや集計時のトラブルを減らしやすくなります。

OnTickで毎回CSV出力してもよいですか？

推奨しません。OnTickは呼び出し頻度が高いため、毎ティック出力するとログが肥大化しやすくなります。イベント発生時、エラー時、詳細ログON時などに絞る設計が扱いやすいです。

CSVに口座番号やWebhook URLを出してもよいですか？

出さないでください。CSVログは共有される可能性があるため、口座番号、パスワード、APIキー、token、Webhook URL、ライセンスキーなどの機密情報は出力しない設計にします。

関連ページ

MQL5のCSVログ出力を整理する時は、EA設計、イベント処理、ログ確認、OrderCheck、CTrade、バックテスト、通知・外部連携もあわせて確認すると、検証と保守の流れを作りやすくなります。

まとめ

MQL5でCSVログを出力する場合は、FileOpen、FileWrite、FileCloseの基本だけでなく、保存場所、文字コード、区切り文字、ヘッダー行、追記方式、日別ファイル、ログ肥大化対策、機密情報保護まで設計することが重要です。

EA検証では、SIGNAL、FILTER、RISK、ORDER、EXIT、ERRORのようにイベントを分けてCSVへ記録すると、なぜ注文しなかったのか、どのフィルターで止まったのか、OrderSendがどう返ったのかを後から集計しやすくなります。

CSVログは、バックテスト、デモ口座確認、サポート確認、外部連携前のローカル記録に役立ちます。ただし、口座番号、パスワード、APIキー、token、Webhook URLなどの機密情報は絶対に出力しないようにしてください。検証しやすく、共有しても安全なログ設計にすることが大切です。