• /
  • ログイン

JavaエージェントAPIの使用ガイド

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がTransactionを自動的に作成しない場合に作成する

報告されるべき作業を含むメソッドで@Trace(dispatcher = true)。このアノテーションを既存トランザクションのコンテキスト内のメソッドで使用した場合、新たなトランザクションは開始されず、このメソッドを既存トランザクションに含めることになります。

New Relicが自動的にトレースしないメソッドの経過時間を取得する

経過時間を計測したいメソッドで@Trace()

現在のTransactionの名前を設定する

NewRelic.setTransactionName(...)

現在のTransactionのレスポンスタイムに対してタイマーを開始し、作成するTransactionOtherトランザクションとしてではなく、Webトランザクションとして報告させる

NewRelic.setRequestAndReponse(...)

カスタムアトリビュートTransactionsTransactionEventsに追加する

NewRelic.addCustomParameter(...)

TransactionがNew Relicに報告されるのを防ぐ

NewRelic.ignoreTransaction()

アプリケーションのApdexスコアの計算時にTransactionを除外する

NewRelic.ignoreApdex()

非同期の作業をインストゥルメントする

詳しくは、非同期アプリケーション用のJavaエージェントAPIを参照してください。

以下を行う場合...

これを使用

非同期メソッドが既存のTransactionにリンクされている場合、そのメソッドをトレースする...

@Trace(async = true)

現在のスレッド上のTokenに関連するTransactionをリンクする...

Token.link()またはToken.linkAndExpire()

現在のTransactionに関連するTokenを期限切れにする...

Token.expire()

Segmentの時間計測を停止し、その親Transactionの一部として報告させる

Segment.end()

Segmentの時間計測を停止し、その親Transactionの一部として報告させない

Segment.ignore()

ディストリビューティッド(分散)トレーシングAPIの使用

これらのAPIでは、ディストリビューティッド(分散)トレーシングを有効化する必要があります。ディストリビューティッド(分散)トレーシングのすべての設定オプションについては、Javaエージェントの設定をご覧ください。

ディストリビューティッド(分散)トレーシングでは、リクエストが分散システムを経由するパスを見ることができます。以下のコールを利用してディストリビューティッド(分散)トレーシングを実装する一般的な案内については、ディストリビューティッド(分散)トレーシングAPIの使用を参照してください。動作するAPIを確認するには、KafkaでのJavaエージェントのディストリビューティッド(分散)トレーシングAPIの使用をご覧ください。

重要

エージェントのバージョン6.4.0では、6.1.0で導入されたaddCustomAttribute()を除いて、以下のディストリビューティッド(分散)トレーシングAPIが導入されました。非推奨のAPIの代わりに、これらのAPIを使用することを強く推奨します。

以下を行う場合...

これを使用

ディストリビューティッド(分散)トレーシングのヘッダーを作成して、Headersデータ構造に挿入します。このAPIは、newrelicヘッダーとW3C Trace Contextヘッダー(traceparenttracestate)の両方を挿入します。明示的にnewrelicヘッダーを除外するようにエージェントが設定されている場合は例外です。

Transaction.insertDistributedTraceHeaders(Headers)

現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。

呼び出し元サービスから送信されたディストリビューティッド(分散)トレーシングヘッダーを受け入れて、ディストリビューティッド(分散)トレースでこれらのサービスをリンクします。

現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。

受信または送信メッセージのタイプ固有のヘッダー。提供されているHeadersの実装には、ConcurrentHashMapHeadersを使用します。

ディストリビューティッド(分散)トレーシングのヘッダーを受け入れる際のトランスポートタイプを定義するための列挙体の定数を提供するユーティリティクラス。

分散トレースのカスタム属性SpanEvents に追加

NewRelic.getAgent().getTracedMethod().addCustomAttribute(...)

注意

エージェントのバージョン6.4.0では、以下のディストリビューティッド(分散)トレーシングAPIが非推奨になり、上の表のAPIで置き換えられました。エージェントをアップグレードして、非推奨APIの代わりに新しいAPIを使用することを強く推奨します。

以下を行う場合...

これを使用

呼び出したサービスに送るペイロードを作成する。

現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。

注意

エージェント6.4.0の時点で非推奨になったAPI

最初のサービスから送られたペイロードを受け取る。その結果、これらのサービスを1つのトレース内で結びつけることができる。

現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。

注意

エージェント6.4.0の時点で非推奨になったAPI

