本記事の趣旨

はじめまして。私は普段、APMであるInstanaを用いてシステム開発・運用に関わることを試行錯誤しています。
今回は、数あるInstanaの機能の中でも、Pipeline Feedback をピックアップして、この機能の使ったユースケースをご紹介します。
Instanaのユーザーコミュニティで、とある方がご紹介されていたことをきっかけに、いろいろ調べたり、妄想を膨らませていたりしているうちに、だんだん楽しくなってきたためアドベントカレンダーへ投稿することにしました。
なお、別の記事で「理論編」を題して、Pipeline Feedbackを用いたユースケースをご紹介しておりますのでぜひご覧ください。

Pipeline Feedbackとは

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

これより下に記載している、「設定」・「スクリプトの実行」・「コマンドの実行」は、必ずInstana 公式ドキュメントをお確かめの上、自己責任でお願いいたします。

API Tokenの取得

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

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

発行された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上のアプリケーション名\"
            }
          ]
        }
      }
    ]
}"

参考情報：Windows環境（PowerShellの場合）

Windows環境におけるPowerShellでは下記のように設定することでAPIを実行することができます。

# 環境変数のの設定
$timestamp = [Int32](Get-date (get-date -Format U) -UFormat %s) * 1000
$INSTANA_APITOKEN = "<先ほど取得したAPI Token>"
$INSTANA_URL = "<InstanaのテナントURL>"
$body = @{
    name = "リリース名"
    start = $timestamp 
}
#Release Markerをつける
Invoke-RestMethod -Uri "$INSTANA_URL/api/releases" `
    - Method POST `
    - Headers @{Authorization ="apiToken $INSTANA_APITOKEN"; "Content-Type" = "application/json"} `
    - Body $body
#Release Markerを消す
Invoke-RestMethod -Uri "$INSTANA_URL/api/releases/<リリースID>" `
    - Method DELETE `
    - Headers @{Authorization ="apiToken $INSTANA_APITOKEN"; "Content-Type" = "application/json"} `

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

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

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

実行結果とInstana画面

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

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

マーカーの削除

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

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

注意事項

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

参考資料