ホスト・エージェントの REST API

Instana のホストエージェントは、カスタムイベント、メトリクス、およびトレースデータを受け付けるWebサービス（ REST API ）を提供します。

Linux でのインフラストラクチャーの相関

ホストエージェントにおいて、ホストエージェントが受信した 1.1.582メトリクスおよびトレースデータは、以下の前提条件が満たされている場合、そのデータを送信したプロセスと関連付けられます

ホストエージェントは Linux システム上で動作し、以下のコマンドが利用可能です： lsns, nsenter, および ss。
メトリクスとトレースデータを送信するプロセスは、ホストエージェントと同じホスト上で実行されます。
「プロセスを無視」機能を使用しても、メトリクスおよびトレースデータを送信するプロセスは無視されません。
メトリクスとトレースは、プロキシを経由せず、ホストエージェントに直接送信されます（たとえば、 OpenTelemetry Collector を使用する OpenTelemtry の場合）。メトリックとトレース・データがプロキシーを経由する場合は、代わりにプロキシー・プロセスがメトリックとトレースに関連付けられます。

データをトレースするために、「アプリケーション・パースペクティブ・サービス」ダッシュボードは、関連するトレースが取り込まれたすべてのプロセスを正しく参照します。これには、このサービスに対して行われたインフラストラクチャーの変更などが含まれます。

これらの前提条件のいずれかが満たされない場合、メトリクスおよびトレースデータは、ホストエージェントが実行されているホストと関連付けられます。

注：対応する API を再度呼び出す際は、エージェントの API エンドポイントへの接続を一度確立したら、その接続を再利用することを強く推奨します。それ以外の場合は、新しい API 要求ごとにプロセス・ルックアップがトリガーされます。これを保証できない場合、あるいは問題が発生した場合（たとえば、トレースレートが高い高負荷の状況など）、プロセス検索を無効にすることができます。 API からのメトリクスとトレースは、引き続きデータを取得するホストと関連付けられますが、対応するプロセスエンティティとは関連付けられません。

プロセス検索を無効にするには、エージェントの configuration.yaml ファイルに次のスニペットを追加してください：

com.instana.processlookup:
  enabled: false

OpenTelemetry メトリクスおよびトレースのエンドポイント

オンラインで編集する

OpenTelemetry のメトリクスおよびトレースの取り込みについては、『 OpenTelemetry 』のドキュメントを参照してください。

Prometheus メトリックおよびエンドポイント

オンラインで編集する

Prometheus のメトリクス取り込みについては、 Prometheus のリモート書き込みに関するドキュメントを参照してください。

イベント SDK Web サービス

オンラインで編集する

エンドポイント: http://<agent_ip>:42699/com.instana.plugin.generic.event

Event SDK REST Webサービスを使用することで、カスタムヘルスチェックやその他のイベントソースを Instana に統合することができます。それぞれは、手動イベントを送信するために使用される Instana エージェント上で動作します。このエージェントには、 http://<agent_ip>:42699/com.instana.plugin.generic.event ポート 8000 でリスニングするエンドポイントがあり、たとえば、 POST リクエストを含む次のような JSON を受け付けます：

{
  "title": <string>,
  "text": <string>,
  "severity": <integer>,
  "timestamp": <integer>,
  "duration": <integer>,
}

使用できるイベント・パラメーターは次のとおりです。

title : 「 Instana 」のイベントビューに表示されるタイトル。
text : イベントの詳細セクションに表示される説明文。
severity: 意図するイベント・タイプに応じて、次のいずれかの値になるオプションの整数。
- 変更イベント: -1 (デフォルト)
- 警告イベント: 5
- クリティカル・イベント: 10
さらに、 タイトル フィールドにキーワード 「オンライン」 または 「オフライン」が含まれている場合、変更イベントは存在イベントと見なされます。
timestamp: イベントのタイム・スタンプ ( UNIX エポックからのミリ秒数)。存在しない場合、代わりに現在の時刻が使用されます。
duration: イベントのオプションの期間 (ミリ秒)。値が指定されていない場合、イベントは期間のない「インスタント」イベントとして表示されます。さらに、「変更」イベントまたは「存在」イベントは、常に期間後にクローズされます。イベントの期間を延長するには、 path パラメーターを使用して、 path パラメーターで設定されている値と同じ値を持つオープン・イベントを識別します。
インシデント: trueに設定されている場合にインシデントトリガー・イベントに変換するオプションの ブール値 。これには、 severity が正でなければなりません。
path: このエンドポイントに対する同じパス値を使用した以降の要求でイベントを拡張することが必要になる可能性がある場合に定義できるオプションの ID。

