APMインサイト エージェント設定のオプション

このページでは、Webページのトランザクション追跡の設定チューニング法を説明します。設定はapminsight.confファイルで行います。ファイルがAPMインサイト エージェントのデプロイ先フォルダーにあることを確認してから作業してください。

以下、設定をまとめて説明します。

設定 説明 デフォルト値

application.name*
  • Applications Managerに表示する希望のアプリケーション名を指定してください。
  • お客さまアプリケーションが複数インスタンスあり、グループにまとめる場合は、アプリケーション名をすべてのインストール先APMインサイトのエージェント設定ファイルに設定する必要があります。

例：myonlineshopping.com

メモ：APMインサイトのJavaエージェントでは、アプリケーション名をapminsight.confファイルではなく、JVM引数でも指定できます。次のパラメーターを追加してください。

-Dapminsight.application.name=My Application

My Application

apm.host*
  • Applications Managerが稼働しているホストの名前です。
  • 入力したホスト名が無効や到達不能の場合、エージェントは「Connection Refused」の例外を投げ、正しいホスト名がapminsight.confに設定されるまでリトライを続けます。
  • 指定はホスト名でもIPv4アドレスでも可能です。

例：mymachine.mydomain.com

apm.protocol.https
  • Applications ManagerにデータをHTTPSで送る場合は、trueを指定します。
  • falseを指定すると、HTTPでの送信となります。

false

apm.port*
  • Applications ManagerのHTTPポートを指定します。apm.protocol.httpsがtrueの場合は、HTTPSポートを指定してください。
  • サービスが指定ポートで実行されていない場合、エージェントは「Connection Refused」例外を投げ、apminsight.confに正しいポートが入力されるまでリトライします。

例：9090

behind.proxy
  • エージェントをインストールしたアプリケーション サーバーへの接続に、プロキシを経由するか否かを指定してください。
  • trueの場合、エージェントからApplications Managerへのメトリック データ送信に、プロキシ認証情報の指定が必要となります。
  • behind.proxyをtrueにセットする場合、次のキーに値を指定してください。
    • proxy.server.host：プロキシ サーバーのホスト名
    • proxy.server.port：プロキシ サーバーのポート
    • proxy.auth.username：プロキシ サーバーのユーザー名
    • proxy.auth.password：プロキシ サーバーのパスワード

false

agent.server.port*
  • アプリケーション サーバーのHTTPリスニング ポートを指定してください。
  • 同じホストで、同じアプリケーション サーバーが複数稼働しているとき、インスタンスを区別するのに便利です。例：8080

apdex.threshold
  • Apdexスコア（Application Performance Index）はアプリケーションのパフォーマンスを測定し、0から1の間で示します。
  • 詳細情報はwww.apdex.orgを参照ください（英語）。
  • トランザクション応答時間のスコアに、Apdexしきい値より低いものがあれば、トランザクションは満足と判定されます（satisfied）。
  • トランザクション応答時間のスコアに、Apdexしきい値の4倍を超えるものがあれば、トランザクションは不満と判定されます（frustrated）。
  • Apdexしきい値とまったく同じか、満足と不満の間の場合は、容認と判定されます（tolerating）。

0.5（秒）

sql.capture.enabled
  • こちらを有効にすると、実行したSQLクエリをすべて確認します。
  • 無効の場合、データベース メトリックは収集しません。

true

transaction.trace.enabled
  • このオプションを有効にすると、スロウなトランザクションでトレース構築を実行します。
  • Applications Mangerが収集したトレースは、APMインサイト ページでトレース タブを選択すると、確認できます。

true

transaction.trace.threshold
  • 応答時間のスコアが、こちらで指定するしきい値を超えている場合は、トランザクションのトレースを収集します（transaction.trace.enabledをtrueにする必要があります）。
  • トレースは、トランザクションの挙動の分析やトラブルシュートに有用です。

2（秒）

transaction.trace.sql.parametrize
  • このオプションを有効にすると、スロウなトランザクションのトレースにあるSQLクエリは、すべてパラメーター表記となります（sql.capture.enabledとtransaction.trace.enabledをtrueにする必要があります）。
  • 無効の場合、実際のクエリ内容が、パラメーターの値とともに取得されます。
  • クエリ実行の際、クレジットカード番号やパスワードなど秘密パラメーターを利用している場合は、この機能を有効にするよう推奨します。

true

transaction.trace.sql.stacktrace.threshold
  • このオプションを有効にすると、実行したSQLクエリが、ここで指定するしきい値を超えた場合に、スタック トレースの収集を行います。

3（秒）

