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

はじめに

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

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

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

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

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

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

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の公式ドキュメント をご覧ください。

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

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

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 などのコンテナ実行環境に加え、以下のコマンドラインツールが必要です。お試しの際は、あらかじめインストールをお願いします。

• kind コマンド
• kubectl コマンド

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

KINDでローカ環境にKubernetesクラスターを構築します。下記のkind create cluster コマンドで、シンプルな1ノードのクラスターが構築できます。

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

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

$ kind get cluster

kind

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

Kuberntesクラスターに testns ネームスペースを作成して、そこに、本記事でテストAPIとして利用するUsers API（github）をデプロイします。

まずは、Users APIの構成を定義するマニフェストファイルを取得します。ローカル環境でgitコマンドが使える人は下記のようにgit cloneコマンドで、gitコマンドがない方は、こちらよりソースを直接ダウンロードしてください。

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

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

$ kubectl create namespace testns

namespace/testns created

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

$ 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リソースの情報を取得します。

$ 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 にフォワードします。

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

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

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

$ curl http://localhost:8080/users

[]

Postman Insightsのセットアップ

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

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

図: Workspace Setting > Configure sidebar

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

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

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

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

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

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

次の2種類のパターンがあります:

1. サイドカーパターン: Insightsエージェントは各Podにサイドカーコンテナとして注入（inject）されます。手順について詳しくは⇒ Install Postman Insights Agent as a sidecar
2. Daemonsetパターン: 各k8sノードにInsightsエージェントが設定されます。手順について詳しくは⇒ Install Postman Insights Agent as a DaemonSet

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

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

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

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が作成されていることがわかります。

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）します。

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キーの管理ページでAPIキーを生成してください

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

$ 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エージェントがサイドカーコンテナとして注入されているかどうかや、そのコンテナの具体的な設定内容を確認できます。

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タブをみると、次のようにエージェント情報が表示され、トラフィック監視が開始されていることがわかります。

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

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

## ユーザー作成 
curl --location 'localhost:8080/create' \
--header 'Content-Type: application/json' \
--data-raw '{ "name": "Testuser", "email": "[e-mail]", "pwd": "Xno1UxjdsRFIFZE" }'

## ユーザー更新 
curl --location 'localhost:8080/update' \
--header 'Content-Type: application/json' \
--data-raw '{ "name": "Isac", "email": "[e-mail]", "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": "[e-mail]", "pwd": "KdJTV0axnF_2Wow" }'

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

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

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

Overviewタブ

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

図: Postman Insights Overview

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

また、エンドポイントとして表示される内容を調整することができます。エンドポイントタブで各エンドポイントを編集することで、AIアルゴリズムにヒントを与えることができます。これについて詳しくはCustomize your Postman Insightsを参照ください。

Errorsタブとエラー詳細

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

図: Postman Insights Errors

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

Reproモード

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

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

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

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

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

注意点・制約など

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

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

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

図: Settingsタブの内容

Reproモードにおける注意点

• 執筆時点では、Access logsや With Bifrostは利用できませんでした。公式マニュアルには、「Coming soon」と記載されているので、近いうちに利用可能にはなるようです

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

おわりに

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

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

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

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