レベル: 中級 Dan Jemiolo (danjemiolo@us.ibm.com), Advisory Software Engineer, IBM
2007年 7月 23日 WSDM (WS-DistributedManagement) は、管理対象リソースの基盤となる Web サービス・インターフェースを定義する OASIS 標準です。WSDM 仕様にはメトリックに関する定義も含まれています。メトリックとは、一定の期間で値を収集する対象となるリソース・プロパティーのことです。Web サービス・メトリックの例には、1 分あたりの要求処理数、1 日あたりのディスク・スペースの消費量、サーバーのタイムアウトが原因で失敗したトランザクションの割合などがあります。この記事では、WSDM のメトリックを使用する上での重要な 3 つのタスク、すなわち、メトリックにすべきリソース・プロパティーの決定、Apache Muse によるメトリックの作成、そして Web サービス・クライアントからのメトリック値の評価について説明します。
WSDM (WS-DistributedManagement) は、管理対象リソースの最も基本的な部分を対象とした Web サービス・インターフェースを定義する標準です。WSDM 仕様にはメトリックに関する定義が含まれており、一定の期間で値を収集する対象となるリソース・プロパティーのことを指します。例えば以下のようなプロパティーをメトリックとすることができます。
- 1 分あたりの要求処理数
- 1 日あたりのディスク・スペース消費量
- サーバーのタイムアウトが原因で失敗したトランザクションの割合
この記事では、独自のメトリック・レポート・システムを使用可能にするために必要な 3 つの重要なタスクについて説明します。そのタスクとは、以下のとおりです。
- メトリックにすべきリソース・プロパティーの決定
- Apache Muse を利用したメトリックの作成
- Web サービス・クライアントからのメトリック値の評価
この記事の前提条件として、Apache Muse を使った Web サービス・エンドポイントの作成に慣れていること、そして WSDM (WS-DistributedManagement) の一般概念を理解していることが必要です。また、Muse 配布に含まれているサンプル・プロジェクトを事前にビルドしてテストしておく必要もあります （WSRF Sample Project サイトを参照）。記事では、このサンプル・プロジェクトを使ってメトリック関連の作業を開始します。作業を始める前に WSDM および Muse に関する詳しい背景を知っておきたいという方は、「参考文献」セクションのリンクにアクセスしてください。
サンプル・プロジェクトの作成
リソース・プロパティーによる WSDM メトリックの使用法を説明するためにまず必要になるのは、WSRP (WS-ResourceProperties) を使用するサンプル Web サービス・エンドポイントです。この必要条件を完全に満たしてくれるのが、Muse 配布に含まれている wsrf サンプル・プロジェクトです。WSRP 操作のすべてを使用するこのサンプル・プロジェクトには、拡張可能な基本 WSRP 文書が含まれています。リスト 1 は、サンプル・プロジェクトの WSDL ファイル (/wsrf/wsdl/WsResource.wsdl) にある WSRP 文書スキーマです。
リスト 1. WSRP 文書スキーマ
<xsd:schema targetNamespace="http://ws.apache.org/muse/test/wsrf">
<xsd:element name="MyProperty" type="xsd:string"/>
<xsd:element name="WsResourceProperties">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="wsrf-rl:CurrentTime" />
<xsd:element ref="wsrf-rl:TerminationTime" />
<xsd:element ref="wsrf-rp:QueryExpressionDialect"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="tns:MyProperty"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
|
最初の 2 つのプロパティー (wsrf-rl:CurrentTime、wsrf-rl:TerminationTime) は WS-ResourceLifetime に関連し、3 番目のプロパティー (wsrf-rp:QueryExpressionDialect) は WSRP の QueryResourceProperties に関連します。最後のプロパティー (tns:MyProperty) はカスタム・リソース・プロパティーを例示するために含まれているありきたりな定義です。これらのプロパティーはいずれも WSDM メトリックの説明には関係しませんが、WSRP 文書に追加することになります。
このアプリケーションをデプロイして、アプリケーションのテスト・クライアントが正常に実行されるようになってから、次のセクションに進んでください。
メトリックの決定
Web サービス・インターフェースにメトリックを追加する際には、まず初めに、メトリックとして妥当なリソース･プロパティーを作成します。
WSDM 仕様では、次のように説明しています。
- メトリックとして有効なのは、特定のイベントに応じて行われる測定、または一定の間隔でスケジュールされる測定です。
- システム・リソースの単純なカウンターをメトリックにすることも可能です。
プロパティーがカウンターと定期的な測定のどちらであるか、そして変更される頻度についての詳細は、メトリックを作成する際に重要になってきます。仕様では、このようなプロパティーの詳細を宣言する方法を説明しています。仕様の複雑な詳細に足を踏み入れる前に、まずは新しいプロパティーをいくつか定義し、それらのプロパティーが何故メトリックであるのかを理解してください。
リスト 2 はリスト 1 の WSRP 文書に似ていますが、tns:FreeDiskSpace と tns:NumberOfRequestsという新しい 2 つのプロパティーが追加されています。前者はホスト・マシンのディスク空き容量をメガバイトで表し、後者はリソースがオンラインになってから処理した要求の数を表します。これらの新規プロパティーは太字で示しています。
リスト 2. 新規プロパティーを 2 つ追加した WSRP 文書
<xsd:schema targetNamespace="http://ws.apache.org/muse/test/wsrf">
<xsd:element name="MyProperty" type="xsd:string"/>
<xsd:element name="FreeDiskSpace" type="xsd:float"/>
<xsd:element name="NumberOfRequests" type="xsd:integer"/>
<xsd:element name="WsResourceProperties">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="wsrf-rl:CurrentTime" />
<xsd:element ref="wsrf-rl:TerminationTime" />
<xsd:element ref="wsrf-rp:QueryExpressionDialect"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="tns:MyProperty"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="tns:FreeDiskSpace" />
<xsd:element ref="tns:NumberOfRequests" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
|
すべてのメトリックの場合と同様、この 2 つのプロパティーは数値です。前者は、例えば一定の間隔でシステムをポーリングするなどしてシステムから収集する値です。一方、後者はカウンターで、新しい要求が処理されるたびに更新されます。
WSDL に新規プロパティーを追加したら、WSDL2Java ツールを実行してエンドポイントのカスタム機能コードを再生成してください。すると、1 つのプロパティー (tns:MyProperty) の実装コードだったところが、3 つのプロパティーのコードに置き換わります。リスト 3 は、生成された org.apache.muse.test.wsrf.MyCapability クラスのソース・ファイルです。
リスト 3. 生成された MyCapability クラスのソース・ファイル
//
// MyCapability.java
// Thu Mar 08 20:45:30 EST 2007
// Generated by the Apache Muse Code Generation Tool
//
package org.apache.ws.muse.test.wsrf;
import org.apache.muse.ws.addressing.soap.SoapFault;
import org.apache.muse.ws.resource.impl.AbstractWsResourceCapability;
import javax.xml.namespace.QName;
public class MyCapability extends AbstractWsResourceCapability implements IMyCapability
{
public void initialize() throws SoapFault
{
//
//The following call is necessary to property initialize the resource
//
super.initialize();
//
//TODO perform intitialization of the following non-primitive properties
//
// MyProperty
//
throw new RuntimeException("User needs to update initialization code");
}
private static final QName[] _PROPERTIES = new QName[]
{
new QName(NAMESPACE_URI, "MyProperty", PREFIX),
new QName(NAMESPACE_URI, "FreeDiskSpace", PREFIX),
new QName(NAMESPACE_URI, "NumberOfRequests", PREFIX)
};
public QName[] getPropertyNames()
{
return _PROPERTIES;
}
private String[] _MyProperty;
private double _FreeDiskSpace;
private int _NumberOfRequests;
public String[] getMyProperty()
{
return _MyProperty;
}
public void setMyProperty(String[] param0)
{
_MyProperty = param0;
}
public double getFreeDiskSpace()
{
return _FreeDiskSpace;
}
public void setFreeDiskSpace(double param0)
{
_FreeDiskSpace = param0;
}
public int getNumberOfRequests()
{
return _NumberOfRequests;
}
public void setNumberOfRequests(int param0)
{
_NumberOfRequests = param0;
}
}
|
作業を簡単にするため、2 つのメトリック・プロパティーにはデフォルト値を入力してください。これで、もう 1 度アプリケーションをテストしてからメトリック関連の変更を行うことができます。以下に、必要な変更を太字で示します。
private float _FreeDiskSpace = 1000.00;
private int _NumberOfRequests = 10;
|
アプリケーションをビルドしてデプロイすると、wsrf テスト・クライアントのコードを使用してアプリケーションがまだきちんと動作するかどうかを確認することができます。具体的には、リスト 4 のコードによりエンドポイントで WSRP getResourcePropertyDocument() 操作が呼び出され、コンソールに WSRP 文書全体が表示されます。
リスト 4. コンソールでの WSRP 文書全体の表示
URI address = URI.create("http://localhost:8080/wsrf/services/WsResource");
EndpointReference epr = new EndpointReference(address);
WsResourceClient client = new WsResourceClient(epr);
client.setTrace(true);
try
{
client.getResourcePropertyDocument();
}
catch (SoapFault fault)
{
fault.printStackTrace();
}
|
メトリックを使用するためのアプリケーションの構成
WSDM メトリックを使用するように Muse ベースのアプリケーションを構成するには、2 つの作業が必要になります。まず、muws2:CurrentTime プロパティーを WSDL に追加する作業、そしてメトリック・メタデータを RMD ファイルに追加する作業です。RMD ファイルとその目的について十分な知識がない場合は、「参考文献」に記載したリソース・メタデータに関する記事を読んでください。この記事を読めば、RMD ファイルを (許可と検証を WSRP 文書に追加して) 作成する方法、そしてこのファイルを Muse ベースのアプリケーションに追加する方法が分かります。
それではまず、WSDM メトリック機能の追加手順から説明していきましょう。
WSDM メトリック機能の追加
 |