webtransaction.trace.input.params.record
  • WebへのGETリクエストとPOSTリクエストの全パラメーター取得を有効とする項目です。
  • 不要なパラメーターをスキップする婆AIは、webtransaction.trace.input.params.ignoreで指定してください。
  • 取得したパラメーターは、トレース タブでトランザクションを選ぶと表示されます。

false

webtransaction.trace.input.params.ignore
  • パスワードやPINなど、Webリクエストのパラメーターを指定して取得対象から外す場合は、このキーにパラメーター名を指定してください。
  • 複数エントリは、カンマ（,）区切りで指定します。値は大文字・小文字を区別します。
  • 何も指定しなければ、リクエスト パラメーターをすべて記録します。

password、authKey

webtransaction.naming.use.requesturl

  • WebトランザクションのURLを完全に取得するには、 webtransaction.naming.use.requesturl=trueをapminsight.confファイルに記載してください。こちらは隠し設定で、デフォルト値はfalseになっています。

webtransaction.encoding.charset

  • アプリケーション データの文字コードを指定します。たとえば、apminsight.confファイルにwebtransaction.encoding.charset=Windows-1252と記載すれば、Windows用の西ヨーロッパ言語です。デフォルトではUTF-8を指定してあります。

transaction.skip.listening
  • 指定URLパターンのWebトランザクションを、追跡の対象から外します。
  • 複数エントリは、カンマ（,）で区切って下さい。
  • 例：transaction.skip.listening=*.jpegの指定で、.jpegで終わるトランザクションはスキップします。

*.css、*.js、*.gif、*.jpg、*.jpeg、*.bmp、*.png

transaction.tracking.request.interval
  • サンプリング係数を指定します。20にすれば、同一種別のリクエストは20個ごとに取得します（1番名、21番目、41番目…）。
  • リクエスト番号は、1分ごとにリセットされます。

1（リクエスト）

include.components
  • デフォルトでは、APMインサイトはトランザクションを、Struts、サーブレット、MySQLなどのコンポーネントにグループ分けします。
  • カスタム コンポーネントの追加には、パッケージ名を「packagename/.*:Component_Name」形式で指定してください。
  • 指定したパッケージの下にあるパッケージとクラスは、すべて、特定コンポーネントにまとめられます。
  • 例：「include.components=com/test/custom/.*:CUSTOM」を指定すると、「com/test/custom/」パッケージにある全パッケージとクラスが、コンポーネント名「CUSTOM」にまとめられます。
  • 複数エントリは、カンマ（,）で区切って下さい。

メモ：パッケージ名を指定すると、デフォルトでインストルメンテーションの対象となり、custom_instrumentation.confでの同じ設定は不要です。

apminsight.log.dir
  • APMインサイト ログの保存先ディレクトリ パスを表します。
  • パス区切りにはスラッシュを利用します（/）。
  • 例：
  • 指定が間違っていたり、ディレクトリを作成できなかったりする場合は、エージェントjarファイルのあるディレクトリをデフォルトで選択します。

apminsight.log.level
  • APMインサイト エージェントが情報を記録する際のログ レベルを指定します。
  • SEVERE、WARNING、INFO、FINEから選択ください。

INFO（レベル）

autoupgrade.enabled
  • エージェントの最新バージョンを、自動ダウンロードとインストールする設定項目です。

false

無効値が指定された場合、APMインサイトはデフォルト値を利用します。以下に示す項目以外は、実行中の変更が可能です。

  • application.name
  • apm.host
  • apm.port
  • agent.server.port
  • apminsight.log.dir
  • apminsight.log.level（Javaエージェントの場合。.NETエージェントでは、このプロパティも実行時に変更可能）
メモ：
「*」のマークがあるものは、必須項目です。必須項目が1つでも指定されていない場合、エージェントは初期化や起動ができません。ただし、エージェント デプロイ先のアプリケーション サーバーは、正常起動します。

Apdexしきい値の詳細情報は、https://apdex.org/overview.htmlで確認ください。

バックグラウンド トランザクションの追跡

Webアプリケーションでは表の通信とは別に、バックグラウンドでメンテナンス、スケジュール、メッセージングなどを実行していることが多々あります。APMインサイトはこれらのトランザクションも取得し、ダッシュボードのバックグラウンド タブで表示します。

メモ：この機能は、.NETとJavaのエージェントでのみサポートしています。

バックグラウンド トランザクションの追跡には、background_transaction.confファイルでの有効化が必要です。バックグラウンド トランザクションの設定法を、下に説明します。