サービス接続に使用するペイロード。text()コールが、ペイロードのJSON文字列表現を返す。

DistributedTracePayload.text()

注意

エージェント6.4.0の時点で非推奨になったAPI

サービス接続に使用するペイロード。httpSafe()コールが、base64でエンコードされたペイロードのJSON文字列表現を返す。

DistributedTracePayload.httpSafe()

注意

エージェント6.4.0の時点で非推奨になったAPI

クロスアプリケーショントレーシング(CAT)の使用

外部コールを追跡し、 クロスアプリケーショントレーシングを追加するには、以下のAPIを使用します。

以下を行う場合...

これを使用

プロプライエタリRPCトランスポートなど、New Relicがデフォルトでサポートしていないカスタムトランスポートチャネルを通してトレースする

Transactionを使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

TracedMethodのメトリック名やロールアップメトリック名を表示または変更する

OtherTransaction/allなどのロールアップメトリック名は特定のトランザクションに限定されておらず、すべてのバックグラウンドトランザクションを表しています。)

TracedMethodを使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

JavaエージェントAPIの@Traceアノテーションを使って、トレースされている外部HTTPサービス、データベースサーバー、メッセージキュー、またはその他の外部リソースへのコールを報告する

ExternalParametersビルダを使用して作成された引数をTracedMethod.reportAsExternal(...)に渡す。

TracedMethodを使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

New Relicによってインストゥルメントされている外部HTTPまたはJMSサービスと通信している際に、クロスアプリケーショントレーシングを有効化して追加する

TracedMethod.addOutboundRequestHeaders(...)TracedMethod.reportAsExternal(...)

TracedMethodを使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

自動でサポートされないアプリケーションサーバーやディスパッチャーに対しタイミングを追加する。

Transaction.setRequest(...)、Transaction.setResponse(...)、またはNewRelic.setRequestAndResponse(...)、およびTransaction.markResponseSent()

Transactionを使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

New Relic APIクラスへのリファレンスを取得する

他のタスクでは、New Relicのエージェントオブジェクトが必要になります。エージェントオブジェクトは、以下の機能を提供する複数のオブジェクトを公開します:

以下を行う場合...

これを使用

現在のTransactionへのリファレンスを取得する

NewRelic.getAgent().getTransaction()

非同期作業をリンクするTokenを取得する

起動して、Segmentへのリファレンスを取得する

現在トレースされているメソッドへのリファレンスを入手する。

NewRelic.getAgent().getTracedMethod()

Agentロガーへのリファレンスを取得する

NewRelic.getAgent().getLogger()

Agentの設定へのリファレンスを取得する

NewRelic.getAgent().getConfig()

カスタムメトリックスに対するアグリゲータへのリファレンスを入手する。

NewRelic.getAgent().getAggregator()

カスタムイベントを記録するために、Insightへのリファレンスを取得する

NewRelic.getAgent().getInsights()

追加のAPI機能

以下のAPIは、アプリケーションサーバーの情報設定、エラー報告、ページロードタイミングの情報追加、カスタムメトリックスの記録、そしてInsightsへのカスタムイベントの送信など、追加の機能を提供します。

以下を行う場合...

これを使用

アプリケーションサーバーやディスパッチャーに対してポート、名前、バージョン情報、もしくはJVMに対してインスタンス名を明示的に設定する。

New Relicが自動的に報告しないエラーを報告する。

NewRelic.noticeError(...)

トランザクション内では、noticeErrorへの最初の呼び出しが優先されます。トランザクションごとに1つのエラーのみが報告されます。

New Relicが自動的にヘッダに追加しないTransactionsに対するブラウザのページロードタイミングを追加する

カスタムメトリックスを作成および蓄積する。

NewRelic.recordMetric(...).recordResponseTimeMetric(...)、または.incrementCounter(...)

カスタムイベントを記録

Insights.recordCustomEvent(...)

または、NewRelic.addCustomParameter(...)を使用して、New Relic定義のTransactionEventタイプにカスタムアトリビュートを追加する。

Insightを使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

その他のAPI使用例

APIの使用における詳しいコード例に関しては、以下のカスタムインストゥルメンテーションに関するNew Relicのドキュメントを参照してください。

その他のヘルプ

さらに支援が必要な場合は、これらのサポートと学習リソースを確認してください:

問題を作成するこのページを編集する
Copyright © 2020 New Relic Inc.