【　ns-3.30の使い方 → 1 → 2 → 3 → 4 → 5 → [6] → 7　】

ネットワークシミュレータであるns3の説明をいくつかにわけて投稿しています．この投稿は「6. トレーシングシステム」です．

6. トレーシングシステム

ns3ではシミュレーション中の様々な変数をトレースし，ファイルに出力することができます．例えば，移動するノードの座標やTCPの輻輳窓サイズなどです．この記事では，ns3のトレーシングシステムについて説明します．

ノードの座標をトレースする
トレースの仕組み
トレースに関するコードの書き方
ファイルに出力
mid-levelヘルパーの使い方
まとめ

文献

ノードの座標をトレースする

third.ccではモバイルノードがランダムウォークしていました．scratch/mythird.cc（examples/tutorial/third.ccを単にコピーしたもの）を書き換えて，通信をしているモバイルノード（n7）の座標を画面に出力させます．

40行目NS_LOG_COMPONENT_DEFINE()の直後に以下のコードを追加します．

mythird.cc

void
CourseChange (std::string context, Ptr<const MobilityModel> model)
{
  Vector position = model->GetPosition ();
  NS_LOG_UNCOND (context <<
    " x = " << position.x << ", y = " << position.y);
}

191行目Simulator::Run()の直前に以下のコードを追加します．

mythird.cc

std::ostringstream oss;
oss <<
  "/NodeList/" << wifiStaNodes.Get (nWifi - 1)->GetId () <<
  "/$ns3::MobilityModel/CourseChange";

Config::Connect (oss.str (), MakeCallback (&CourseChange));

これで実行してみます．

$ ./waf --run mythird
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10, y = 0
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.3841, y = 0.923277
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.2049, y = 1.90708
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.8136, y = 1.11368
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.8452, y = 2.11318
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.9797, y = 3.10409
At time 2s client sent 1024 bytes to 10.1.2.4 port 9
At time 2.01796s server received 1024 bytes from 10.1.3.3 port 49153
At time 2.01796s server sent 1024 bytes to 10.1.3.3 port 49153
At time 2.03364s client received 1024 bytes from 10.1.2.4 port 9
/NodeList/7/$ns3::MobilityModel/CourseChange x = 11.3273, y = 4.04175
/NodeList/7/$ns3::MobilityModel/CourseChange x = 12.013, y = 4.76955
/NodeList/7/$ns3::MobilityModel/CourseChange x = 12.4317, y = 5.67771
/NodeList/7/$ns3::MobilityModel/CourseChange x = 11.4607, y = 5.91681
...

無事，n7の座標情報が表示されました．

トレースの仕組み

上述の追加コードで行なっていたことを端的に説明すると，「自作したトレースシンク関数CourseChange()をトレースソースCourseChangeへフックし，変数の値が変わるたびにコールバック¹としてトレースシンク関数が呼ばれる．」です．トレースソース・トレースシンク・フックについてそれぞれ説明します．

トレースソースとは，ns3側で用意されているトレースできる変数の名前のことです．上の例ではMobilityModelクラスが持つCourseChangeというトレースソースを利用して，座標情報を取得しましした．つまり__API__です．トレースシンクは，トレースソースから情報を取得して処理する関数で，40行目以下に追加したCourseChange()のことです．トレースシンクがどのトレースソースから情報を取得する関数であるかを関連づける行為をフックと呼びます．フックされたトレースシンク関数は，トレース対象である変数の値が変わるたびにコールバックとして呼び出されます．

mythird.ccのコードを見ていきましょう．

トレースシンク

mythird.cc

void
CourseChange (std::string context, Ptr<const MobilityModel> model)
{
  Vector position = model->GetPosition ();
  NS_LOG_UNCOND (context <<
    " x = " << position.x << ", y = " << position.y);
}

トレースシンク関数です．引数のmodelから位置情報を取得しNS_LOG_UNCONDで画面に出力しています．関数の型はトレースソースごとに決まっていて，調べ方は後述します．contextは次で説明するコンフィグパスです．

コンフィグパスとフック

mythird.cc

std::ostringstream oss;
oss <<
  "/NodeList/" << wifiStaNodes.Get (nWifi - 1)->GetId () <<
  "/$ns3::MobilityModel/CourseChange";

Config::Connect (oss.str (), MakeCallback (&CourseChange));

モバイルノードの座標を出力すると言えど，どのモバイルノードの座標かを示す必要があります．ns3ではそれをコンフィグパスというファイルパスのような仕組みを使って特定します．上のコードのossには/NodeList/7/$ns3::MobilityModel/CourseChangeという値が入り（ノード数をオプションで変更していない場合），「シミュレーションに参加する全ノードの7番目（n7）のMobilityModelオブジェクトのトレースソースCourseChange」を意味します．ノード番号はPtr<Node>のGetId()メソッドで取得できます．$マークはns3オブジェクトを表します．以上で，欲しい情報はn7の座標であることが特定できました．

コンフィグパスのトレースソースと自作したトレースシンク関数をConfig::Connect()関数でフックします．フックするトレースシンク関数はコールバック関数である必要があるため，ns3のMakeCallback()関数でコールバックに変換しています．コンフィグパスの調べ方は後述します．

トレースシンク関数をフックしたことにより，トレース対象の変数m_courseChangeTraceの値が変わるたびにCourseChange()が呼ばれ，画面に座標情報が出力されることになります．

自作したトレースシンク関数CourseChange()をトレースソースCourseChangeへフックし，変数の値が変わるたびにコールバックとしてトレースシンク関数が呼ばれる．

理解できたでしょうか．

トレースに関する3つの疑問