設定 説明 デフォルト値
bgtransaction.tracking.enabled
  • このオプションを有効にすると、APMインサイト エージェントはバックグラウンド トランザクションの追跡を始めます。
  • HTTP以外の通信はすべて、バックグラウンド トランザクションと見なします。
 true
bgtransaction.trace.enabled
  • エージェントでスロウなバックグラウンド トランザクションのトレース収集を有効にするキーです（bgtransaction.tracking.enabledをtrueにする必要があります）。
 true

bgtransaction.trace.threshold
  • 応答時間がしきい値を超えたバックグラウンド トランザクションで、トレース収集を行います（bgtransaction.trace.enabledをtrueにする必要があります）。
 5（秒）
bgtransaction.tracking.request.interval
  • バックグラウンド トランザクションのサンプル係数です。
  • 値を1にすると、エージェントはすべてのトランザクションを追跡します。nにセットした場合は、同一種別のトランザクションを、n個につき1つ追跡します。
 Javaでは1、.NETでは5

 

メモ：
  • これらの値は、Javaエージェントでは実行時の変更ができません。変更を有効にするには、サーバー再起動が必要です。
  • .NETエージェントでは再起動不要で、値は実行中に更新されます。

カスタム インストルメンテーション

APMインサイト エージェントは、Webコンポーネントやフレームワークから事前定義のあるクラスを組み込み、アプリケーションを把握することができます。お客さま指定クラスの組み込みも可能です。カスタム インストルメンテーションを利用すれば、アプリケーションで利用している特定機能やモジュールの追跡が容易となります。

Javaエージェントでは、2通りの方法で、アプリケーションのカスタム インストルメンテーションができます。

1：設定ファイルを利用する

希望のクラスを組み込むには、「custom_instrumentation.conf」ファイルで以下の形式に従い、クラス名を指定してください。

Fully/qualified/ClassName : Methods to be instrumented

複数メソッドを指定するには、カンマ（,）区切りにしてください。メソッド名を指定しない場合は、指定クラスにあるすべてのメソッドを組み込みます。If there exists, overloading methods that needs to be instrumented, all overloaded methods will be instrumented. クラスは改行区切りで1つずつ指定してください。

例：

  1. a/b/c/CustomClass : methodA, methodB
  2. a/b/c/CustomClass：

パッケージにあるすべてのクラスを組み込む場合、パッケージ名を下のとおり記載します。

package_name/.*：

例：

  1. a/b/c/.* :

パッケージ全体の指定は推奨しません。パッケージにある全クラスの全メソッドを組み込むこととなり、CPUやメモリに余分な負荷がかかります。多くのメソッドはパフォーマンス監視と関係が薄く、トレースが余分に長くなります。ただし、コードの流れを把握するのが目的であれば、パッケージ全体の指定も可能です。

メモ：変更を有効にするには、アプリケーション サーバーの再起動が必要です。

2：Javaアノテーションを利用する

お客さまアプリケーションのクラスやメソッドは、Javaアノテーションでも、カスタム インストルメンテーションが可能です。Javaアノテーションの利用で、トランザクションへのカスタム名の定義や、カスタム コンポーネントの割り当てが可能となります。

メモ：この機能は、エージェントのバージョン2.2から利用できます。

要件

  • apminsight-javaagent.zipファイルをダウンロードしてください。エージェントjarや関連ファイルにくわえ、apminsight-javaagent-api.jarが入っています。
  • apminsight-javaagent-api.jarファイルをプロジェクト ビルドのパスに追加してください。jarファイル エクスポートの際には、アプリケーションのライブラリも必要です。

カスタム インストルメンテーでは、2つのアノテーションを使います。

ApmTracker：トレースに組み込むあらゆるクラスやメソッド使えます。

ApmRootTracker：トランザクション実行の開始地点となるメソッドで使います。

ApmTracker

このアノテーションはクラスにもメソッドにも利用できます。クラスで利用すると、内部の全メソッドに属性が適用されます。アノテーションのオーバーライドは、メソッド横断で実行されます。

属性

component: デフォルト値はPOJOです（Plain Java Object）。

アノテーションする要素にコンポーネント名を定義します。任意属性です。

例

ケース1：クラスでの利用例

@ApmTracker
public class Category {
        ...
}
ケース2：

