Get started with Postman Insights

To get started using Insights, you can begin your user journey as an individual user or by setting up a team workspace in Postman. Both experiences are available with a free Postman account.

Next, you'll install and configure the Postman Insights Agent, and start getting insights about your endpoints. From there, you can curate your endpoints into collections and observe performance trends over time.

The Postman Insights Agent supports Amazon Elastic Container Service (ECS) on EC2 and ECS Fargate deployments.

Access Postman

If you don't have a Postman account, download Postman and sign in.

When you sign up, a personal workspace will be created for you. If you'd like to share your work, you can create a team. With the Postman Free plan, you can have a team with up to three users. If you don't already have a team in Postman, see Creating a team for instructions on how to set it up.

If you set up a team workspace and later decide to leave it, see Leaving a team to learn what happens with your workspace data.

Once you're signed up, contact the Insights Alpha team to get access to the Insights alpha in Postman.

Install the Postman Insights Agent

The Insights Agent listens to the traffic arriving at the cluster service you want to monitor and creates an Insights Project for it.

1. In Postman, select your workspace, then the Settings tab, and activate the Insights element.

   

2. Select Insights in the sidebar and select + to create a new Insights Project.

   

   The onboarding instructions display, listing the configuration requirements.

3. Review the instructions and select I'm Ready.

4. Copy the install script from the onboarding instructions and run it in your shell:

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

Configure the Postman Insights Agent

• If you’re using Fargate, you can configure the Insights Agent as a sidecar only.
• If you’re using ECS on EC2 with awsvpc, you can install it as a sidecar or as a daemon service.
• If you’re using ECS on EC2 with bridge networking, you can configure the Insights Agent as a daemon service only.

Requirements

Configuring ECS requires:

• Internet access for your service, to be able to communicate with the Insights backend services. For more information, see Ensure internet access.
• AWS credentials at ~/.aws/credentials with edit access to ECS cluster, service and task definition. For more information, see Set up AWS ECS permissions.
• Cluster ARN. Navigate to the cluster in the AWS console and find the ARN in the cluster overview.
• Service ARN. The ARN of the service on which you want to install the Postman Insights Agent.

Configure the Insights Agent as a sidecar

Following are instructions for installing the Insights Agent as a sidecar container. The sidecar is added using the ecs add subcommand or, if you're on CloudFormation stack, using ecs cf-fragment.

If you're using ECS on EC2 with bridge networking, you will need to attach the Insights Agent to the host network. See Configure the Insights Agent as a daemon service.

Configure using ecs add

1. Prepare to run the install script. Check Requirements for needed information.

2. In the New insights page, select Add API Key to generate or use an API key.

3. Copy the script and run it in your shell, substituting your values. The script on the page should have your API key and project ID filled in for you.

   POSTMAN_API_KEY=<your_api_key> postman-insights-agent ecs add \
   --project <projectID> \
   --cluster <ECS_cluster_ARN> \
   --profile <aws_profile_name> \
   --region <aws_region> \
   --service <ECS_service_ARN> \
   --task <task-name>
   

   Observe the deployment progress.

   

   See the help menu for further configuration.

   postman-lc-agent ecs --help
   

   The time it takes for the deployment to complete depends on the number of tasks running in a service. Therefore, while the process might take a while, the CLI will run until the deployment is finished because the processing is handled by AWS.

4. Return to Postman and observe an Insights Project populated for your services.

   Your Insights Project can take a few minutes to populate.

You are ready to check your Insights Agent connection, curate your endpoints, and observe insights about your endpoints. You can also review any traffic errors.

Configure using ecs cf-fragment

The ecs cf-fragment command prints a CloudFormation fragment that can be included in an ECS cluster managed by a CloudFormation template.

To edit the CloudFormation template:

1. On your command line, run the ecs cf-fragment subcommand:

   postman-insights-agent ecs cf-fragment --project svc_YYYYY
   

2. Edit the CloudFormation template that has the task definition for your service. Include the container definition output from the command above in the task definition.

3. Edit the CloudFormation template for your service to use the new revision of the task definition.

The precise steps depend on your workflow for updating your CloudFormation templates. As an example, the steps below show how to do this using Application Composer in the AWS console.

To add the Insights Agent to a task definition in AWS Application Composer:

1. Navigate to your CloudFormation stack that has the task definition for your service. Click the Update button.

   

2. Select Edit in Application Composer, then select the Edit in Application Composer button.

   

