Postman Insightsで始めるAPIオブザーバビリティ

# はじめに

Postman最大の年次イベント[POST/CON 25](url)にて、[Postman Insights](https://www.postman.com/product/postman-insights/)がOpen Betaとして発表されました。Postman Insightsは複雑なダッシュボード設定やテレメトリ連携を行うことなく、Insightsエージェントを導入すれば、APIのトラフィックや動作、パフォーマンスを可視化できるAPIオブザーバビリティに特化したサービスです。

Keynoteでは、[Agent mode](https://www.postman.com/product/agent-mode/)でAPIエンドポイントのエラーの詳細をチェックするように指示をするとPostman InsightsによりAPIトラフィックが可視化されたダッシュボードからエラーの詳細を確認したり、失敗したリクエストをもとに即座にデバッグできる **再現モード** が披露されました。

興味のある方は、次のPOST/CONのRecapブログを読んでみてください: 

https://blog.postman.com/post-con-25-keynote-recap/

私も深夜のKeynoteをリアルタイムで視聴しており、そのときのポストがこちら:

https://x.com/yokawasa/status/1930310478968041628

本記事では、Postman Insightsの概要を紹介するとともに、ローカルKubernetes（以下、k8s）環境にテスト用APIを使って、Postman InsightsがどのようにAPIの動きを可視化できるのかを試してみます。あわせて、利用時の注意点や制限事項についても簡単にご紹介します。

なお、亀田さん（[@kameoncloud](https://x.com/kameoncloud)）がEC2上にデプロイしたAPIを使って検証された記事も公開されています。こちらもあわせて参考にしてみてください。

https://zenn.dev/kameoncloud/articles/af2a9f4af2d1ff

# Postman Insightsとは？

Postman Insightsは、APIに特化したオブザーバビリティを支援する機能です。

Web APIは単なるデータの出入口ではなく、リクエストとレスポンスが交差するシステムの境界点として、異常やボトルネックが最も表れやすい場所です。このAPIのふるまいを観測することで、よく使われているエンドポイントや、応答時間の異常といった重要な情報を得ることができます。

Postman Insightsを使えば、InsightsエージェントをAPI環境にインストールするだけで、APIの挙動をリアルタイムに可視化し、問題の早期発見と修正を支援します。トラブルの影響範囲を最小化し、ユーザーに影響が出る前に対処できるのが大きな特徴です。

### **主な特徴**

- **APIトラフィックのキャプチャ:**  InsightsエージェントがBerkeley Packet Filter（BPF）を用いて、APIトラフィックをパッシブに取得します
- **AIによるエンドポイント検出:**  AIを活用してエンドポイントを自動で特定。ホットスポットや重要な経路を可視化し、たとえばヘルスチェックのような補助的なエンドポイントはデフォルトで表示から除外されます
- **自動エラー検出とアラート:**  エラー率の高いエンドポイントを検出し、自動でアラートを送信。関心のある問題を重点的に追跡できます
- **再現モード (Repro Mode)**:  実際の失敗リクエスト（ヘッダー・認証・ペイロード込み）をキャプチャし、Postmanで開いてそのまま問題のリクエストを再実行・デバッグできます。シームレスに同じワークスペース内で完結できるのが利点です

### **対応プラットフォーム**

現在、Postman Insights (Open Beta) は以下の環境にデプロイされたAPIで利用可能です：

- **Kubernetes**
- **Amazon EKS / ECS / EC2 / Elastic Beanstalk**

詳細は [Insightsの公式ドキュメント](https://learning.postman.com/docs/insights/overview/) をご覧ください。

:::note
 💡 利用プランに関する注意点 (202506時点) 

Postman Insightsはバージョン11.48.0以降のFree / Basic / Professionalプラン（EU以外）でOpen Betaとして利用可能です。Enterpriseプランでの利用を希望される場合や、その他対応プラットフォームについて詳細は、[About Postman Insights](https://learning.postman.com/docs/insights/overview/) を確認してください。
::: 

### **Postmanモニターとの違い**

Postmanには、Postmanモニターという機能があります。これはPostmanコレクションをクラウド上で定期的に実行し、APIの健全性やパフォーマンスを監視するものです。単なるステータスチェックにとどまらず、Postmanスクリプトを活用した柔軟なテストロジックを組み込めるのが特徴です。

一方で、モニタリングはあらかじめ想定された異常（既知の問題）を検出することに特化しており、未知の障害や予期しないふるまいを見逃してしまう可能性があります。

Postman Insightsは、まさにこの未知の障害に対応するためのアプローチです。APIへの実際のトラフィックを観測し、問題の兆候や異常を早期に発見し、モニタリングでは補いきれない部分をカバーします。

# Postman Insightsを使ってみる

ここでは、テスト用のAPIに対してPostman Insightsエージェントを設定し、どのようにAPIの動作が可視化されるのかを試してみます。

使用するのは、シンプルなCRUD機能を提供する「Users API」です。これをローカルのKubernetes（k8s）環境で動かし、Insightsによる観察結果を確認していきます。


### API実行環境の構築

#### 環境 & 事前準備

本手順は、以下の環境およびバージョンで動作確認を行いました。

```
local OS: macOS 15.2 (24C101)
k8s: v1.30.0 (KIND)
Postman app:  11.49.2 (ブラウザ版)
```

実行にあたっては、[Docker Desktop](https://docs.docker.com/desktop/) などのコンテナ実行環境に加え、以下のコマンドラインツールが必要です。お試しの際は、あらかじめインストールをお願いします。

- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) コマンド
- [kubectl](https://kubernetes.io/ja/docs/tasks/tools/#kubectl) コマンド


#### (1) ローカル Kuberentes（KIND）クラスターの構築

[KIND](https://kind.sigs.k8s.io/)でローカ環境にKubernetesクラスターを構築します。下記の`kind create cluster` コマンドで、シンプルな1ノードのクラスターが構築できます。

```bash
$ kind create cluster --image kindest/node:v1.30.0
```

上記コマンドを実行してクラスタ構築が完了の表示がされたら、下記コマンドでクラスター情報を確認できます。

```bash
$ kind get cluster

kind
```

#### (2) テストAPIのデプロイ

Kuberntesクラスターに `testns` ネームスペースを作成して、そこに、本記事でテストAPIとして利用するUsers API（[github](https://github.com/yokawasa/users-api-flask-mysql)）をデプロイします。

まずは、Users APIの構成を定義するマニフェストファイルを取得します。ローカル環境でgitコマンドが使える人は下記のように`git clone`コマンドで、gitコマンドがない方は、[こちら](https://github.com/yokawasa/users-api-flask-mysql)よりソースを直接ダウンロードしてください。

```bash
git clone https://github.com/yokawasa/users-api-flask-mysql.git
```

k8sクラスタに`testns`ネームスペースを作成します。

```bash
$ kubectl create namespace testns

namespace/testns created
```

次に、先に取得したUsers APIのマニフェストファイルを、下記の`kubectl apply`コマンドで`testns`ネームスペースにデプロイします。

```bash
$ kubectl apply -f kubernetes/users-api-all-in-one.yml -n testns

persistentvolume/mysql-pv-volume created
persistentvolumeclaim/mysql-pv-claim created
deployment.apps/mysql created
service/mysql created
secret/flaskapi-secrets created
deployment.apps/flaskapi-deployment created
service/flask-service created
```

Users APIをデプロイしたら、次のコマンドでUser APIのServiceリソースと、Podリソースの情報を取得します。

```bash
$ kubectl get svc,pods -n testns

NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
service/mysql              NodePort       10.96.108.207   <none>        3306:30650/TCP   27m
service/usersapi-service   LoadBalancer   10.96.167.212   <pending>     5000:30579/TCP   26m

NAME                                       READY   STATUS    RESTARTS   AGE
pod/mysql-6598d69f79-mf7w6                 1/1     Running   0          27m
pod/usersapi-d4bb79cc4-4wjms               1/1     Running   0          14m
```

上記コマンドの出力結果から、Users APIアプリのコンテナを実行するPodは`Running`ステータスであり、また、Users APIのPodへのアクセスを束ねる`usersapi-service`という名前のServiceリソースがポート`5000`で公開されていることが分かります。外部からこのServiceリソースのポートにアクセスすると、Users APIのPodに転送されます。

ためしに、Users APIにアクセスしてみます。

まずは、クラスタ内の `usersapi-service`サービス (ポート:`5000`)にアクセスするため、次のコマンドでポート`5000`をローカルポート`8080` にフォワードします。

```bash
kubectl port-forward svc/usersapi-service 8080:5000 -n testns
```

これで、クラスタにデプロイされたAPIには、ベースURL`http://localhost:8080`でアクセスできるようになります。

試しに、ユーザー情報取得のためのエンドポイント `http://localhost:8080/users` にGETメソッドでアクセスしてみてください。レスポンスボディに次のような空のJSON配列が表示されれば無事アクセス成功です。

```bash
$ curl http://localhost:8080/users

[]
```

### Postman Insightsのセットアップ

#### (1) サイドバーにInsightsメニューの追加

ワークスペースのサイドバーに「Insights」が表示されていない場合、下記のようにワークスペースの`Settings`のサイドバー設定エリア(Configure sidebar)でInsights表示をOnにすると、サイドバーにInsightsが表示されるようになります。

![Screenshot 2025-06-13 at 14.22.27.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/18aeb167-92af-4b62-b5ff-618a98ae98ac.png)

図: Workspace Setting > Configure sidebar

#### (2) Postman Insightsエージェントのセットアップ

サイドバーの「Insights」をクリックして、「`+`」をクリックまたは、[`Get started with Insights`]ボタンをクリックしてInsightsプロジェクトを追加してください。

下図左（図 Postman Insightsのセットアップガイド）のようにセットアップ先の環境を選択します。ここではローカルk8s環境を活用するので、 `Start with Kubernetes`を選択してください。下図右のような選択する環境ごとのインストラクション(サイドカーパターンの説明)が表示されます。

![Screenshot 2025-06-13 at 16.00.36.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/977f371d-cc6d-4c34-956b-69cf230a69b1.png)

図: Postman Insightsのセットアップガイド

それでは、インストラクションを参考に、デプロイされているAPIに対してPostman Insightsエージェントを設定します。

:::note
💡 Insightsエージェントのk8s環境へのインストールのパターン

次の2種類のパターンがあります:
 
1. **サイドカーパターン**: Insightsエージェントは各Podにサイドカーコンテナとして注入（inject）されます。手順について詳しくは⇒ [Install Postman Insights Agent as a sidecar](https://learning.postman.com/docs/insights/get-started/kubernetes/sidecar)  
2. **Daemonsetパターン**: 各k8sノードにInsightsエージェントが設定されます。手順について詳しくは⇒ [Install Postman Insights Agent as a DaemonSet](https://learning.postman.com/docs/insights/get-started/kubernetes/daemonset/)
::: 

まずは、次のスクリプトを実行して、Postman Insightsエージェントの設定に必要なクライアントコマンドをローカルにインストールします。

```bash
bash -c "$(curl -L https://releases.observability.postman.com/scripts/install-postman-insights-agent.sh)"
```

無事に成功すると、このようなメッセージが出力されます

```bash
You have successfully installed the Postman Insights Agent!

For more information on how to start capturing API traffic and
create an endpoint collection, see the Insights docs at:

  https://learning.postman.com/docs/insights/insights-gs/
```

つぎに、k8sクラスタ全体のDeploymentリソースの構成を確認します。下記コマンド実行の結果、`testns`ネームスペースに`mysql`と`usersapi`が作成されていることがわかります。

```bash
kubectl get deployments -A

NAMESPACE            NAME                     READY   UP-TO-DATE   AVAILABLE   AGE
kube-system          coredns                  2/2     2            2           36m
local-path-storage   local-path-provisioner   1/1     1            1           36m
testns               mysql                    1/1     1            1           43s
testns               usersapi                 1/1     1            1           43s
```

づづいて、Postman Insightsエージェントを設定していきます。

下記のコマンドは、Postman Insightsの`Setup`タブのインストラクションページに表示されているものと同じものです。このコマンドでPostman InsightsエージェントをUsers APIのPodにサイドカーとして注入（inject）します。

```bash
kubectl get -n <namespace> deployment/<deployment> -o yaml \
    | POSTMAN_API_KEY=<add-your-api-key-here> postman-insights-agent kube inject --project svc_***** --repro-mode -s=true -f - \
    | kubectl apply -f -
```

コマンド実行に必要なデータ項目とその取得方法については下記の通り：

| データ項目 | 取得方法 |
|---|---|
| `namespace` |  サイドカーを注入するAPIのネームスペースです。ここでは、先の確認結果のとおり`testns`になります |
| `deployment` | サイドカーを注入するAPIのDeploymentリソース名です。ここでは、先の確認結果のとおり`usersapi`になります|
| `プロジェクトID` | `svc_`ではじまる文字列がプロジェクトIDになります、Postman Insightsの`Setup`タブのインストラクションページに表示されているコマンドに最初から含まれています |
| `Postman APIキー`| まだPostman APIキーをもっていない人は[Postman APIキーの管理ページ](https://go.postman.co/settings/me/api-keys)でAPIキーを生成してください|

上記のデータ項目が取得できたら、コマンドを実行します。

```bash
$ kubectl get -n testns deployment/usersapi -o yaml \
  | POSTMAN_API_KEY=PMAK-***** postman-insights-agent kube inject --project svc_***** --repro-mode -s=true -f - \
  | kubectl apply -f -
  
secret/postman-agent-secrets created
deployment.apps/usersapi configured
```

コマンドを実行すると、`usersapi` Deploymentリソースは更新され、Podにサイドカーコンテナーが注入されます。

次の`kubectl describe`コマンドを使うと、`usersapi` Deploymentリソースに含まれるPodテンプレートの内容を確認できます。これにより、Insightsエージェントがサイドカーコンテナとして注入されているかどうかや、そのコンテナの具体的な設定内容を確認できます。

```bash
kubectl describe deploy usersapi -n testns

---
Pod Template:
  Labels:  app=usersapi
  Containers:

   usersapi:
    Image:      ghcr.io/yokawasa/users-api-flask-mysql/users-api:0.0.1
    ... snip ...

   postman-insights-agent:
    Image:      public.ecr.aws/postman/postman-insights-agent:latest
    Port:       <none>
    Host Port:  <none>
    Args:
      apidump
      --project
      svc_6WPPSBCvMuIzYQ7ZIp5wWg
      --repro-mode
    Limits:
      cpu:     200m
      memory:  500Mi
    Requests:
      cpu:     200m
      memory:  500Mi
    Environment:
      POSTMAN_API_KEY:        <set to the key 'postman-api-key' in secret 'postman-agent-secrets'>  Optional: false
      POSTMAN_K8S_NODE:        (v1:spec.nodeName)
      POSTMAN_K8S_NAMESPACE:   (v1:metadata.namespace)
      POSTMAN_K8S_POD:         (v1:metadata.name)
      POSTMAN_K8S_HOST_IP:     (v1:status.hostIP)
      POSTMAN_K8S_POD_IP:      (v1:status.podIP)
    Mounts:                   <none>
  ...
```

Insightsエージェント設定後に、Postman Insightsの`Diagnostics`タブをみると、次のようにエージェント情報が表示され、トラフィック監視が開始されていることがわかります。

![N-3-2-2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/03960ba0-d6a2-46da-9ae3-690e7a35fcf5.png)

図:Postman Insights Diagnostics

この`Diagnostics`では、サービスに対してトラフィックを送信している実行中のエージェントのメタデータが表示されます。ここでのUsers APIは単一Podで動かしているため、そこに注入された1つのInsightsエージェント情報がここに表示されますが、複数Podで構成されている場合は、当然ながら複数エージェントの情報が表示されます。

### APIへのテストリクエスト送信

それでは、診断対象のAPIにテストリクエストを送信してみます。下記のUsers APIのCRUD用エンドポイントすべてにリクエストを送信します。

> エンドポイント http://localhost:8080

| 機能 |	HTTPメソッド	| URIパス | リクエストボディ |
|---|---|---|---|
| ユーザー一覧取得 | GET | /users | なし | 
| ユーザー取得 | GET | /user/{id} | なし | 
| ユーザー追加 | POST | /create | `{ "name":"<name>", "email":"<email>", "pwd": "<password>" }` | 
| ユーザー更新 | POST | /update | `{ "user_id":"<id>","name":"<name>", "email":"<email>", "pwd": "<password>" }` |
| ユーザー削除 | DELETE | /delete/{id} | なし | 

※ このAPIのURIパスはRESTfulな設計スタイルには準拠してません

いろんなパターンのリクエストを観測できるように、成功するリクエストのみならず、エラーステータスが返却されるリクエストも送信します。

#### テストAPIリクエスト用のデータ

Postmanアプリでリクエストを送信する場合は、こちらのコレクションファイルをインポートしてお使いください: 

https://github.com/yokawasa/users-api-flask-mysql/blob/main/postman/users-api.postman_collection.json

手っ取り早くcurlコマンドで送信したい人は下記のサンプルリクエストを参考にしてみてください: 

```bash
## ユーザー作成 
curl --location 'localhost:8080/create' \
--header 'Content-Type: application/json' \
--data-raw '{ "name": "Testuser", "email": "testuser@example.com", "pwd": "Xno1UxjdsRFIFZE" }'

## ユーザー更新 
curl --location 'localhost:8080/update' \
--header 'Content-Type: application/json' \
--data-raw '{ "name": "Isac", "email": "updated.1749364031@example.com", "pwd": "cR6skShkAWrNaco", "user_id": 2 }'

## ユーザー一覧とID別ユーザー取得
curl --location 'localhost:8080/users'
curl --location 'localhost:8080/user/1'
curl --location 'localhost:8080/user/2'

## ユーザー削除
curl --location --request DELETE 'localhost:8080/delete/1'

## ユーザー作成 (エラーステータスになる例)
curl --location 'localhost:8080/create' \
--header 'Content-Type: application/json' \
--data-raw '{ "email": "dummy.1749187709@example.com", "pwd": "KdJTV0axnF_2Wow" }'

## ユーザー更新 (エラーステータスになる例)
curl --location 'localhost:8080/update' \
--header 'Content-Type: application/json' \
--data-raw '{ "namex": "Heloise", "email": "updated.1749187630@example.com", "pwd": "AlCAofz9IdCOi5L", "user_id": 13}'
```

### Postman Insightsダッシュボードの確認

ある程度のテスト用APIリクエストを送信した後、それらがPostman Insightsのダッシュボード上でどのように可視化されるのかを確認していきます。

#### Overviewタブ

`Overview`タブでは、システムの健全性を簡単に把握できるよう、過去7日間の観測されたリクエスト総数、P90レイテンシ、エラー、エンドポイントの健全性などの情報が表示されます。

![](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/28c6db17-7c7e-407d-8da4-f2b6b9d928f0.png)

図: Postman Insights Overview

Postman Insightsで表示されるデータは、Insightsエージェントよりキャプチャされたトラフィック情報を元に、AIによる適正判断が加えられてます。このため、AIが初めてエンドポイントを検出するまでには数分かかる場合があります。

また、エンドポイントとして表示される内容を調整することができます。`エンドポイント`タブで各エンドポイントを編集することで、AIアルゴリズムにヒントを与えることができます。これについて詳しくは[Customize your Postman Insights](https://learning.postman.com/docs/insights/customize/#edit-path-parameters)を参照ください。

#### Errorsタブとエラー詳細

`Errors`タブでは、プロジェクト全体にわたって4xxおよび5xxエラーが発生しているエンドポイントが表示され、エラーを簡単に発見できるようになっています。また、エンドポイントごとのエラーデータを集約表示することもできます。エラーリクエストの詳細な内容を深堀りすることも簡単にできるようになっています。

![](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/e844b6b9-e9d7-4076-b738-e0e6dfb871a3.png)

図: Postman Insights Errors

![N-3-2-5.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/27016295-4453-4fcf-930f-7898b071b5b6.png)

図: Postman Insights エラー詳細の確認

#### Reproモード

これは、私がもっとも期待していた機能です。Reproモードとは、その名の通りエラーが発生したリクエストを再現できる機能のことです。

Reproモードは、`Overview`、`Errors`、`Endpoints`や`Requests`タブに表示されるエラーが発生しているエンドポイントで、Reproモードを選択できます。

下図のように`Run`ドロップダウンメニューから`Original request`を選択すると、Postmanのリクエストビルダーに移動して、そのリクエストを実行できます。デバッグ・トラブルシュートにとても活躍しそうです。

![N-3-2-6.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/4c2755c2-bbfc-4230-9e43-bfa7773c4fa7.png)

図: Postman Insights 再現（Repro）モード

:::note
Reproモードはデフォルトで有効化されていないので、使う前に、`Settings`タブでReproモードが有効になっていることを確認してください
:::

# 注意点・制約など

## Postman Insigthsのデフォルト表示・設定について

Postman Insigthsは、デフォルトで次の3点が有効化されていないので注意が必要です。それぞれSettingsタブで有効化・無効化できます。

- **Reproモード**
- **IPホスト表示**（ホストのIPアドレスでのアクセスはデフォルト表示しない）
- **ヘルスチェック用のエンドポイント表示**（ヘルスチェック用と判断されたエンドポイント）

![Screenshot 2025-06-14 at 8.43.29.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/687aac84-c3ce-479f-b29a-422c01d5631e.png)

図: Settingsタブの内容

## Reproモードにおける注意点

- 執筆時点では、`Access logs`や `With Bifrost`は利用できませんでした。[公式マニュアル](https://learning.postman.com/docs/insights/debug/#use-repro-mode)には、「Coming soon」と記載されているので、近いうちに利用可能にはなるようです

- Dedaction対象情報: Postman Insightsはユーザーのセキュリティやプライバシーに関わるようなセンシティブな情報とみなしたデータフィールドをマスク（`*REDACTED*`に置き換え）します。デフォルトでセンシティブとみなす情報フィールド一覧は[Repro mode data redactions](https://learning.postman.com/docs/insights/data/redactions/)で確認できます。また、Settingsタブで、柔軟にマスク対象とするデータフィールドの設定ができます

# おわりに

本記事では、Postman Insightsの概要から、ローカルk8s環境を使った導入・検証方法、そして実際のダッシュボード表示や再現モードの活用までを一通り紹介しました。

Postman Insightsは、既存のモニタリングツールとは異なり、APIの生のトラフィックに基づいた観測と、未知の問題への気づきを支援するオブザーバビリティ機能が魅力です。特にRepoモードによる即時デバッグの体験は、実運用時のトラブル対応において大きな武器となるでしょう。

今回はローカルk8s環境を例にしましたが、EKS、ECSやEC2など他のプラットフォームでも同様に導入できます。Postmanをすでにご利用の方は、まずは小さなプロジェクトや開発環境からInsightsを試してみるのがおすすめです。

今後、正式リリースに向けて対応環境や機能も拡充されていくと思われます。期待していきましょう。