PDF

NetCrunch ネイティブデータ形式

JSON、XML、CSVを使用して、外部監視データをカウンター、ステータス、コンテキストデータオブジェクトとして取り込むためにNetCrunchが使用するネイティブペイロード形式。

目的と適用範囲

NetCrunch ネイティブデータ形式は、外部システムが監視結果を一貫性のあるステートレスな監視指向の方法でNetCrunchに提供する方法を定義します。

これらの形式は、次のようなすべての外部取り込みメカニズムで共有されます。

  • Telemetry Node ペイロード
  • スクリプトおよびSSHベースのセンサー
  • Data File センサー（FTP、FTPS、HTTP、HTTPS、SSH、TFTP、Windows/SMB）
  • Receiver およびレガシーReceiver
  • RESTおよびHTTPベースのセンサー

データがどのように到着しても、NetCrunchは同じデータモデルを使用して解釈するため、次の用途に一貫して使用できます。

  • アラートとポリシー
  • ダッシュボードとチャート
  • ノードのステータスとセンサービュー
  • トポロジーとマップオーバーレイ
  • トレンドとレポート

ネイティブ形式が存在する理由

外部ソースは、多くの場合ステートレスです。

  • スクリプトは定期的に実行され、結果を出力するだけです
  • エクスポーターとエージェントはスナップショットをプッシュします
  • デバイスとAPIは通常、現在の状態のみを返します
  • ほとんどのシステムは履歴コンテキストを保存しません

NetCrunchはステートフルなコンポーネントです。

  • カウンターの時系列を保存します
  • ステータスの最後の状態を保存します
  • 状態遷移を検出します
  • データのコンテキストスナップショットを保存します

この設計により、外部統合がより簡単かつ安全になります。SDK、ローカルストレージ、または以前の値を記憶する処理がなくても、意味のある監視データを生成できます。

コア要素

すべてのネイティブペイロードには、次の3種類の要素を含めることができます。

  • カウンター
  • ステータス
  • データオブジェクト

CSVはカウンターのみをサポートし、最後に説明します。

カウンター

概念

カウンターは、時間の経過とともに繰り返し収集される数値を表します。NetCrunchは、トレンドおよびアラート用にカウンターを時系列として保存します。

カウンターの一般的な例：

  • CPU使用率（パーセント）
  • ディスクの空きバイト数
  • 1秒あたりのリクエスト率
  • 温度（度）
  • キューの長さ
  • 空きメモリ（メガバイト）
  • 1秒あたりのネットワークバイト数

カウンター構造の説明

カウンターは、最大3つの部分で識別されます。

Object
関連する測定値をグループ化するカテゴリ
例：Processor、Disk、NetworkInterface、Weather
Counter
測定対象となる具体的な値
例：% Processor Time、Free Bytes、Temperature
Instance
特定のオブジェクトを識別するオプションの識別子
例：_Total、C:、eth0、Prague

簡単なメンタルモデル：

  • Objectは、これがどのような種類のものかを示します
  • Instanceは、どのオブジェクトかを示します
  • Counterは、何が測定されているかを示します

外部カウンターパス形式

外部データを送信する場合、カウンターパスには次の形式を使用する必要があります。

Object/Counter.Instance

ルール：

  • Objectは省略可能です。省略した場合、NetCrunchはDefaultを使用します
  • Instanceは省略可能です。省略した場合、インスタンスはありません
  • ドットは常にインスタンスを導入します
  • ドットをカウンター名の一部にすることはできません
Instanceの構文規則
ドット（.）は常にインスタンスを導入します。
Weather/Temperatureにはインスタンスがありません。
Weather/Temperature.PragueにはPragueというインスタンスがあります。
Objectのデフォルト規則
Objectを省略すると、Defaultになります。
TemperatureはDefault/Temperatureとして扱われます。

ドキュメントでは、例に明示的なオブジェクト名を意図的に使用しています。Defaultに依存することもできますが、明示的なオブジェクトのほうが分かりやすく、拡張性にも優れています。

