操作ガイド

SIP リクエストと応答のロギング

以下の節では、SIP リクエストと応答のロギングをコンフィグレーションおよび管理する方法について説明します。

SIP ロギングの概要

Oracle Communications Converged Application Server では、処理される SIP リクエストと応答の Protocol Data Unit (PDU) ロギングを行うことができます。ログされた SIP メッセージは、Oracle Communications Converged Application Server のドメイン全体のログ ファイル、または個々の管理対象サーバ インスタンスのログ ファイルに書き込まれます。SIP メッセージは Oracle Communications Converged Application Server インスタンスと同じログ ファイルを共有するので、ログに記録された SIP メッセージを管理するときに、ログ ローテーション、ドメイン ログ フィルタ、最大ログ サイズ コンフィグレーションなどの高度なサーバ ロギング機能を利用できます。

管理者は SIP PDU ロギングをコンフィグレーションするために、com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl クラスを使って 1 つまたは複数の SIP サーブレットを定義します。次に、定義したサーブレットのパラメータとして、またはアプリケーションと共にパッケージ化される独立した XML ファイルで、ロギング条件をコンフィグレーションします。

SIP リクエストが処理されるか、SIP 応答が生成される際に、ロギング サーブレットはスタンドアロンの XML コンフィグレーション ファイルまたはサーブレットのパラメータで定義されたフィルタ処理のパターンをメッセージと照合します。指定されたパターンと一致する SIP リクエストと応答は、ロギング サーブレットの名前、コンフィグレーションされているロギング レベル、その他の詳細と共にログ ファイルに書き込まれます。無駄なパターン マッチングを避けるために、サーブレットは最初のパターンが一致すると新しい SIP セッションにマークして、そのセッションのそれ以降のリクエストと応答を自動的にログに記録します。

ロギング条件は、sip.xml でロギング サーブレットのパラメータとして直接定義するか、外部 XML コンフィグレーション ファイルで定義します。「ロギングするメッセージの条件の指定」を参照してください。

sip.xml でのロギング サーブレットの定義

SIP メッセージのロギング サーブレットを作成するには、実装クラス com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl を持つサーブレットを定義します。msgTraceLogger サンプルの定義をコード リスト 4-1 に示します。

<servlet>

    <servlet-name>msgTraceLogger</servlet-name>

      <servlet-class>com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl</servlet-class>

    <init-param>

      <param-name>domain</param-name>

      <param-value>true</param-value>

    </init-param>

    <init-param>

      <param-name>level</param-name>

      <param-value>full</param-value>

    </init-param>

    <load-on-startup/>

  </servlet>

ロギング レベルと出力先のコンフィグレーション

SIP メッセージのロギングの詳細レベルや出力先ログ ファイルなどのロギング属性は、初期化パラメータとしてロギング サーブレットに渡されます。表 4-1 に、init-param のエントリとして指定できるパラメータとパラメータ値を示します。「コード リスト 4-1 サンプルのロギング サーブレット」には、すべての SIP メッセージ情報をドメイン ログ ファイルに記録するサーブレットの init-param サンプルのエントリの例が示されています。

ロギングするメッセージの条件の指定

ログに記録される SIP メッセージを選択するための条件は、ロギング サーブレットのアプリケーションと共にパッケージ化される XML ファイルで定義することも、サーブレットの sip.xml デプロイメント記述子で初期化パラメータとして定義することもできます。以下の節で、それぞれの方法について説明します。

XML ドキュメントを使ったロギング条件の指定

ロギング サーブレットの初期化パラメータとしてロギング条件を指定しない場合、サーブレットはロギング アプリケーションの最上位にある 1 組の XML 記述子ファイル内のロギング条件を参照します。request-pattern.xml およびresponse-pattern.xml という名前のこれらの記述子ファイルでは、ログ ファイルに記録される SIP リクエストと応答を選択するための Oracle Communications Converged Application Server のパターンが定義されます。

通常のパターン定義では、SIP メッセージ ヘッダ内の特定の値を照合するための条件を定義します。たとえば、msgTraceLogger サーブレットで使われるサンプルの response-pattern.xml では、すべての MESSAGE リクエストが照合されます。この記述子の内容を次に示します。

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE pattern

   PUBLIC "Registration//Organization//Type Label//Definition Language"

   "trace-pattern.dtd">

<pattern>

  <equal>

    <var>response.method</var>

    <value>MESSAGE</value>

  </equal>

</pattern>

SIP メッセージを照合するための追加の演算子と条件については、「trace-pattern.dtd リファレンス」を参照してください。コード リスト 4-2 に示されている equal 条件など、ほとんどの条件には、評価する SIP メッセージの部分を識別する変数 (var 要素) が必要です。表 4-2 に、一般的な変数と値の例を示します。この他の変数名と例については、「SIP Servlet API 1.1 仕様」の第 16 章「Mapping Requests to Servlets」を参照してください。Oracle Communications Converged Application Server では、リクエストと応答の両方の変数をロギング サーブレットにマッピングすることができます。

