REST を介した InterSystems IRIS の監視

メトリックはテキストベース形式で返されます。これについては、Prometheus のドキュメント (https://prometheus.io/docs/instrumenting/exposition_formats/Opens in a new tab) で説明されています。各メトリックは 1 行に記述し、名前と値は 1 つのスペースで区切ります。一意の各メトリックの前に # HELP および # TYPE コメント行が付けられます (https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-informationOpens in a new tab で説明されています)。該当する場合、InterSystems IRIS には # UNIT コメント行も含められます。このコメントは、メトリックに使用される単位を指定します。これらのコメント行も提供するには、カスタム・アプリケーション・メトリックを構成します。

以下のテーブルに、InterSystems IRIS メトリックとセンサ・グループを示します。センサ・グループの使用の詳細は、ExcludeMetricsOpens in a new tab プロパティに関する説明を参照してください。

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

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

   set $namespace = "[interopNS]"
   

   

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

2. ターミナルで以下のコマンドを実行して、現在のネームスペース内のアクティブなプロダクションに対してメトリックのコレクションを有効にします。

   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 の追加の HTTP 転送メトリックを収集する場合は、以下の手順を実行して、対応するビジネス・オペレーションの HTTP メトリックのレポートを有効にします。

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

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

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

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

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

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

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

   Note:

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

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

以下のテーブルに示すメッセージ保存メトリックは、プロダクション・データが適切に削除されているかどうかを判断するのに役立ちます。これらのメトリックは、Ens.SAM.GeneralMetricsOpens in a new tab クラスの Collect() メソッドによって集計されます。これは、直接呼び出すか、"相互運用性メッセージ保存メトリックの収集" タスクである Ens.Util.Tasks.MonitorMetricsOpens in a new tab によって実行をスケジュールできます。

DayBoundariesForCounts プロパティを使用すると、メッセージ・ヘッダ・カウント計算を締め切るさまざまな日数境界を指定できます。このプロパティの値は、最も古い日と 0 を除いたメッセージ・ヘッダ・カウントを示す日数のコンマ区切りリストです。既定値は "56, 28, 14, 7, 1" です。

API を直接呼び出すには、以下を実行します。

do ##class(Ens.SAM.GeneralMetrics).Collect(<boundaries>)

boundaries パラメータはオプションで、DayBoundariesForCounts の値を指定します。

InterSystems IRIS では、このセクションの冒頭で説明した追加の有効化手順を実行する場合のみ、アクティビティ量メトリックと HTTP メトリック (以下の 2 つのテーブルで説明します) が提供されます。

/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 との互換性を確保するために、値は整数または浮動小数点数にする必要があります。

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

     Note:

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

   • SetSensorLabels() メソッドを呼び出すことで、このメソッドにはオプションでメトリックのラベルを含めることができます。ただし、メトリックのラベルを定義する場合は、そのメトリックを設定するたびにそのラベルを含める必要があります。

   • このメトリックは、SetSensorInfo() メソッドを呼び出すことで、オプションでメトリックの HELP、TYPE、および UNIT 情報を定義できます。/metrics エンドポイントの出力には、この情報がコメントとして含められます。詳細は、Prometheus のドキュメント (https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-informationOpens 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
   

   
   Note:

   InterSystems IRIS システムをアップグレードする場合は、この手順をやり直す必要があります。

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

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

7. ブラウザで URL http://<baseURL>/api/monitor/metrics を指定して、/metrics エンドポイントの出力を確認します。<baseURL> はシステムのベース URL です。以下のように、InterSystems IRIS メトリックの後に、定義したメトリックが表示されます。

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

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