Zenn
🐕

Postman Insights　

に公開
Postman
o11y
insights
tech

先日Postmanが開催している年次カンファレンスであるPOST/CON 25でいくつかの新機能がリリースされました。
https://postcon.postman.com/2025/
中の人である川崎さんがそれぞれの機能のサマリーをXでポスト（Postmanだけに・・・やかましい、ごめんなさい）してくれています。
https://x.com/yokawasa

それらを触っていこうと思います。第三回目はPostman Insightsです。

Postman Insights とは

https://learning.postman.com/docs/insights/overview/
公式ドキュメントにはこう記載があります。

Postman Insightsは、障害のあるAPIを最も迅速かつ簡単に発見し、修正する方法を提供することを目指しています。Postman InsightsエージェントはAPIトラフィックを監視し、すべてのAPIエンドポイントにおいてエンドポイントごとのメトリクスとエラーを自動的に提供します。カスタムダッシュボードを必要とせず、ほぼリアルタイムで提供されます。Insightsは、実際のユーザーデータに基づいて、リクエストとレスポンスのコンテキストで障害のあるAPI呼び出しを再現し、トラブルシューティングできる再現モードにより、デバッグをさらにシームレスにします。

Postmanは通常APIをテストする、もしくはAPIの開発を補助するツールとして使われますが、今回リリースされたPostman Insights AgentをAPIをホスティングしている環境にインストールしておくことで、APIの状況を通信のモニタリングからキャプチャを行いPostman側で解析し、ダッシュボードとして表示してくれるのがPostman Insights となります。
さらにそれに加えて通常のo11yツールと大きく異なるPostman Insightsの目玉は、Repro Modeです。これは通信のキャプチャログからCollectionを再現してすぐAPIコールを再現できます。

さっそくやってみる


いつも通りPostmanの新機能は、左ペインの四角の集合体をクリックすることでトグルを有効化できます。まずはInsightsをクリックします。
NewをクリックするとAgentのデプロイ先を選択する画面が出てきます。


k8sクラスター,ECS,EC2,Elastic Beanstalkが選択可能です。余談ですが、2025年にリリースされた新機能でElastic Beanstalkをサポートしているのはとても胸熱です。それ以外の環境（AWSでいえばLambdaやそれ以外のクラウド環境等）も今後順次増えていくとは思いますが、Postmanにリクエストを送るリンクもありますのでぜひ皆さんの環境のサポートが欲しい方他は連絡してみてください。

この記事ではEC2を用います。以下のインストール用コマンドが表示されますのでコピーを行いEC2で実行します。

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

等Postman InsightsのドキュメントにはEC2の要件として[インターネットからSSHが行えること]と記載がありますが、実際はこのコマンドが実行できれば通信経路は何でも問題ありません。（Postman Insightsサービス自体が稼働中にSSHをEC2に対して行うわけではありません）
インストールが完了したら以下を実行します。

sudo POSTMAN_API_KEY=<add-your-api-key-here> postman-insights-agent ec2 setup --project svc_1bIELBCpE6Y3HLMnlOpipQ --repro-mode

(svc_1bIELBCpE6Y3HLMnlOpipQの値は皆さん毎に代わります）
API Keyは画面をクリックすると生成可能です。

これでAgentの起動が完了し、EC2でホスティングされているAPIの通信キャプチャが行われ自動でPostmanクラウド側に送出されるようになります。ここでしている--repro-modeが今回の目玉機能ですので忘れずこのフラグを付けておきます。

Postmanクラウド側のDiagnosticsタブでは以下の様にAgentを検知して通信の状況をキャプチャし始めていることがわかります。

SettingsタブからIP Hostsのトグルを有効化しておきます。通常Postman Insight AgentはIPアドレスをベースとした通信はヘルスチェック用として統計は取得するもののPostmanクラウド側に解析用のデータとして通信のキャプチャ内容を送出しないようになっています。このトグルをオンにすることでIPアドレスベースの通信もダッシュボードに表示されます。

ではEC2上で以下のファイルをserver.jsとして作成します。

// server.js
const express = require('express');
const app = express();
const port = 3000;

// JSONをパースするミドルウェア
app.use(express.json());

// GETエンドポイント
app.get('/', (req, res) => {
  res.send('Hello World!');
});

// POSTエンドポイント
app.post('/echo', (req, res) => {
  // 0〜1のランダムな数値を生成
  if (Math.random() < 0.5) {
    // 50%の確率で500エラーを返す
    res.status(500).json({
      message: 'Internal Server Error (simulated)',
    });
  } else {
    // 通常通りレスポンス
    res.json({
      message: 'Received!',
      data: req.body,
    });
  }
});

// サーバ起動
app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

これはEC2のIPアドレスを読み込むと（GET）Hello Worldを返し、/echoにPOSTを行うと50%の確率で500エラーかReceivedを戻します。
ある程度通信を発生させながら（ブラウザで読み込むかPostman Collectionでテストを行うか）8~10分待つと以下の通りAgentがインストールされているホストのAPIを検知し始めます。

Errorも以下の様に検出されています。

repro mode

では今回の目玉のrepro modeを使ってみます。
EndpointsタブからAPIコールを選択してSave to Collectionをクリックします。


Collectionの方でInsightsから作成されたアイコンがついたCollecitonが生成されます。

Repro Modeの特徴としてInsightsでキャプチャーしたHTTPヘッダーやボディ情報がそのままCollectionに自動でセットされていますのであとは送信ボタンを押せばテストがすぐ行えます。

Discussion