3. Enter Template mode.

   

4. Find the ContainerDefinitions section of the appropriate TaskDefinition resource. Add the Postman Insights Agent container definition.

   

5. Select Update template. Select an appropriate S3 bucket and then Confirm and continue to CloudFormation.

   

6. Select Next.

   

7. Select Next again to accept the existing set of parameter values.

   

8. On the Stack failure options card, select Roll back all stack resources, or the update may not succeed. Select Next.

   

9. Review the changes and select Submit. It may take a few minutes for the task definition to be updated.

If your service isn't configured to pick up the latest version of a task definition, you'll need to update the service manually.

To update a service with a new task definition revision in AWS Application Composer:

1. Navigate to the Task definitions page of the ECS console. Ensure you are in the appropriate AWS region, and select the task definition that was updated above. Note its latest revision number.

   

2. Follow the steps above for editing a task definition, except instead of adding the Insights Agent’s container definition, update the task definition for your service.

   

3. Return to Postman and observe an Insights Project populated for your services.

   Your Insights Project can take a few minutes to populate.

You are ready to check your Insights Agent connection, curate your endpoints, and observe insights about your endpoints. You can also review any traffic errors.

Configure the Insights Agent as a daemon service

Following are instructions for attaching the Insights Agent to the host network in ECS. This option is necessary if you use ECS with bridge networking. If you’d like to install the Insights Agent as a sidecar instead, see Configure the Insights Agent as a sidecar.

You can add the Insights agent to an ECS cluster as a daemon service by using ecs task-def.

Create a new task definition:

1. Navigate to the Task definitions page of the ECS console. Ensure you are in the appropriate AWS region.

2. Select the Create new task definition button and choose Create new task definition with JSON.

   

3. On your command line, run the ecs task-def subcommand:

   postman-insights-agent ecs task-def --project svc_YYYYY
   

4. Replace the contents of the task definition with the output from the command above.

   

5. Select Create. You can use the postman-insights-agent task definition to add the Postman Insights Agent to your ECS cluster.

Add the Insights Agent to your ECS cluster as a daemon service:

1. Navigate to the Tasks tab of your ECS cluster. Select the Run new task button.

   

2. In the Environment card, select Launch type and EC2.

   

3. In the Deployment configuration card, configure the following settings:

   • Set the Application type to Service.
   • In the Family dropdown, choose postman-insights-agent.
   • Set the Service name to postman-insights-agent.
   • Set the Service type to Daemon.
   

4. At the bottom of the page, select Create.

5. Return to Postman and observe an Insights Project populated for your services.

   Your Insights Project can take a few minutes to populate.

You are ready to check your Insights Agent connection, curate your endpoints, and observe insights about your endpoints. You can also review any traffic errors.

Uninstall the Insights Agent

The Insights Agent installation modifies the task definition of your service to include the Insights Agent sidecar. To uninstall the Insights Agent, simply revert to the earlier version of your task definition. To completely uninstall the agent, you can delete the task definition that contains the Insights Agent sidecar.

Ensure internet access

Fargate tasks

To verify that your task has a route to the internet:

• When using a public subnet, you can assign a public IP address to the task ENI.
• When using a private subnet, the subnet can have a NAT gateway attached.

For more information, see Task networking for tasks hosted on Fargate.

EC2 tasks

Tasks must be launched in private subnets with NAT gateway. For more information, see Task networking for tasks that are hosted on Amazon EC2 instances.

Set up AWS ECS permissions

Attach the following policy to your AWS profile.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:UpdateService",
                "ecs:RegisterTaskDefinition",
                "ecs:DescribeServices",
                "ecs:TagResource",
                "ecs:DescribeTaskDefinition",
                "ecs:DescribeClusters"
                ],
            "Resource": "*"
        }
    ]
}

The Postman Insights Agent CLI needs the following permissions in order to install the Insights Agent in ECS. If the profile you selected lacks any of these permissions, the CLI output will show an error message indicating which action it was attempting to perform.

The AmazonECS_FullAccess policy provided by Amazon is a superset of these actions; you could add that entire policy as an easy way to ensure your permissions are sufficient, if they're not already.