@ApmTracker(component="payment"
        public class PaymentProcessor {
        ...
}

ケース3：メソッドでの利用例

public class Product {
        @ApmTracker
        public int getPrice(String product, String brand) {
                ...
        }
...

        @ApmTracker(component="FetchBrand")
                private List fetchAllBrandsList(String product) {               
                ...
        }
}

ApmRootTracker

このアノテーションは、メソッドでのみ利用できます。アノテートしたメソッドが、サーバーのトランザクション処理中に最初に実行される際、トランザクションはtxnName属性で指定した名前に置き換わります。それ以外の場合は、通常のメソッド呼び出しの扱いとなり、トレースにも入ります。

属性

txnName：必須属性です。

この属性の値は、ApmRootTrackerがアノテートしたメソッドを実行する際、トランザクションの命名に利用されます。

component：デフォルト値はPOJOです。

アノテーションする要素にコンポーネント名を定義します。任意属性です。

例

public class AppService {
        @ApmRootTracker(txnName="Service-Initialisation")
        public void init() {
            ...
        }
}

類似トランザクションのグループ化

トランザクション名の動的変化は多くのアプリケーションで日常的に発生しており、アプリケーション追跡が困難となる要因です。動的トランザクションでは、Webアプリケーションは単一URLを利用しつつも、実行のたび一意の英数字の識別子をURLに付加するため、Webトランザクション名自体が変わってしまいます。このようなURLを個々に追跡するのは、超人的作業です。類似トランザクションをグループにまとめれば、これら動的トランザクションは、実際のURLに一元化して監視できます。

.NETエージェントの設定手順

設定の編集UIを開き、トランザクション マージ タブを選択、マージするパターンを手動での手順3に従って指定します。

手動で行う場合は、次の手順で操作します。

  1. エージェント インストール後、APMインサイト.NETエージェントへ移動してください。
  2. DotNetAgentフォルダーを開きます。
  3. transaction_merge_patterns.confを開き、下のサンプルのようにパターンを追加します。
    • aspsite/account/~=account：このパターンは、aspsite/account/で始まるトランザクションにマッチし、accountへのリネームを行います。
    • aspsite/~/basicdetails=basicdetails：このパターンは、aspsite/で始まり/basicdetailsで終わるトランザクションにマッチし、basicdetailsへのリネームを行います。
    • ~/educationdetails=educationdetails：このパターンは、/educationdetailsで終わるトランザクションにマッチし、educationdetailsへのリネームを行います。
  4. 編集後は、transaction_merge_patterns.confファイルを、次の場所に貼り付けてください。
    • %WINDIR%ProgramData\DotnetAgent（64ビット バージョンの場合）：Windows Server 2003では、対応するパスは次の通りです。%WINDIR%Documents and Settings\All Users\Application Data\DotNetAgent
    • %WINDIR%ProgramData\DotnetAgent（32ビット バージョンの場合）：Windows Server 2003では、対応するパスは次の通りです。%WINDIR%Documents and Settings\All Users\Application Data\DotNetAgent
    • 監視が複数ある場合は、アプリケーション用のサブフォルダーごとに、設定ファイルを貼り付ける必要があります。
  5. 設定ファイルではいつでも、パターンを追加、削除、コメントが可能です。
メモ：変更はサービス再起動なしで有効になります。数分間お待ちください。

Javaエージェントの設定手順

  • エージェントを設定したアプリケーション サーバーをシャットダウンします。
  • apminsight.confがあるディレクトリに、新規ファイル「transaction_merge_patterns.conf」を作成します。
  • ファイルをテキスト エディターで開き、下記の構文で、キー・バリューのペアを指定してください。
  • URL=new_name_to_be_assigned（キーは正規表現をサポート）
  • アプリケーション サーバーの起動後は、上記パターンでトランザクションのマージが行われます。

例：

次のトランザクションURLがあるものとします。

ebay/shop/user/4534634 ebay/shop/user/1380284
ebay/shop/0278734/chocolate/orion
ebay/shop/0278734/chocolate/snickers
ebay/shop/3847553/stationary/pencil
ebay/shop/9734944/stationary/pen

transaction_merge_patterns.confで以下のように指定してください。

ebay/shop/.*/chocolate/.*=ebay/shop/chocolate
ebay/shop/.*/stationary/.*=ebay/shop/stationary
ebay/shop/user/.*=ebay/shop/users

Rubyエージェントの設定手順

  1. お客さまアプリケーションで、apminsight.confファイルがあるディレクトリに、新規ファイル「transaction_merge_patterns.conf」を作成します。
  2. ファイルをテキスト エディターで開き、下記の構文で、キー・バリューのペアを指定してください。
    URL=new_name_to_be_assigned（キーは正規表現をサポート）
  3. Railsサーバーの再起動後は、上記パターンでトランザクションのマージが行われます。

例：

ruby/shop/item/laptops/.*=shop/laptops
ruby/shop/item/.*/dell/.*=shop/item/dell
.*/cart/purchase=shop/purchase