New Relic JavaエージェントAPIを使うことで、APM Javaエージェントの機能のコントロール、カスタマイズ、そして拡張が可能です。このAPIは、以下の内容によって構成されています。
com.newrelic.api.agent.NewRelic
クラス上の静的メソッド- カスタムインストゥルメンテーションを実装するための@Trace アノテーション
- 追加の機能を提供するAPIオブジェクトの階層
Javaアプリケーションのカスタムインストゥルメンテーションをセットアップして、より精細なデータを収集するには、このAPIを使用します。このAPIの詳しい情報に関しては、GitHub上のJavadoc一覧を参照してください。
カスタムインストゥルメンテーションをセットアップできるもう1つの手段として、XMLインストゥルメンテーションを使用する方法もあります。XMLを使用した方が簡単な上、アプリケーションのコード修正が必要ありませんが、これにはJavaエージェントAPIのような完全な機能は備わっていません。
重要
APIを使用するにあたって最良の結果を出すには、Javaエージェントのリリースが最新版であることを確認してください。例で使用されているAPIには、Javaエージェント6.4.0以降が必要です。
入手可能なすべてのNew Relic APIを見るには、API入門を参照してください。
APIの使用
APIクラスにアクセスするには、アプリケーションのクラスパスにnewrelic-api.jar
を追加してください。このjarは、New Relic Javaエージェントのインストレーションzip
ファイル内にあります。APIは、Javaエージェントが実行中でないときにコールできます。APIメソッドは単なるスタブで、実装はJavaエージェントがクラスを読み込んだときに追加されます。
トランザクション
アプリケーションでTransactions
をインストゥルメントするには、以下のAPIを使用してください。
以下を行う場合... | これを使用 |
---|---|
New Relicが | 報告されるべき作業を含むメソッドで |
New Relicが自動的にトレースしないメソッドの経過時間を取得する | 経過時間を計測したいメソッドで |
現在の | |
現在の | |
カスタムアトリビュートを | |
| |
アプリケーションのApdexスコアの計算時に |
非同期の作業をインストゥルメントする
詳しくは、非同期アプリケーション用のJavaエージェントAPIを参照してください。
以下を行う場合... | これを使用 |
---|---|
非同期メソッドが既存の | |
現在のスレッド上の | |
現在の | |
| |
|
ディストリビューティッド(分散)トレーシングAPIの使用
これらのAPIでは、ディストリビューティッド(分散)トレーシングを有効化する必要があります。ディストリビューティッド(分散)トレーシングのすべての設定オプションについては、Javaエージェントの設定をご覧ください。
ディストリビューティッド(分散)トレーシングでは、リクエストが分散システムを経由するパスを見ることができます。以下のコールを利用してディストリビューティッド(分散)トレーシングを実装する一般的な案内については、ディストリビューティッド(分散)トレーシングAPIの使用を参照してください。動作するAPIを確認するには、KafkaでのJavaエージェントのディストリビューティッド(分散)トレーシングAPIの使用をご覧ください。
重要
エージェントのバージョン6.4.0では、6.1.0で導入されたaddCustomAttribute()
を除いて、以下のディストリビューティッド(分散)トレーシングAPIが導入されました。非推奨のAPIの代わりに、これらのAPIを使用することを強く推奨します。
以下を行う場合... | これを使用 |
---|---|
ディストリビューティッド(分散)トレーシングのヘッダーを作成して、 | 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。 |
呼び出し元サービスから送信されたディストリビューティッド(分散)トレーシングヘッダーを受け入れて、ディストリビューティッド(分散)トレースでこれらのサービスをリンクします。 | 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。 |
受信または送信メッセージのタイプ固有のヘッダー。提供されている | |
ディストリビューティッド(分散)トレーシングのヘッダーを受け入れる際のトランスポートタイプを定義するための列挙体の定数を提供するユーティリティクラス。 | |
分散トレースのカスタム属性を |
|
注意
エージェントのバージョン6.4.0では、以下のディストリビューティッド(分散)トレーシングAPIが非推奨になり、上の表のAPIで置き換えられました。エージェントをアップグレードして、非推奨APIの代わりに新しいAPIを使用することを強く推奨します。
以下を行う場合... | これを使用 |
---|---|
呼び出したサービスに送るペイロードを作成する。 | 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。 注意エージェント6.4.0の時点で非推奨になったAPI |
最初のサービスから送られたペイロードを受け取る。その結果、これらのサービスを1つのトレース内で結びつけることができる。 | 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。 注意エージェント6.4.0の時点で非推奨になったAPI |
サービス接続に使用するペイロード。 |
注意エージェント6.4.0の時点で非推奨になったAPI |
サービス接続に使用するペイロード。 |
注意エージェント6.4.0の時点で非推奨になったAPI |
クロスアプリケーショントレーシング(CAT)の使用
外部コールを追跡し、 クロスアプリケーショントレーシングを追加するには、以下のAPIを使用します。
以下を行う場合... | これを使用 |
---|---|
プロプライエタリRPCトランスポートなど、New Relicがデフォルトでサポートしていないカスタムトランスポートチャネルを通してトレースする |
|
( |
|
JavaエージェントAPIの |
|
New Relicによってインストゥルメントされている外部HTTPまたはJMSサービスと通信している際に、クロスアプリケーショントレーシングを有効化して追加する |
|
自動でサポートされないアプリケーションサーバーやディスパッチャーに対しタイミングを追加する。 |
|
New Relic APIクラスへのリファレンスを取得する
他のタスクでは、New Relicのエージェント
オブジェクトが必要になります。エージェント
オブジェクトは、以下の機能を提供する複数のオブジェクトを公開します:
以下を行う場合... | これを使用 |
---|---|
現在の | |
非同期作業をリンクする | |
起動して、 | |
現在トレースされているメソッドへのリファレンスを入手する。 | |
| |
| |
カスタムメトリックスに対するアグリゲータへのリファレンスを入手する。 | |
カスタムイベントを記録するために、 |
追加のAPI機能
以下のAPIは、アプリケーションサーバーの情報設定、エラー報告、ページロードタイミングの情報追加、カスタムメトリックスの記録、そしてInsightsへのカスタムイベントの送信など、追加の機能を提供します。
以下を行う場合... | これを使用 |
---|---|
アプリケーションサーバーやディスパッチャーに対してポート、名前、バージョン情報、もしくはJVMに対してインスタンス名を明示的に設定する。 | |
New Relicが自動的に報告しないエラーを報告する。 | トランザクション内では、 |
New Relicが自動的にヘッダに追加しない | |
カスタムメトリックスを作成および蓄積する。 |
|
カスタムイベントを記録 |
または、
|
その他のAPI使用例
APIの使用における詳しいコード例に関しては、以下のカスタムインストゥルメンテーションに関するNew Relicのドキュメントを参照してください。
- 外部コール、クロスアプリケーショントレース、メッセージング、データストア、Webフレームワーク
- クロスアプリケーショントレーシングと外部データストアコール
- アノテーション付きのカスタムインストゥルメンテーションを使うアプリケーション
- カスタムインストゥルメンテーション フレームワークAPI
- 不要なインストゥルメンテーションの防止
- カスタムアトリビュートの挿入
- カスタムイベントの挿入
- カスタムメトリックスの収集
その他のヘルプ
さらに支援が必要な場合は、これらのサポートと学習リソースを確認してください:
- Explorers Hubを参照して、コミュニティから支援を受け、ディスカッションに参加してください。
- 当社のサイトで回答を見つけ、サポートポータルの使用方法について学びます。
- Linux、Windows、およびmacOSのトラブルシューティングツールであるNew Relic Diagnosticsを実行します。
- New Relicのデータセキュリティとライセンスドキュメントを見直してください。