外部カウンターパスの例

単一コンテキストのカウンター（インスタンスなし）：

  • Weather/Temperature
  • System/CPU Usage
  • Web/Latency ms

複数インスタンスのカウンター（ドットの後にインスタンスを指定）：

  • Weather/Temperature.Prague
  • Disk/Free Bytes.C:
  • NetworkInterface/Bytes Received.eth0
  • Sensor/Value.Channel 1

UIでの表示形式

NetCrunch UIでは、カウンターはCIMスタイルの表記を使用して表示されます。

Object(instance)\Counter

これは表示専用の形式です。外部ペイロードではスラッシュとドットの形式を使用します。

例：

  • Weather(Prague)\Temperature
  • Disk(C:)\Free Bytes
  • Processor(_Total)\% Processor Time

カウンターの宣言と保存

制御されないメトリックの増加を防ぐため、カウンターは必要な場合にのみ永続化され、トレンド化されます。

次の条件のうち少なくとも1つを満たす場合、カウンターが保存されます。

  • データコレクターがカウンターを宣言している
  • ノード上またはポリシー（monitoring pack）を通じてしきい値が定義されている
  • センサーで、すべてのカウンターを収集するオプションが有効になっている

宣言も参照もされていないカウンターを送信した場合、NetCrunchはそのカウンターを無視することがあります。これにより、スクリプトが動的または無制限のカウンター名を出力することによって引き起こされる、偶発的なメトリックの急増からシステムを保護します。

JSON

{
  "counters": {
    "Weather/Temperature": 18.5,
    "Weather/Temperature.Prague": 16.2,
    "Disk/Free Bytes.C:": 82463372032
  }
}

XML

<nc>
  <counters>
    <counter path="Weather/Temperature">18.5</counter>
    <counter path="Weather/Temperature.Prague">16.2</counter>
    <counter path="Disk/Free Bytes.C:">82463372032</counter>
  </counters>
</nc>

ステータス

概念

ステータスは、数値トレンドではなく、離散的な状態を表します。

ステータス：

  • 最後の値のみを保存します
  • 時間の経過とともに変化します
  • 遷移時に評価されます

ステータスは、ステートレスなスクリプトや外部ソースに適しています。

一般的な用途：

  • サービスの健全性
  • 可用性チェック
  • 論理モード
  • 環境状態

ステートレス状態モデル

外部システムは現在の状態のみを報告します。

NetCrunchは次の処理を行います。

  • 以前の値を保存します
  • 遷移を検出します
  • 変更または特定の遷移時にアラートをトリガーします

これにより、ステートレスなスクリプトをステートフルなモニターのように動作させることができます。

標準ステータス値

NetCrunchは、次の標準状態を認識します。

  • unknown
  • ok
  • warning
  • error
  • critical

カスタムステータス値

カスタムのテキスト値または数値を使用できます。

  • Rain、Storm、Clear
  • Primary、Secondary
  • Open、Closed

カスタム値には、ダッシュボードまたはポリシーで明示的なマッピングが必要になる場合があります。

例：サービスの健全性と天候

次の例では、Webサービスの健全性と現在の天候を報告します。

JSON

{
  "statuses": {
    "WebService": "ok",
    "Weather": "Rain"
  }
}

XML

<nc>
  <statuses>
    <status name="WebService" value="ok"/>
    <status name="Weather" value="Rain"/>
  </statuses>
</nc>

メタデータを含む詳細なステータス

ステータスには、メッセージや診断データなどの追加コンテキストを含めることができます。

JSON

{
  "statuses": {
    "WebService": {
      "value": "error",
      "message": "HTTP 503 from backend",
      "critical": true,
      "data": {
        "endpoint": "/api/orders",
        "retryAfter": 30
      }
    }
  }
}

XML

<nc>
  <statuses>
    <status name="WebService">
      <value>error</value>
      <message>HTTP 503 from backend</message>
      <critical>true</critical>
      <data>
        <item key="endpoint">/api/orders</item>
        <item key="retryAfter">30</item>
      </data>
    </status>
  </statuses>