request-pattern.xml と response-pattern.xml では、同じ文書型定義 (DTD) が使われます。詳細については、「trace-pattern.dtd リファレンス」を参照してください。

サーブレットのパラメータを使ったロギング条件の指定

パターン マッチング条件は、独立した XML ドキュメントとしてではなく、ロギング サーブレットの初期化パラメータとして指定することもできます。マッチング条件を指定するためのパラメータ名は、request-pattern-string および response-pattern-string です。これらのパラメータは、「ロギング レベルと出力先のコンフィグレーション」で説明したロギング レベルや出力先と共に定義されます。

各パターン マッチング パラメータの値は、スタンドアロン パターン定義ドキュメントの DTD に準拠する有効な XML ドキュメントで構成されている必要があります (「XML ドキュメントを使ったロギング条件の指定」を参照してください)。パターンと値を定義する XML ドキュメントは sip.xml 記述子の一部として解析されてはならないので、コンテンツを [CDATA] タグで囲む必要があります。コード リスト 4-3 に、サンプルのロギング サーブレット invTraceLogger の sip.xml エントリ全体を示します。最後の 2 つの init-param の要素で、INVITE リクエスト メソッドと OPTIONS 応答メソッドだけをログに記録することを指定しています。

<servlet>

      <servlet-name>invTraceLogger</servlet-name>

      <servlet-class>com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl</servlet-class>

      <init-param>

        <param-name>domain</param-name>

        <param-value>true</param-value>

      </init-param>

      <init-param>

        <param-name>level</param-name>

        <param-value>full</param-value>

      </init-param>

      <init-param>

        <param-name>request-pattern-string</param-name>

        <param-value>

            <![CDATA[

                <?xml version="1.0" encoding="UTF-8"?>

                <!DOCTYPE pattern

                   PUBLIC "Registration//Organization//Type Label//Definition Language"

                   "trace-pattern.dtd">

                <pattern>

                  <equal>

                    <var>request.method</var>

                    <value>INVITE</value>

                  </equal>

                </pattern>

            ]]>

        </param-value>

      </init-param>

      <init-param>

        <param-name>response-pattern-string</param-name>

        <param-value>

            <![CDATA[

                <?xml version="1.0" encoding="UTF-8"?>

                <!DOCTYPE pattern

                   PUBLIC "Registration//Organization//Type Label//Definition Language"

                   "trace-pattern.dtd">

                <pattern>

                  <equal>

                    <var>response.method</var>

                    <value>OPTIONS</value>

                  </equal>

                </pattern>

            ]]>

        </param-value>

      </init-param>

      <load-on-startup/>

  </servlet>

暗号化されていないロギングのコンテンツ タイプの指定

デフォルトでは、Oracle Communications Converged Application Server は、テキストまたはアプリケーション /sdp Content-Type 値を有する SIP メッセージのコンテンツをログするために、文字列フォーマット (UTF-8 エンコーディング) を使用します。他のすべての Content-Type 値では、文字列セットが指定されている場合、Oracle Communications Converged Application Server はメッセージの charset パラメータに指定した文字列セットを使用してメッセージのコンテンツをログします。ンテンツをログしようとします。charset パラメータが指定されていない場合、または charset 値が無効かサポートされていない場合、Oracle Communications Converged Application Server は、メッセージをログする前にメッセージ コンテンツを暗号化するために Base-64 エンコーディングを使用します。

こうした状況でメッセージのコンテンツの暗号化を回避するには、sipserver.xml の string-rep 要素を使用して String-representable Content-Type 値のリストを指定します。string-rep 要素は 1 つまたは複数の一致する content-type 要素を持つことができます。ログされたメッセージがコンフィグレーションされた content-type 要素要素のいずれかに一致する場合、Oracle Communications Converged Application Server は charset パラメータが含まれているか否かにかかわらず、UTF-8 エンコーディングを使用して文字列フォーマットにコンテンツをログします。

