REST API を使用した InterSystems IRIS の監視

メトリックの説明

メトリックはテキストベース形式で返されます。これについては、Prometheus のドキュメントの "Exposition Formats" ページ (https://prometheus.io/docs/instrumenting/exposition_formats/Opens in a new tab) で説明されています。各メトリックは 1 行に記述し、名前と値は 1 つのスペースで区切ります。

以下のテーブルに、InterSystems IRIS メトリックを表示します。ここでは、読みやすくするために、ラベルがあるメトリック名には改行を入れています。

相互運用メトリック

前のセクションで説明したメトリックの他にも、InterSystems IRIS インスタンスでは、アクティブな相互運用プロダクションOpens in a new tabに関するメトリックを記録し、それを /metrics エンドポイントの出力に含めることもできます。このような相互運用メトリックの記録は、既定で無効になっています。これを有効にするには、監視する相互運用プロダクションごとに以下の手順を実行する必要があります。

1. 監視するプロダクションを実行している InterSystems IRIS インスタンスのターミナル・セッションを開きます。必要に応じて、以下のコマンドを実行して、プロダクションに関連付けられているネームスペースに切り替えます。

   set $namespace = "[interopNS]"
   

   

   [interopNS] はネームスペース名です。

2. ターミナルで以下のコマンドを実行して、現在のネームスペース内のアクティブなプロダクションに対してメトリックのコレクションを有効にします (SAM は、インターシステムズのモニタリング・ソリューションである System Alerting and MonitoringOpens in a new tab を指します)。

   do ##class(Ens.Util.Statistics).EnableSAMForNamespace()
   

   
   Note:

   ネームスペースに対してメトリックの記録は有効になっているが、対応するプロダクションがアクティブでない場合、/metrics エンドポイントはいずれのメトリックも返しません。

   Ens.Util.Statistics クラスには、/metrics エンドポイントの出力をカスタイマイズするためのメソッドが用意されています。例えば、DisableSAMIncludeHostLabel メソッドを呼び出すと、集約メトリックがホストごとに別々に提供されるのではなく、プロダクション全体の集約メトリックが提供されます。

   この手順の完了後に使用できるメトリックについては、以下のテーブル "基本的な相互運用メトリック" を参照してください。

3. プロダクションのアクティビティ量に関する追加のメトリックを収集する場合は、ターミナルを使用して、対応するネームスペースで、クラスメソッド Ens.Util.Statistics.EnableStatsForProduction を呼び出すことでアクティビティ・モニタリングを有効にする必要があります。また、プロダクションに、Ens.Activity.Operation.Local ビジネス・オペレーションを追加することも必要です。このプロセスの詳細は、"アクティビティ量の監視" ページの "アクティビティ・モニタリングの有効化" を参照してください。

   この手順の完了後に使用できる追加メトリックについては、以下のテーブル "アクティビティ量メトリック" を参照してください。

4. EnsLib.HTTP.OutboundAdapter または EnsLib.SOAP.OutboundAdapter を使用する相互運用 Web クライアントについて、追加の HTTP 転送メトリックを収集する場合は、以下の手順を実行して、対応するビジネス・オペレーションの HTTP メトリックのレポートを有効にする必要があります。

   1. 監視する Web クライアントを含む InterSystems IRIS インスタンスの管理ポータルを開きます。

   2. [相互運用性] を選択して、Web クライアントを含むネームスペースを選択します。

   3. [構成]→[プロダクション] を選択して、[プロダクション構成] ページを開きます。

   4. HTTP または SOAP 送信アダプタを使用するオペレーションを選択します。

   5. [プロダクション設定]→[設定] パネルの [アラートの制御] セクションで、[SAMにメトリックを提供] チェックボックスにチェックを付けます。

   6. [適用] を選択して、設定を保存します。

   この手順の完了後に使用できる追加メトリックについては、以下のテーブル "HTTP メトリック" を参照してください。

   Note:

   現在、HTTP 転送メトリックは、([プロセス内] スタイルではなく) [キュー] スタイルを使用してアクターを呼び出すビジネス・オペレーションについてのみ収集されます。これらの呼び出しスタイルの相違についての詳細は、"ビジネス・オペレーションの定義" の "ビジネス・オペレーション・クラスの定義" を参照してください。

以下のテーブルに、InterSystems IRIS 相互運用メトリックを示します。ここでは、読みやすくするために、ラベルがあるメトリック名には改行を入れています。

アプリケーションのメトリックの作成

/metrics エンドポイントによって返されたメトリックにカスタム・アプリケーションのメトリックを追加するには、以下の手順に従います。

1. %SYS.Monitor.SAM.AbstractOpens in a new tab を継承する新規クラスを作成します。

2. PRODUCT パラメータをアプリケーションの名前として定義します。InterSystems IRIS メトリックに予約されている iris 以外の任意の値を指定できます。

3. GetSensors()Opens in a new tab メソッドを実装して、必要なカスタム・メトリックを次のように定義します。

   • このメソッドには、SetSensor()Opens in a new tab メソッドへの 1 つ以上の呼び出しが含まれている必要があります。このメソッドは、アプリケーション・メトリックの名前と値を設定します。Prometheus および InterSystems SAM との互換性を確保するために、値は整数または浮動小数点数にする必要があります。

     オプションでメトリックのラベルを定義できますが、定義する場合は常に、その特定のメトリックのラベルを定義する必要があります。

     Note:

     メトリックおよびラベル名の選択のベスト・プラクティスについては、Prometheus のドキュメントの "Metric and Label Naming" を参照してください (https://prometheus.io/docs/practices/naming/Opens in a new tab)。

   • 成功すると、このメソッドは $$$OK を返します。

   Important:

   GetSensors() の実装が低速であると、システム・パフォーマンスに悪影響を及ぼす可能性があります。GetSensors() の実装が効率的であることをテストして、タイムアウトや停止が発生する可能性のある実装は避けてください。

4. クラスをコンパイルします。以下に例を示します。

   /// Example of a custom class for the /metric API
   Class MyMetrics.Example Extends %SYS.Monitor.SAM.Abstract
   {
   
   Parameter PRODUCT = "myapp";
   
   /// Collect metrics from the specified sensors
   Method GetSensors() As %Status
   {
      do ..SetSensor("my_counter",$increment(^MyCounter),"my_label")
      do ..SetSensor("my_gauge",$random(100))
      return $$$OK
   }
   
   }

   

5. SYS.Monitor.SAM.ConfigOpens in a new tab クラスの AddApplicationClass()Opens in a new tab メソッドを使用して、カスタム・クラスを /metrics 構成に追加します。クラスの名前とそれが配置されているネームスペースを引数として渡します。

   例えば、ターミナルで %SYS ネームスペースから以下のように入力します。

   %SYS>set status = ##class(SYS.Monitor.SAM.Config).AddApplicationClass("MyMetrics.Example", "USER")
   
   %SYS>w status
   status=1
   

   

6. /api/monitor Web アプリケーションに、カスタム・メトリックにアクセスするために必要なアプリケーション・ロールがあることを確認します。アプリケーション・ロールの編集方法の詳細は、"アプリケーションの編集 ： [アプリケーションロール] タブ" を参照してください。

   この手順では、カスタム・メトリックに必要なデータへの /api/monitor アクセスを許可します。例えば、カスタム・メトリック・クラスが USER データベース (%DB_USER リソースによって保護されている) にある場合、/api/monitor に %DB_USER ロールを付与します。

7. ブラウザで http://<instance-host>:52773/api/monitor/metrics を指して、/metrics エンドポイントの出力を確認します (52773 は、既定の WebServer ポート)。以下のように、InterSystems IRIS メトリックの後に、定義したメトリックが表示されます。

   [...]
   myapp_my_counter{id="my_label") 1
   myapp_my_gauge 92
   

/metrics エンドポイントは、定義したカスタム・メトリックを返すようになります。InterSystems IRIS メトリックには接頭語 “iris_” が含まれるのに対し、カスタム・メトリックでは PRODUCT の値が接頭語として使用されます。