Instana API

概要とメリット

Instana API は、REST API 経由でリリースマーカー（Release）を作成・更新・削除できます。これによりデプロイ時に自動で Instana のタイムラインへ「変更が起きた瞬間」を記録できます。API のため特定ツールに依存せず、curl や CI/CD ツール、運用スクリプトなどあらゆる場所から利用できます。
APIを用いる機能として、Pipeline Feedback という機能があります。リリースマーカーを時系列グラフに表示し、CPU・メモリ・レイテンシ・エラー率などのメトリクスと重ねて確認できます。これにより「どのリリースから問題が発生したのか？」を一目で判断できます。

公式ドキュメントのリンク

Instana公式ドキュメント https://www.ibm.com/docs/en/instana-observability/latest?topic=instana-rest-api-sdks
Instana REST API仕様 https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Introduction

Instana APIを用いた活用例（Pipeline Feedback）

Instana APIを用いることで、「curl」コマンドなどでInstana APIコールをした際に、Instanaのグラフにマーカーを打つことができます。この機能を活用し、何らかの作業時にマーカーを打つような運用にすると、作業前後のメトリクスの変化やエラーを素早く読み取ることでき、正常性確認や切り戻し判断に役立つことが期待されます。

about-1

API Tokenの取得

Pipeline Feedbackを使用するためには、API Tokenの発行が必要です。 Instanaにログインし、設定→セキュリティ&アクセス→APIトークン→新規APIトークンをクリックします。

token-1

「新規APIトークンの作成」で「リリースの構成」にチェック入れ、保存します。

token-2

発行されたAPI Tokenは忘れずに保存してください。

curlコマンドによるPipeline　Feedbackの実行

利便性を上げるため、下記の環境変数を設定します。

#API Tokenの設定
export INSTANA_APITOKEN=<先ほど取得したAPI Token>

#InstanaテナントURLの設定　「https://」から「instana.io」までを指定する
export INSTANA_URL=<InstanaのテナントURL>

#タイムスタンプの指定
export timestamp=`date "+%s000"`

環境変数の設定後、下記のcurlコマンドを実行することでPipeline Feedbackを使用したマーカーを打つことができます。

curl --location --request POST "$INSTANA_URL/api/releases" \
  --header "Authorization: apiToken $INSTANA_APITOKEN" \
  --header "Content-Type: application/json" \
  --data "{
        \"name\": \"リリース名\",
        \"start\": $timestamp,
        \"services\": [
      {
        \"name\": \"Instana上のサービス名\",
        \"scopedTo\": {
          \"applications\": [
            {
              \"name\": \"Instana上のアプリケーション名\"
            }
          ]
        }
      }
    ]
}"

サービス名とアプリケーション名

curlコマンドとInstanaのサービス名とアプリケーション名の対応について説明します。

curl-command

右側は、Instanaにおけるアプリケーション・パースペクティブの画面です。ここに表示されているサービス名（ここでは、nginx-web / robot-shop-mysql / robot-shop-redis のいずれかを指定）とアプリケーション名（demo-robotshop）をcurlコマンドのオプションとして指定することで、そのアプリケーション・パースペクティブのメトリクスにマーカーを打つことができます。なお、サービス名とアプリケーション名は省略することができます。その場合、Instanaテナント内すべてのメトリクスにマーカーが打たれ、さらに実行後に、すべての画面内でPipeline Feecbackが実行されたことが通知されます。

実行結果とInstana画面

curlコマンドで指定した①から④は、Instanaでは図のように対応します。

result-1

result-2

なお、サービス名とアプリケーション名を省略した場合、③と④における「Scope」は「Global」と表示されます。

マーカーの削除

上記のcurlコマンドを実行後に表示される「release id」を用いることで、マーカーを削除することができます。

1	`curl --location --request DELETE "$INSTANA_URL/api/releases/<release id>" --header "Authorization: apiToken $INSTANA_APITOKEN"`

注意事項

curl後に表示されるreleaseIDを用いてInstana APIのURLにアクセスすると、誰でもcurlコマンドのオプションに記載した内容を表示できるため、curl --data部分の記載には注意が必要です。

caution-1