InstanaにおけるPipeline Feedbackを用いたシステムの開発・運用効率化を考える（実践編）

## 本記事の趣旨

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

## Pipeline Feedbackとは

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

![about-1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/359643/07545c23-466a-6ef7-f651-7838738fceb3.png)

<hr>

:::note warn

**これより下に記載している、「設定」・「スクリプトの実行」・「コマンドの実行」は、必ず[Instana 公式ドキュメント](https://www.ibm.com/docs/en/instana-observability/current)をお確かめの上、自己責任でお願いいたします。**

:::

<hr>

## API Tokenの取得

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

![token-1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/359643/d74a7906-5244-edfc-5404-c2cfc8e171a3.png)

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

![token-2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/359643/f7243e24-fffc-08cb-40ff-82fa945dc218.png)

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

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

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

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

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

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

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

```bash
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上のアプリケーション名\"
            }
          ]
        }
      }
    ]
}"
```

<details><summary>参考情報：Windows環境（PowerShellの場合）</summary>

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

```powershell
# 環境変数のの設定
$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"} `
```

</details>

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

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

![curl-1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/359643/20da7d17-9783-d56d-f1f4-c4ab5b27d890.png)

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

## 実行結果とInstana画面

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

![result-1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/359643/1d9ef749-9806-bc95-8e08-10c3fc6ef83b.png)

![result-2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/359643/6b2746d6-0645-89d4-e59d-cf5ba8d1d22c.png)


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

## マーカーの削除

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

```bash
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.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/359643/d3bb52c9-32c0-58df-0287-69887aa16099.png)


## 参考資料

- [Instana 公式ドキュメント](https://www.ibm.com/docs/en/instana-observability/current?topic=capabilities-pipeline-feedback)
- [Instana API リファレンス](https://instana.github.io/openapi/)
- [IBM コミュニティブログ](https://community.ibm.com/community/user/wasdevops/blogs/randy-langehennig1/2021/05/23/how-to-integrate-ibm-urbancode-deploy-with-instana)