以下の例は、インスタント・イベントを示しています。

{
    "title": "Instant critical event on the host",
    "text": "Description of the event that occurred",
    "severity": 10
}

以下の例は、期間が 5 分のイベントを示しています。これは、 path パラメーターを使用して拡張できます。同じ path ID を持つ後続のイベントが送信されない場合、イベントは 5 分後に自動的にクローズされます。

{
    "title": "WARNING: This event started to happen",
    "text": "It will be active for 5 minutes",
    "severity": 5,
    "duration": 300000,
    "path": "unique-event-identifier"
}

同じ path パラメーターを持つ後続のイベントを送信して、イベントの存続時間を延長することができます。以下のイベント例は、イベントを前の例からさらに 5 分拡張します。

{
    "title": "WARNING: This event continues to happen",
    "text": "It will be active for another 5 minutes",
    "severity": 5,
    "duration": 300000,
    "path": "unique-event-identifier"
}

このエンドポイントは、次のような配列を指定するとイベントのバッチも受け付けます。

[
  {
    "title": "First event",
    ...
  },
  {
    "title": "Second event",
    ...
  }
]

Ruby の例

オンラインで編集する

次の例は、 Ruby のインスタンスを示しています：

duration = (Time.now.to_f * 1000).floor - deploy_start_time_in_ms
payload = {}
payload[:title] = 'Deployed MyApp'
payload[:text] = 'pglombardo deployed MyApp@revision'
payload[:duration] = duration

uri = URI('http://localhost:42699/com.instana.plugin.generic.event')
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req.body = payload.to_json
Net::HTTP.start(uri.hostname, uri.port) do |http|
  http.request(req)
end

Curl の例

オンラインで編集する

次の例は、Curlのインスタンスを示しています：

curl -XPOST http://localhost:42699/com.instana.plugin.generic.event -H "Content-Type: application/json" -d '{"title":"Custom API Events ", "text": "Failure Redeploying Service Duration", "duration": 60000, "severity": 5}'

PowerShell の例

オンラインで編集する

PowerShell, では、標準の Cmdlet を使用するか Invoke-WebRequest 、またはを使用できます Invoke-RestMethod。指定するパラメーターは、基本的に同じです。

Invoke-RestMethod
        -Uri http://localhost:42699/com.instana.plugin.generic.event
        -Method POST
        -Body '{"title":"PowerShell Event ", "text": "You used PowerShell to create this event!", "severity": -1}'

Invoke-WebRequest
  -Uri http://localhost:42699/com.instana.plugin.generic.event
  -Method Post
  -Body '{"title":"PowerShell Event ", "text": "You used PowerShell to create this event!", "severity": -1}'

Mina 統合

オンラインで編集する

Mina との連携に関する詳細については、「 Mina イベント連携」をご覧ください。

トレース SDK Web サービス

オンラインで編集する

エンドポイント: http://<agent_ip>:42699/com.instana.plugin.generic.trace

トレース SDK REST Web サービスを使用すると、言語に関係なく任意のアプリケーションに Instana を統合できます。アクティブな Instana エージェントそれぞれを使用して、手動でキャプチャーしたトレースを Web サービスにフィードでき、自動的にキャプチャーしたトレースと結合することも、完全に分離することもできます。このエージェントは、 URL http://<agent_ip>:42699/com.instana.plugin.generic.trace でリスニングするエンドポイントを提供し、 POST リクエストを使用して以下の JSON を受け付けます：

{
  "spanId": <string>,
  "parentId": <string>,
  "traceId": <string>,
  "timestamp": <64 bit long>,
  "duration": <64 bit long>,
  "name": <string>,
  "type": <string>,
  "error": <boolean>,
  "data": {
    <string> : <string>
  }
}

spanId は、特定のスパンの固有 ID です。トレースは、ルート・スパンによって定義されます。つまり、スパンには parentId はありません。 traceId は、同じトレースに属するすべてのスパンで同一である必要があり、 spanId. traceId、 spanId、および parentId とのオーバーラップが許可されます。64 ビットの固有値は、 b0789916ff8f319fのような 16 進数ストリングとしてエンコードされます。スパンは、親の spanId を parentId として参照することで、階層を形成します。トレース内のスパン階層の例を以下に示します。

      root (spanId=1, traceId=1, type=Entry)
          child A (spanId=2, traceId=1, parentId=1, type=Exit)
            child A (spanId=3, traceId=1, parentId=2, type=Entry)
              child B (spanId=4, traceId=1, parentId=3, type=Exit)
        child B (spanId=5, traceId=1, parentId=4, type=Entry)

timestamp フィールドと duration フィールドの単位はミリ秒です。タイム・スタンプは、協定世界時に調整されたエポック・タイム・スタンプでなければなりません。