</nc>

データオブジェクト

概念

データオブジェクトは、現在発生している事象を説明するコンテキスト監視情報を提供します。

データオブジェクトは次の特性を持ちます。

  • 監視サイクル中またはテレメトリ経由で収集されます
  • 最新のスナップショットのみが保存されます
  • Sensor Viewに自動的に表示されます
  • トレンド化されず、しきい値にも使用されません

データオブジェクトは、次の用途に使用します。

  • 接続中のユーザーまたはセッションの一覧
  • 実行時統計
  • 診断テーブル
  • グループ化された分布

Data Views

Data Viewsは、ネイティブペイロードのデータブランチから生成されるコンテキストビューです。

技術的にはペイロード内のデータオブジェクトとして表現されますが、NetCrunchではビューとしてレンダリングされ、ノードステータスのSensor Viewsページに自動的に表示されます。

カウンターとデータオブジェクトの比較

トレンドまたはアラートしきい値が必要な場合は、カウンターを使用します。

コンテキストまたはスナップショットビューが必要で、高カーディナリティのメトリックを避けたい場合は、データオブジェクトを使用します。

例：接続ユーザーテーブル

JSON

{
  "data": {
    "connectedUsers": {
      "type": "table",
      "name": "Connected Users",
      "columns": ["User", "Source", "Login Time"],
      "rows": [
        ["alice", "10.0.1.12", "10:21"],
        ["bob", "10.0.1.15", "09:58"]
      ]
    }
  }
}

XML

<nc>
  <data>
    <object id="connectedUsers" type="table" name="Connected Users">
      <data>
        <columns>
          <item>User</item>
          <item>Source</item>
          <item>Login Time</item>
        </columns>
        <rows>
          <row>
            <item>alice</item>
            <item>10.0.1.12</item>
            <item>10:21</item>
          </row>
          <row>
            <item>bob</item>
            <item>10.0.1.15</item>
            <item>09:58</item>
          </row>
        </rows>
      </data>
    </object>
  </data>
</nc>

例：コンテキスト時系列スナップショット

JSON

{
  "data": {
    "cpuHistory": {
      "type": "time-series",
      "name": "CPU History",
      "timestamps": [1672531200000, 1672531260000, 1672531320000],
      "values": [12, 15, 10]
    }
  }
}

XML

<nc>
  <data>
    <object id="cpuHistory" type="time-series" name="CPU History">
      <data>
        <timestamps>
          <item>1672531200000</item>
          <item>1672531260000</item>
          <item>1672531320000</item>
        </timestamps>
        <values>
          <item>12</item>
          <item>15</item>
          <item>10</item>
        </values>
      </data>
    </object>
  </data>
</nc>

例：カテゴリ分布

JSON

{
  "data": {
    "httpCodes": {
      "type": "category",
      "name": "HTTP Responses",
      "categories": ["2xx", "3xx", "4xx", "5xx"],
      "values": [15230, 820, 431, 98]
    }
  }
}

XML


<nc>
  <data>
    <object id="httpCodes" type="category" name="HTTP Responses">
      <data>
        <categories>
          <item>2xx</item>
          <item>3xx</item>
          <item>4xx</item>
          <item>5xx</item>
        </categories>
        <values>
          <item>15230</item>
          <item>820</item>
          <item>431</item>
          <item>98</item>
        </values>
      </data>
    </object>
  </data>
</nc>

CSV形式

CSVはカウンターのみをサポートしており、意図的に機能が制限されています。

パスと値の形式


Weather/Temperature,18.5
Weather/Temperature.Prague,16.2
Disk/Free Bytes.C:,82463372032

詳細形式


Weather,Temperature,,18.5
Weather,Temperature,Prague,16.2
Disk,Free Bytes,C:,82463372032

countersdata objectsdata viewsdata-ingestiondata-objectsformatsnativestatusestelemetry