3つの疑問に答えながらトレースの手順を説明します．

どのようなトレースソースがあるか
書くべきトレースシンク関数の引数の型はなにか
コンフィグパスは何か

疑問1. どのようなトレースソースがあるか

なによりもまず，どんなトレースソースがあるか分からなければ利用できません．API DocumentationのAll TraceSourcesに全トレースソースが掲載されています．

クラスのドキュメントにもクラスに属するトレースソースがリストされています．

お目当てのトレースソースがなければ残念ながら自作するしかありません．トレースソースの作り方はモジュール開発の記事で扱います．

疑問2. 書くべきトレースシンク関数の型は何か

トレースソースがわかれば，対応するトレースシンク関数を書く必要がありますが，関数の型はどうすればいいでしょうか．トレースソースの説明のCallback signatureをクリックするとわかります．

Ptr<const MobilityModel> modelが引数であることがわかりました．mythird.ccに追加したトレースシンクCourseChange()の型は，それにcontextを追加したものです．

mythird.cc

CourseChange (std::string context, Ptr<const MobilityModel> model)

コンフィグパスを表すcontextはConfig::Connect()でフックした際に自然と挿入される引数です．いらない場合は，フックする際にConfig::ConnectWithoutContext()を使い，トレースシンク関数の引数からcontextを削ります．

CourseChange (Ptr<const MobilityModel> model)

疑問3. コンフィグパスは何か

トレースシンク関数が書いたあとはフックするだけです．コンフィグパスはTraceSourcesの少し上にあります．

[i]にはノード番号が入ります．したがって，ノード7の座標を知りたいときのパスは/NodeList/7/$ns3::MobilityModel/CourseChangeです．mythird.ccに記述したパスと一致しています．

中には/NodeList/[i]/DeviceList/[i]/$とネットデバイス番号まで指定するものもあります．例えば，ノード番号3でネットデバイス番号0のコンフィグパスは/NodeList/3/DeviceList/0です．モビリティモデルは，デバイスごとではなくノードごとに設定するものなので，デバイス番号は必要ありません．また，全てのノードや全てのネットデバイスを表すには*を使います．/NodeList/*/DeviceList/*

ファイルに出力

実践的には，画面ではなくファイルに出力したいことが多いと思います．ns3ではファイルに出力するために，mid-levelヘルパーというヘルパー関数があります．

CourseChange()を以下のように変更してください．

myfirst.cc

void
CourseChange (Ptr<OutputStreamWrapper> stream, std::string context, Ptr<const MobilityModel> model)
{
  Vector position = model->GetPosition ();
  *stream->GetStream () << context << " x = " << position.x << ", y = " << position.y << std::endl;
}

Config::Connectの部分を以下のように変更してください．

mythird.cc

  AsciiTraceHelper asciiTraceHelper;
  Ptr<OutputStreamWrapper> stream = asciiTraceHelper.CreateFileStream ("third.tr");

  std::ostringstream oss;
  oss <<
    "/NodeList/" << wifiStaNodes.Get (nWifi - 1)->GetId () <<
    "/$ns3::MobilityModel/CourseChange";

  Config::Connect (oss.str (), MakeBoundCallback (&CourseChange, stream));

実行してみます．

$ ./waf --run mythird.cc
At time 2s client sent 1024 bytes to 10.1.2.4 port 9
At time 2.01796s server received 1024 bytes from 10.1.3.3 port 49153
At time 2.01796s server sent 1024 bytes to 10.1.3.3 port 49153
At time 2.03364s client received 1024 bytes from 10.1.2.4 port 9
$ head -5 third.tr
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10, y = 0
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.3841, y = 0.923277
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.2049, y = 1.90708
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.8136, y = 1.11368
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.8452, y = 2.11318

座標情報がthird.trというファイルに出力されていることが確認できます．gnuplotで動いた道筋を図にしてみます．

$ gnuplot
gnuplot> set terminal png size 640,480
gnuplot> set output "third.png"
gnuplot> plot 'third.tr' using 4:7 title "n7 Walk Path" with linespoints
gnuplot> exit
$ xdg-open third.png

モバイルノードn7はスタート地点(10,0)から確かにランダムウォークしているようです．

mid-levelヘルパーの使い方

AsciiTraceHelperを使ってOutputStreamWrapperを生成
OutputStreamWrapperをトレースシンク関数へ追加の引数として渡す
トレースシンク関数内でOutputStreamWrapper::GetStream()を使って標準出力のように記述する
出力先がファイルになっている

OutputStreamWrapperは単にstd::ostreamをラップしているだけ，などと難しいことは述べません．CreateFileStream()の引数にファイル名を指定し，OutputStreamWrapper::GetStream()を使えばファイル出力ができる，ということを抑えればもう使い始められます．MakeBoundCallback()はトレースシンク関数の引数を増やしています．

トレースソースから提供される情報がパケットのときは，pcapファイルへ出力することもできます．詳しい仕組みを知りたい方は，公式チュートリアルのTracing#using-mid-level-helpersを見てください．

まとめ

特定の変数を追跡したい場合はトレーシングシステムが便利です．変更内容を追跡したい変数で，わざわざstd::coutする必要がありません．mid-levelヘルパーと組み合わせることで，ファイルやpcapファイルへも出力可能です．ぜひ使いこなしてください．

次の記事では，ネットワークシミュレーションの要であるスループットやパケット損失率をフローモニタを使って測定します．

いつ実行されるかわからないAの実行後にB関数を実行するためには，AにBを登録しておき，A実行の最後でBを呼び出すことで実現できる．この仕組みをコールバックといい，Bをコールバック関数という． ↩