Action	Resource	Purpose
ec2:DescribeRegions	*	Find the list of AWS regions you have enabled. (If not present, it defaults to a precompiled list.)
ecs:ListClusters	*	Find the available ECS clusters.
ecs:DescribeClusters	*, or restricted to account like arn:aws:ecs:::cluster/*	Look up the names of the available ECS clusters.
ecs:ListTaskDefinitionFamilies	*	Find the available task definitions.
ecs:DescribeTaskDefinition	*	Read the existing task definition in order to copy it.
ecs:RegisterTaskDefinition	*	Write a new version of the task definition.
ecs:ListServices	*	Find the available services.
ecs:DescribeServices	*, or restricted to your account, or restricted to the cluster you selected	Identify which services are using the task definition you selected.
ecs:UpdateService	*, or restricted to your account, or restricted to the cluster you selected	Update and restart the service using the new task definition.
ecs:TagResource	*, or restricted to your account, or restricted to the cluster you selected	Mark the service as having been updated by the Insights Agent.

Check your Insights Agent connection

The Insights Project shows you the properties of your system based on real-time API traffic. For Postman Insights to work, the Postman Insights Agent needs to see your API traffic.

To see if your agent is working, or to debug problems, you can see traffic error states and messages in the Insights Project’s Diagnostics tab.

Edit path parameters

As Postman collects endpoint traffic, it's finding the dynamic parts of the path and replacing them with path argument variables. However, some endpoints may need to be adjusted manually.

To edit a path parameter, do the following:

1. In your Insights project, select the edit icon next to the endpoint you want to edit.

   

2. From the dropdown list, select the component to edit.

   

3. Give the component a name, which will automatically display as a variable in the endpoint.

4. Specify the parameter values. You can select the types of characters the parameter can include or, for better precision, specify a string by entering regular expressions. Make sure to select Enter after each expression. Values that will and won’t be included displays at the bottom.

   

5. Select Next to review any exceptions you want to use to avoid merging specific values into the parameter, for example, if you want to watch a specific endpoint separately.

6. Select Confirm to apply the change. The timeline will be recomputed, and the API model will apply the new rule to future traffic.

   

Curate your endpoints

The Postman Insights Agent watches your API traffic to automatically populate your endpoints inside your Insights Project. You can search and sort your endpoints, and filter them by host, method, category, or status code. To share your filtered results, copy and send the URL of your filtered page.

To see a pie chart of an endpoint's status codes, select the error rate value.

You can select View endpoint details to observe a timeline of captured requests by status code. In the graph, select a status code to hide its detail and review the timeline of the status code you're interested in.

You can select endpoints that you would like to monitor and save them to a collection.

To curate your endpoints, do the following:

1. Find endpoints that you would like to monitor and add them to a curated collection. For example, select all endpoints by a specific host and select Save to Collection.

   

2. Add the selected endpoints to an existing curated collection or create a new collection. Select Add.

   

3. Access your curated collection and check the Endpoints and Errors tabs for the selected endpoints. See Observe Insights for more information.

Just as with the ordinary collections in Postman, an Insights collection has these elements:

• Query parameters — Sent with your requests using the URL box and the Params tab.
• Path variables — Form part of the request URL, and are referenced using placeholders preceded by : as in this example: /customer/:id.
• Headers — Provide more metadata about the operation you are performing.
• Body — Enables you to specify the data you need to send with a request.
• Response — Gives you several tools to help you understand the response quickly. You can view the body in one of four views: Pretty, Raw, Preview, and Visualize.

For more information, see Send API requests and get response data in Postman.

Observe Insights

A curated collection provides Endpoints and Errors tabs where you can observe endpoint error trends, enabling you to catch errors before your users do.

This feature is experimental and will continue to evolve. Send your feedback and ideas about the types of metrics you would like to see to the Insights Alpha team.

The Endpoints tab returns a list of error categories for endpoints, selectable from a dropdown list:

• Endpoints with most errors, based on the HTTP status code of the response.
• Endpoints with the highest proportion of requests that resulted in an error, based on the HTTP status code of the response.
• Endpoints with new errors in the past day for endpoints that were previously error free for 6 days, based on the HTTP status code of the response.
• Endpoints with the highest p90 latency.
• Slowest endpoints.

Use the time range selector to get the level of detail you need.

If you select a 14-day time range, the graph overlays errors from the previous week over the errors captured in the past seven days. Check each selection to observe the difference in errors between the captures.

The Errors tab displays per-endpoint error states in a chronological order as well as a graphical representation of the seven-day trend.

Next steps

• About Postman Insights Early Access
• Postman Insights overview
• Diagnose and troubleshoot errors
• Postman Insights Agent reference