name フィールドには、トレースを視覚化およびグループ化するために使用される任意のストリングを指定でき、任意のテキストを含めることができます。ただし、簡潔にすることをお勧めします。

type フィールドはオプションで、指定しないときは ENTRY として処理されます。選択肢は ENTRY、 EXIT、 INTERMEDIATE、、またはです EUM。 type の設定は、UI については重要です。 ENTRY の後では、子スパンは INTERMEDIATE または EXIT であることが想定されています。 EXITの後に、 ENTRY が続きます。これは、リモート呼び出しとして視覚化されます。

data フィールドはオプションで、任意のキーと値のペアを指定できます。重複するキーを指定した場合の動作は、予測できません。

error フィールドはオプションで、エラーがあるスパンを示すために true に設定できます。

このエンドポイントは、イベントのバッチも受け付けます。この場合、次のような配列を指定する必要があります。

[
  {
    // span as above
  },
  {
    // span as above
  }
]

Trace SDK Web Service を使用して受信したトレースについては、 Java Trace SDK と同様の変換およびサービス／エンドポイントの命名規則が適用されます。特に、 data のキーと値のペア ( service、 endpoint、および call.name) が命名に使用されます。

注：Kubernetes で提供されているオプションの Instana エージェントサービス（ Instana エージェントの Helm チャートを含む）は、Trace Web SDKのサポートと組み合わせることで非常に有用です。これは、データが同じ Kubernetes ノード上で実行されている Instana エージェントに確実に送信され、 Instana エージェントがインフラストラクチャの相関データを正しく入力できるようにするためです。

Curl の例

オンラインで編集する

以下の例は、一致する ENTRY および EXIT 呼び出しに関するデータをホスト・エージェントに送信する方法を示しています。これは、 https://orders.happyshop.com/my/service/asdasd URL をターゲットとする HTTP GET 要求を受信し、それを https://crm.internal/orders/asdasd URLのアップストリーム・サービスにルーティングするプロセスをシミュレートします。

#!/bin/bash

curl -0 -v -X POST 'http://localhost:42699/com.instana.plugin.generic.trace' -H 'Content-Type: application/json; charset=utf-8' -d @- <<EOF
[
  {
    "spanId": "8165b19a37094800",
    "traceId": "1368e0592a91fe00",
    "timestamp": 1591346182000,
    "duration": 134,
    "name": "GET /my/service/asdasd",
    "type": "ENTRY",
    "error": false,
    "data": {
      "http.url": "https://orders.happyshop.com/my/service/asdasd",
      "http.method": "GET",
      "http.status_code": 200,
      "http.path": "/my/service/asdasd",
      "http.host": "orders.happyshop.com"
    }
  },
  {
    "spanId": "7ddf6b31b320cc00",
    "parentId": "8165b19a37094800",
    "traceId": "1368e0592a91fe00",
    "timestamp": 1591346182010,
    "duration": 97,
    "name": "GET /orders/asdasd",
    "type": "EXIT",
    "error": false,
    "data": {
      "http.url": "https://crm.internal/orders/asdasd",
      "http.method": "GET",
      "http.status_code": 200,
      "http.path": "/orders/asdasd",
      "http.host": "crm.internal"
    }
  }
]
EOF

制限

オンラインで編集する

トレース Web サービスについては、次の速度制限を順守してください。

最大 API 呼び出し数/秒: 20
POST 要求あたりの最大ペイロード: スパンは 4 KiB を超えないようにする必要があります。要求サイズは 4 MiB を超えないようにする必要があります。
最大バッチ・サイズ (スパン/配列): 1000

FAQ

オンラインで編集する

Instana エージェントから Instana バックエンドへの呼び出し回数に制限はありますか？

Instana エージェントと Instana バックエンド間のデータ転送は、多くの要因に左右されます。送信は永続的な HTTP2 接続によって実行され、高度に最適化されています。
Instana エージェント経由で、サイズが約40 MiB のスパンを50,000個、 Instana バックエンドに送信する場合、最適なパケットサイズ（分割サイズ）はどれくらいでしょうか？

1 秒間分のスパン、または 500 個のスパンが収集されるまでバッファーに入れてから、スパンをエージェントに送信する方法をお勧めします。この送信戦略の実装については、 repo を参照してください。
最適なエージェント・パフォーマンス (CPU、RAM など) には、どの要件が推奨されますか?

これは、モニターする必要があるホストによって異なります。例えば、ホストごとの Docker コンテナーの数などです。
Instana エージェント環境はどのように設定する必要がありますか？

詳細については、「エージェントの設定」を参照してください。