コード リスト 4-4 に、text/* および application/sdp コンテンツに加え、追加の 3 つの Content-Type 値に対して文字列コンテンツをログする message-debug コンフィグレーションをサンプルとして示します。

   <message-debug>

     <level>full</level>

     <string-rep>

       <content-type>application/msml+xml</content-type>

       <content-type>application/media_control+xml</content-type>

       <content-type>application/media_control</content-type>

     </string-rep>

   </message-debug>

ログ ローテーションの有効化とログ ファイルの参照

Oracle Communications Converged Application Server のロギング インフラストラクチャでは、既存のログ ファイルが指定のサイズに達したら、自動的に新しいログ ファイルに書き込まれるようにすることができます。また、Administration Console を使ってログの内容を参照することや、ログに書き込まれる追加のサーバ レベル イベントをコンフィグレーションすることもできます。基本的なログ管理の詳細については、『Oracle WebLogic Server 10g Release 3 ドキュメント』の 「ログ ファイルのローテーション」を参照してください。

trace-pattern.dtd リファレンス

trace-pattern.dtd では、request-pattern.xml および response-pattern.xml ドキュメントの必須コンテンツのほかに、サーブレットの init-param 変数である request-pattern-string と response-pattern-string の値も定義されます。

<!--

さまざまなタイプの条件がサポートされています。

-->

<!ENTITY % condition "and | or | not |

                      equal | contains | exists | subdomain-of">

<!--

pattern は条件で、一連の SIP リクエストの述部です。

-->

<!ELEMENT pattern (%condition;)>

<!--

すべての構成要素の条件が true の場合にのみ、"and" 条件は

true になります。

-->

<!ELEMENT and (%condition;)+>

<!--

構成要素の条件のうち少なくとも 1 つが true の場合、"or" 条件は

true になります。

-->

<!ELEMENT or (%condition;)+>

<!--

含まれている条件の値を否定します。

-->

<!ELEMENT not (%condition;)>

<!--

変数の値が、指定したリテラル値と等しい場合に true になります。

-->

<!ELEMENT equal (var, value)>

<!--

変数の値に、指定したリテラル値が含まれる場合に true になります。

-->

<!ELEMENT contains (var, value)>

<!--

指定した変数が存在する場合に true になります。

-->

<!ELEMENT exists (var)>

<!--

-->

<!ELEMENT subdomain-of (var, value)>

<!--

変数を指定します。たとえば次のように指定します。

  <var>request.uri.user</var>

-->

<!ELEMENT var (#PCDATA)>

<!--

ルールの指定に使われるリテラル文字列値を指定します。

-->

<!ELEMENT value (#PCDATA)>

<!--

"equal" テストで大文字と小文字を区別するかどうかを指定します。

-->

<!ATTLIST equal ignore-case (true|false) "false">

<!--

"contains" テストで大文字と小文字を区別するかどうかを指定します。

-->

<!ATTLIST contains ignore-case (true|false) "false">

<!--

ID メカニズムを使うと、ツールで簡単にデプロイメント記述子の

要素に対するツール固有の参照を行うことができます。これにより、

追加のデプロイメント情報 (標準のデプロイメント記述子情報以外の

情報) を生成するツールで、標準以外の情報を独立した

ファイルに格納し、これらのツール固有のファイルから標準の

sip-app デプロイメント記述子の情報を簡単に参照

できるようになります。

-->

<!ATTLIST pattern id ID #IMPLIED>

<!ATTLIST and id ID #IMPLIED>

<!ATTLIST or id ID #IMPLIED>

<!ATTLIST not id ID #IMPLIED>

<!ATTLIST equal id ID #IMPLIED>

<!ATTLIST contains id ID #IMPLIED>

<!ATTLIST exists id ID #IMPLIED>

<!ATTLIST subdomain-of id ID #IMPLIED>

<!ATTLIST var id ID #IMPLIED>

<!ATTLIST value id ID #IMPLIED>

SIP サーブレット コードへの追跡機能の追加

TraceMessageListenerFactory を使用すると、独自のサーブレットや Java コードに追跡機能を追加することができます。TraceMessageListenerFactory により、クライアントはインスタンスを作成し、そのインスタンスに委託することで、デフォルトの追跡メッセージ リスナ実装の動作を再利用できるようになります。ファクトリ実装インスタンスは、SIP サーブレットのサーブレット コンテキストで TraceMessageListenerFactory.TRACE_MESSAGE_LISTENER_FACTORY 属性の値を検索すると見つかります。

サーブレットに追跡を実装するには、コード リスト 4-6 に示すように、サーブレットの init() メソッドでファクトリ クラスを使って委託を作成します。

public final class TraceMessageListenerImpl extends SipServlet implements MessageListener {

  private MessageListener delegate;

  public void init() throws ServletException {

    ServletContext sc = (ServletContext) getServletContext();

    TraceMessageListenerFactory factory = (TraceMessageListenerFactory) sc.getAttribute(TraceMessageListenerFactory.TRACE_MESSAGE_LISTENER_FACTORY);

    delegate = factory.createTraceMessageListener(getServletConfig());

  }

  public final void onRequest(SipServletRequest req, boolean incoming) {

    delegate.onRequest(req,incoming);

  }

  public final void onResponse(SipServletResponse resp, boolean incoming) {

    delegate.onResponse(resp,incoming);

  }

}

リスナとロギング サーブレットの起動順序

リスナとロギング サーブレットが両方ともデプロイされている場合は、最初にリスナ クラスがロードされ、その後でサーブレットがロードされます。各ロギング サーブレットがデプロイされる順序は、Web アプリケーションのデプロイメント記述子で指定されているロード順序に従います。