Web API活用ガイド

Owned by es1shelty
7月 30, 2024
5 min read

SheltyはWebAPIを使うことで画面UIを介さずに収集データを出力することができます。

Web APIに関して下記を説明します。

 

参照可能なデータ

SheltyのAgentおよびBrokerが収集したデータはInfluxDBに格納されます。

格納されたデータ項目は別項MetricList 性能データ項目一覧 に記されています。

 

リテンションポリシーと解像度

格納データは「リテンションポリシー名」というバケット（器）に格納されています。

例えば、OS性能情報を表すos_perfメジャメントは下記の3つのバケットに存在します。

  • rp_default

  • rp_minute

  • rp_hour

 

各バケットは、格納されるデータの保持期間およびデータ取得単位が異なります。例えば、os_perfはrp_defaultでは１秒単位のデータ、rp_minuteでは１分単位のデータが格納されています。

確認したい対象期間、目的に合わせて適切なバケットを選択してご使用ください。

データの保存期期間はデータ保存期間の設定によって決まります。データ保存期間の設定 をご覧ください。

Web API概要

Web APIとは「Application Programming Interface」の一種です。

 

SheltyではInfluxDBに格納されたデータを問い合わせる手段の１つとして/shelty/api/public/v1/flux/execというWeb APIを提供しています。SheltyのManagerに対してWeb APIを通じてHTTPリクエストを送信する事で、InfluxDBに格納された性能情報を取り出すことができます。

 

HTTPリクエストはFluxをPOSTメソッドで送信して行います。

image-20240617-235939.png

 

Flux

Flux は、データのクエリ等の用途に向けて設計されたオープンソースのデータスクリプト言語です。

Fluxを通じてInfluxDBに格納されたデータに対する問い合わせを行います。

 

Fluxの例）ホスト名がhost100の実行時から過去10分間のCPU使用率を問い合わせる

from(bucket: "shelty_db/rp_default") |> range(start: -10m) |> filter(fn: (r) => r["_measurement"] == "os_perf") |> filter(fn: (r) => r["_field"] == "cpu_usage") |> filter(fn: (r) => r["host_name"] == "host100")

 

Web API利用準備

APIキーの準備

Web APIにてリクエストを送信する際にはリクエスト時にクエリーパラメータとしてAPIキーを指定する必要があります。APIキーは事前に準備する必要があります。APIキー管理を参照してください。

 

利用例は下記の通りです。

http://shelty:8080/shelty/api/public/v1/flux/exec?apiKey=00d5a491-7a41-xxx-...

 

Web API利用方法

HTTPのPOSTリクエストを行えるクライアントにてWeb APIを発行します。

Linuxのcurlコマンドから利用する例で説明します。

使用例

curl -X POST http://manager:8080/shelty/api/public/v1/flux/exec?apiKey=00d5a491-7a41-xxx \ -d 'from(bucket: "shelty_db/rp_default") |> range(start: -1m) |> filter(fn: (r) => r["_measurement"] == "os_perf") |> filter(fn: (r) => r["_field"] == "cpu_usage") |> filter(fn: (r) => r["host_name"] == "host100")'

 

書式

-X POST

curlにPOSTすることを指定します。

-d

Fluxを記述します。

 

戻り値

結果はJSON形式で出力します。

CSVなど他の形式が望ましい場合は、後述の加工例をご参照ください。

 

resultプロパティがオブジェクトのリスト構造になっています。

リスト内の各オブジェクトが、各時刻_timeにおける特定フィールド_fieldの値_valueを示します。

その他、メタ情報として自ホストを表すタグhost_nameや所属するシステムや論理サーバを表すsystem_idやserver_group_idなどのタグが含まれます。

 

Web API結果の加工例

Web APIの結果をjqコマンドでCSV形式に加工する例を示します。

 

コマンド解説

  • curlに-sオプションによりコマンド進捗表示を非出力に指定します

  • jqコマンドにて形式変換を指定します

    • _time, _field, _valueのみ選択

    • CSV形式に変換

 

出力例

 

システムおよび論理サーバ構造の活用

SheltyはAgentおよびBroker導入設定時にサーバGおよびインフラGとして階層構造を定義しています。

階層構造の各々の要素は独自のID（タグ）を持ち、InfluxDBに格納されたデータにもタグとして継承されています。例えば、system_id, server_group_idなどです。

 

これらは、Fluxでの問い合わせに活用できます。

利用可能なタグの詳細についてはMetricList 性能データ項目一覧 をご覧ください。

 

例）特定システムの全ホストの最新1分の平均CPU使用率を取得

 

Flux解説

  • range句で過去1分を指定します

  • filtet句でr["system_id"] == "1"と条件を記述することで特定システムの全ホストを対象とします

  • aggregateWindow句で1分単位に平均値を求めます

  • limit句で各ホストの最新1分のデータを出力します

 

システムおよび論理サーバの名称確認

system_idやserver_group_idに紐づく表示名を取得するには下記のWeb APIをご活用ください。

Web API /api/public/v1/meta/hierarchy/agents

 

使用例

 

戻り値例

  • systemNameおよびserverGroupNameがタグに紐づく表示名です。

 

Flux記述時のポイント

from句

バケットを指定します。

shelty_db/rp_default内のshelty_dbは固定です。

後部のrp_defaultはMetricList 性能データ項目一覧 を参照し、読み替えて記述ください。

 

from句の記述例

 

range句

問い合わせの対象期間でのフィルタリングを指示します。

startとstopにて対象期間を指示します。

 

例）実行時刻より過去12時間を対象期間とする例（stopの省略時はnow()がセットされます）

 

例）2024-6-17 0:00:00 ～ 2024-6-18 0:00:00の期間を絶対指定する例

 

例）エポック時刻（整数）で指定する例

 

複数フィールドの取得

os_perfよりcpu_usageとmem_usageを取得し並べて表示する例です。

 

 

Flux解説

  • filter句にて複数のフィールドを取得対象とするよう条件判定にorを使用

  • pivot句にて縦方向に取得される_fieldを横方向に展開

 

 

 

Copyright © IIM. All Rights Reserved.