New Relic で監視される Java アプリケーションのカスタム インストルメンテーション メソッドの 1 つは、XML ファイルを使用して、インストルメント化する必要があるアプリ メソッドを指定することです。Java エージェントは XML ファイルを読み取り、起動時に関連するクラスを計測します。起動後にextensionsディレクトリに追加された XML ファイルは、JVM の再起動を検出する必要はありません。
カスタムインスツルメンテーションのオプションとその使用理由については、 Java agent custom instrumentation を参照してください。
XMLファイルへのアクセス
one.newrelic.com > All capabilities > APM & services > (select an app) > Settings > Instrumentationに移動します。ここから、以下の操作を行えます。
- サンプル XML ファイルをダウンロードします。(これは、
Import an XML fileをクリックすると表示されるポップアップから実行できます。) - 既存のXMLファイルを選択して編集します。
- 楽器の履歴を検索します。
XMLファイルの構造
New Relic エージェントのダウンロード パッケージ ( newrelic_agent.zip ) には、XML 計測を使用するための 2 つのテンプレートが含まれています。
extension.xsdテンプレートは、すべてのカスタム拡張が従わなければならない XML スキーマ定義です。extension-example.xmlテンプレートは一例です。このファイルは、いくつかの基本的な JDK メソッドを計測します。このファイルを編集して名前を変更する場合は、新しいファイル名と一致するようにname="extension-example"属性を変更してください。
extension.xsdテンプレートのプロパティの詳細については、 XML ファイル形式の概要をご覧ください。
XMLファイルの検証
アプリケーションを起動する前に、New Relic のコマンドラインツールを使って XML ファイルを検証します。コマンドラインツールは、クラスが jar に入っている場合にのみ使用できます。XML インストルメントを検証する方法は 2 つあります。
アプリケーションはnewrelic.jarで実行されます。呼び出しには、キーワードinstrumentの後に、XML ファイルへのパスを指定した-fileフラグが続く必要があります。プロパティ-debugはオプションであり、検証中に詳細情報を提供するためにtrueに設定できます。
このツールは
- XMLの構文を検証する。
- インストゥルメント対象の各クラスがクラスパス上に存在することを確認します。
- 各メソッドが適切なクラスに含まれていることを確認します。
XMLファイルが有効であれば、ターミナルにpass文が表示されます。
PASS: The extension at file.txt was successfully validated.XMLの検証に失敗した場合は、ターミナルに失敗メッセージが表示されます。
FAIL: reasonXMLファイルの位置
Java エージェントは、プロセスの起動時にextensionsディレクトリ内の XML ファイルを読み取ります。extensionsディレクトリも収集サイクルごとに読み取られます。実行時にこのディレクトリに追加された XML ファイルは数分以内に読み込まれるため、JVM の再起動は必要ありません。
XMLファイルの場所を指定する方法は2つあります。
XML file location options | Procedure |
|---|---|
extensionsディレクトリを作成する |
|
既存のextensionsディレクトリを指定する |
|
ファイルの読み込みを確認する
エージェントが XML ファイルを読み取ったことを確認するには、まずログ管理をfinerに設定します。
newrelic.yml構成ファイルを編集して、log_levelプロパティを変更します。log_level: finerアプリケーションの起動・再起動を行います。
読み取りが成功した場合、 logs/newrelic_agent.logは次のようなステートメントでこれを示します。
Reading custom extension file /path/to/file.xmllogs/newrelic_agent.logにステートメントがない場合、XML ファイルは見つかりませんでした。XML ファイルの場所を確認し、New Relic プロセスがファイルへの読み取りアクセス権を持っていることを確認してください。
複数のXMLファイル
1つのXMLファイルを使用することが望ましいですが、複数のカスタムXMLファイルを使用することもできます。ファイル内の拡張子が一意であれば、これらのファイルはすべてインストゥルメントされます。
- 2つのカスタムXMLファイルに同じ拡張子の名前が含まれていた場合、バージョンの高い方が実装され、もう一方は無視されます。
- 2つのファイルの名前とバージョンが同じであれば、エージェントが最初に読み込んだファイルが実装され、もう一方のファイルは無視されます。
XMLとYAML
2.10.0より前のバージョンでは、カスタムインストゥルメンテーションにYAMLファイルを使用できました。これらのレガシーYAMLファイルは引き続きサポートされています。ただし、新規ユーザーはカスタム・インストゥルメンテーションにXMLファイルを使用する必要があります。
Legacy users: 同じ拡張子名を持つ YAML ファイルと XML ファイルの両方が存在する場合は、XML ファイルのみがインストゥルメントされます。 YAML ファイルは無視されます。 YAML ファイルと XML ファイルの両方をインストゥルメントする場合は、各ファイルに異なる拡張子名を付けます。
XMLファイルの例
カスタムインスツルメンテーションXMLファイルの例については、 Java XML examples を参照してください。