参考資料
- 「WSDM メトリック機能」は muws2:CurrentTime プロパティーを定義するだけでなく、WSDM メトリックとして宣言されたリソース・プロパティーのメトリック関連のメタデータも管理します。
- この WSDL2Java コマンド概要では、API およびデプロイメント記述子テンプレートを作成する上でのこのコマンドの役割を説明しています。
|
|
muws2:CurrentTime プロパティーは、WSDM メトリック機能が定義する唯一のプロパティーです。WSRP 文書にこのプロパティーがあると、WSDL2Java はリソースがメトリック機能を使用していることを認識し、メトリック機能を muse.xml 内のリソース・タイプ記述に追加します。メトリック機能がリソース・タイプ定義の一部として追加されると、適切なメタデータをプロパティーに追加するだけで、そのプロパティーを「メトリック」として宣言できます。リスト 3 に、WSRP 文書に追加する変更 (太字) を示します。これらの変更を追加したら、WSDL2Java ツールをもう一度実行してください。
リスト 5. メトリックとしてのプロパティーの宣言
<xsd:schema targetNamespace="http://docs.oasis-open.org/wsdm/muws2-2.xsd">
<xsd:include schemaLocation="WSDM-MUWS-Part2-1_1.xsd" />
</xsd:schema>
<xsd:schema targetNamespace="http://ws.apache.org/muse/test/wsrf">
<xsd:element name="MyProperty" type="xsd:string"/>
<xsd:element name="FreeDiskSpace" type="xsd:float"/>
<xsd:element name="NumberOfRequests" type="xsd:integer"/>
<xsd:element name="WsResourceProperties">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="wsrf-rl:CurrentTime" />
<xsd:element ref="wsrf-rl:TerminationTime" />
<xsd:element ref="wsrf-rp:QueryExpressionDialect"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="tns:MyProperty"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="tns:FreeDiskSpace" />
<xsd:element ref="tns:NumberOfRequests" />
<xsd:element ref="muws2:CurrentTime" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
|
アプリケーションの muse.xml ファイルを開くと、メトリック機能をサポートするための XML が追加されていることが分かります。この XML は、リスト 6 のとおりです。
リスト 6. メトリック機能をサポートするために追加された XML
<desc:capability xmlns:desc="http://ws.apache.org/muse/descriptor">
<desc:capability-uri>
http://docs.oasis-open.org/wsdm/muws/capabilities/Metrics</desc:capability-uri>
<desc:java-capability-class>
org.apache.muse.ws.dm.muws.impl.SimpleMetrics</desc:java-capability-class>
</desc:capability>
|
この時点ではアプリケーションの動作は以前と変わりありません。リソース・プロパティーに変更を反映させるには、アプリケーションの RMD ファイルを更新します。
WSDM メトリック・メタデータの追加
WSDM 仕様では、プロパティーがメトリックとして認識されるようにするために関連付ける必要がある数々のメタデータ値について説明しています。そのうち最も重要なメタデータ値は Capability で、これは メトリック機能の URI http://docs.oasis-open.org/wsdm/muws/capabilities/Metrics に設定されます。この値は Muse ランタイムに、プロパティーがメトリックであること、そしてそのプロパティーのメタデータを更新してプロパティーに関するすべての WSRP メッセージに含めなければならないことを指定します。一方、メトリックの特性を記述するメタデータ値は以下のとおりです。
-
ChangeType,
-
TimeScope, and
-
GatheringTime;
-
CalculationInterval (これはオプションで、該当する場合に使用します)
クライアントは上記の値を手掛かりに、メトリック・プロパティーによって記録された値とそれぞれの値の対処方法を評価します。仕様ではこれらの値の微妙な違いを詳しく説明していますが、上記ではとりあえず、記事で説明するメトリックに最適な値を抜粋しました。その他のさまざまな値について調べるのは、読者の皆さんへの課題とします。
リソースのメタデータを更新して 2 つの新規プロパティーがメトリックとして扱われるようにするため、リソースの RMD ファイル (/WEB-INF/classes/wsdl/WsResource.rmd) を開きます。このファイルには元のサンプル・アプリケーションにあったプロパティーのメタデータは含まれていますが、新規プロパティーのエントリーはないので追加する必要があります。リスト 7 は、新規プロパティーのための基本メタデータ・エントリーを作成する XML です。
リスト 7. プロパティーの基本メタデータ・エントリー
<Property xmlns:tns="http://ws.apache.org/muse/test/wsrf"
name="tns:FreeDiskSpace"
modifiability="read-only"
mutability="mutable"/>
<Property xmlns:tns="http://ws.apache.org/muse/test/wsrf"
name="tns:NumberOfRequests"
modifiability="read-only"
mutability="mutable"/>
|
メトリック・メタデータを追加するには、<Property/> 要素の下に、WSDM 仕様で指定された名前と値を使って XML 要素を作成します。tns:FreeDiskSpace に関しては、これは一定の間隔でシステムをポーリングして実装するように意図されているプロパティーであり、単なるカウンターではないため、リスト 8 のような追加が必要になります。
リスト 8. tns:FreeDiskSpace に関する追加
<Property xmlns:tns="http://ws.apache.org/muse/test/wsrf"
name="tns:FreeDiskSpace"
modifiability="read-only"
mutability="mutable">
<muws2:Capability>
http://docs.oasis-open.org/wsdm/muws/capabilities/Metrics</muws2:Capability>
<muws2:ChangeType>Gauge</muws2:ChangeType>
<muws2:TimeScope>Interval</muws2:TimeScope>
<muws2:GatheringTime>Periodic</muws2:GatheringTime>
<muws2:CalculationInterval>PT10S</muws2:CalculationInterval>
</Property>
|
上記の tns:FreeDiskSpace のメトリック・メタデータは Muse に対し、このプロパティーはカウンターではなくゲージであること、そして一定の間隔で収集されることを指定します (間隔は XML Schema 期間として指定されていて、10 秒に相当します)。一方、tns:NumberOfRequests メタデータの場合は多少異なります。これはカウンターで、その値は新しい要求を受け取るたびに収集されるからです。リスト 9 を参照してください。
リスト 9. tns:NumberOfRequests メタデータ
<Property xmlns:tns="http://ws.apache.org/muse/test/wsrf"
name="tns:NumberOfRequests"
modifiability="read-only"
mutability="mutable">
<muws2:Capability>
http://docs.oasis-open.org/wsdm/muws/capabilities/Metrics</muws2:Capability>
<muws2:ChangeType>Counter</muws2:ChangeType>
<muws2:TimeScope>PointInTime</muws2:TimeScope>
<muws2:GatheringTime>OnChange</muws2:GatheringTime>
</Property>
|
RMD ファイルに以上の変更を加えたら、Muse アプリケーションを再起動してください。残りはメトリック機能が処理してくれます。
最後に考慮しなければならない重要な鍵は、メトリックの評価です。
クライアント・アプリケーションからのメトリックの評価
クライアント・アプリケーションでプロパティーをメトリックとして利用するには、以下の 2 つの方法があります。
- プロパティーの RMD ファイルを読み取る
- WSRP の
getResourceProperty() を呼び出すたびに応答メッセージに追加されるメタデータを抽出する
この記事では 2 番目の方法を取り上げ、Muse フレームワークがクライアント側アプリケーションの手間をいかにして省くのかを説明します。
Muse API は、muse-wsdm-muws-impl.jar ファイル内に、org.apache.muse.ws.dm.muws.remote.MetricsClient という名前のクライアント・クラスを持ちます。このクラスに定義されている 2 つのメソッドは、org.apache.muse.ws.resource.remote.WsResourceClient クラスの getResourceProperty() メソッドによく似ていますが、java.util.Map によるメトリック・メタデータの読み取り機能が追加されているところが異なります。ここで必要な作業は、getResourceProperty() 呼び出すときに空のマップを提供することだけです。呼び出しが行われると、MetricsClient が応答メッセージに含まれているメタデータの名前と値のペアをマップに入力します。メタデータ値として使用される可能性があるのは、Duration、LastUpdated、ResetAt です。最初の値はストリングで、後の 2 つは日付です。リスト 10 に、getResourceProperty() の呼び出しで返されたメトリック・メタデータを読み取る方法を示します。
リスト 10. getResourceProperty() で返されるメタデータを読み取る方法
URI address = URI.create("http://localhost:8080/wsrf/services/WsResource");
EndpointReference epr = new EndpointReference(address);
MetricsClient client = new MetricsClient(epr);
client.setTrace(true);
Map metrics = new HashMap();
QName name = new QName("http://ws.apache.org/test/wsrf", "FreeDiskSpace", "tns");
double[] values =
(double[])client.getPropertyAsObjectAndMetrics(name, double.class, metrics);
System.out.println("The property values are: ");
for (int n = 0; n < values.length; ++n)
System.out.println(values[n]);
String duration = (Date)metrics.get(MuwsConstants.DURATION);
System.out.println("The property is updated on the following interval: " + duration);
|
必ずトレース機能をオンにして (client.setTrace(true))、SOAP 応答メッセージでのメトリック・メタデータの表現方法が分かるようにしてください。現時点でのアプリケーションに対して上記のコードを実行すると、結果は以下のようになります。
The property values are:
1000.0
The property is updated on the following interval: PT10S
|
これまで作成したコードを変更すれば、WSDL2Java で生成された setFreeDiskSpace() メソッドでディスクの空き容量を読み取り、フィールドを更新するシステム呼び出しを実際に行うこともできます。プロパティーを更新するたびに、メトリック機能は保管しているそのプロパティーのメタデータを更新するので、次の getResourceProperty() 要求は最新のメタデータを受け取ることになります。
まとめ
この記事では、メトリックの基盤を提供する WSRP や、異なるタイプのメトリックについての詳細なセマンティクスについても触れながら、WSDM 仕様ではメトリックがどのように定義されているかを説明しました。Apache Muse アプリケーションは、Java コードを一切書かなくても、メトリックを使用するように構成できます。さらに Muse にはクライアント側の API も含まれているため、メトリック情報を簡単に解析できます。このような基本的なスキルがあれば、リソースの振る舞いをより完全に把握できる高度な Web サービス・インターフェースを定義できるはずです。
参考文献 学ぶために
製品や技術を入手するために
議論するために
著者について | 
| | Dan Jemiolo は、ノースカロライナ州リサーチ・トライアングル・パークにある IBM Autonomic Computing チームの Advisory Software Engineer です。彼は Apache Muse 2.0 の設計および開発を指揮し、現在も引き続きこのプロジェクトに取り組んでいます。また、Dan は WS-RF TC に WS-ResourceMetadata 仕様のエディターとして参加しており、Web サービス標準の採用を促進する IBM の戦略に携わっています。彼はわずか 2 年前に、Rensselaer Polytechnic Institute で Computer Science を専攻し理学修士の学位を取得した後、IBM に入社しました。 |
記事の評価
| 
