Diagnose and troubleshoot Insights Agent errors

As you work with the Postman Insights Agent, you may encounter errors and receive error messages. You may also come across frequently encountered issues. You'll find solutions to some of these issues below.

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.

Error messages

The Insights Agent displays errors and provides diagnostics so that you can act on them. Observe the information received from the Insights Agent on usage and error states, including interfaces, ports, and traffic (for example, HTTP vs. encrypted traffic and the busiest endpoints).

ECS memory issues

The Postman Insights Agent needs at least 300 MB of memory to run. If you've used most memory available, you need to make adjustments. Consider specifying an upper limit. Learn more from the following use cases.

For more information, see How Amazon ECS manages CPU and memory resources.

OutofMemory message

A task memory limit is required for an Amazon Elastic Container Service (ECS) Fargate instance but optional for an ECS on EC2 instance. If you specify a task-level memory limit, the ecs add command won't specify the memory size for the Insights Agent. This means the Agent shares memory with other containers in the task.

If the instance runs out of memory, one of the containers may stop operating. If you see instances restarting after an OutOfMemory outage, you can either increase the hard limit for the task, or set a hard limit on the Agent. To set a hard limit on the Agent, specify at least 700 MB as the Memory hard limit value in the container definition.

For more information, see How do I troubleshoot OutOfMemory errors in Amazon ECS?.

Container size is too large

If you don't specify a task-level memory limit, then the ecs add command sets a container-level memory request of 300 MB. This means that your task requires additional 300 MB of memory to be scheduled on an instance.

If you use a Docker Compose file to create your ECS task or service and no memory limit is specified, the Insights Agent sidecar is allocated 512 MB by default.

If you've already tuned the other containers in your task definition based on the instance size used in your cluster, the total size of the base container and the sidecar may be too large to schedule. You'll get the following message:

INFO[0006] (service mgg-test) was unable to place a task because no container instance met all of its requirements. The closest matching (container-instance 79cac21ecdb44097a989744944e202d7) has insufficient memory available. For more information, see the Troubleshooting section of the Amazon ECS Developer Guide. timestamp="2023-12-18 23:31:31 +0000 UTC"

In this case, you may need to reduce the memory or memoryReservation parameters on other containers in the task by the 300 MB (or 512 MB) requested by the Insights Agent.

Frequently asked questions

The following topics can help you get traffic in the appropriate state and get API models to show the information you need.

• Why isn't my API traffic showing up?

• What do I do if my traffic is encrypted?

• What does the Insights Agent do with sensitive data?

• I can't update my Insights Project.

• I'm not seeing the traffic I'm looking for in my API model.

• My API model is mostly health checks and infrastructure endpoints.

Why isn't my API traffic showing up?

You've set up the Insights Agent, and you've been running API traffic across the network, but your API model page is either empty or shows random endpoints you don't care about.

Here are a few things that may be going on:

• Permission issues that prevent the Insights Agent from seeing traffic.
• Encrypted traffic. See What do I do if my traffic is encrypted? for solutions.
• Data formats that the Insights Agent doesn't recognize.
• ECS on EC2 with bridge networking. You can install Insights Agent as a daemon service only. See the installation instructions.

In many of these cases, there is a solution. The Insights Agent doesn't support these three cases:

• Encrypted traffic.
• gRPC/GraphQL.
• PaaS platforms where the Insights Agent can't easily access the network traffic through packet capture. Known platforms in this category are Heroku and Render.

If you experienced one of these cases, contact the Insights team so work in this area can be prioritized.

Postman provides more information about how to debug what's going on:

• Diagnostic information in the CLI itself
• Information about encrypted traffic and errors in Postman

Check your CLI output

If your traffic is getting blocked in a way that the Insights Agent recognizes, your CLI shows error output describing what's gone wrong. If you need help resolving your issues, email your log output to Support.

Check the Insights Project diagnostics

Issues with traffic processing appear in the Insights Project's Diagnostics tab.

What do I do if my traffic is encrypted?

If your model is missing expected endpoints or is empty, you may be trying to observe your API at a point where it's encrypted. In Postman, navigate to the Insights Project's Diagnostics tab and review the client reports listed there. Check to see whether the Insights Agent detected any traffic encrypted with TLS.

Add a reverse proxy

If HTTPS currently terminates at your application, then the Insights Agent won't be able to see the unencrypted version of your data. You could reconfigure your deployment to let the Insights Agent see the unencrypted data by adding a reverse proxy to serve as the HTTPS endpoint.

See NGINX Reverse Proxy for instructions on setting up the open-source web server NGINX as a reverse proxy. This reverse proxy can be set up as part of your container image or run as a sidecar.

When configured with your certificate, the reverse proxy accepts the HTTPS connection from clients, decrypts the data, and then sends the unencrypted data to your application. The unencrypted data can be observed by the Insights Agent on the local network. The easiest way to get started with this configuration is to have both NGINX and the Insights Agent configured as sidecars in your application container.

Use HTTP from the load balancer instead of HTTPS

If you are using a load balancer, and your security policy permits it, you could have the load balancer terminate HTTPS, and communicate to the application using unencrypted HTTP. Amazon's Application Load Balancer supports using either HTTP or HTTPS as a target, but only HTTP will be visible to the Insights Agent.

What does the Insights Agent do with sensitive data?

The Insights Agent obfuscates request/response payload data and sends only request/response metadata to our servers.

The Insights Agent sends salted hashes of request/response payload data. The Postman cloud isn't able to access this information, so the Postman cloud never accesses your sensitive data.

I can't update my Insights Project.

You may come across the following error message when you attempt to update your Insights Project.

[ERROR] You cannot send traffic to the to the service with ID svc_01234AaBbCcDd. Ensure that your collection ID is correct and that you have edit permissions on the collection. If you don't have edit permissions, please contact the workspace administrator to add you as a collection editor.

This issue can occur for the following reasons:

• You don't have the right project ID. To locate the project ID, select your Insights Project and then select the Diagnostics tab. The project ID is an alphanumeric string that begins with svc_.

  

• You don't have the required permission. Please contact your Workspace Admin for access.

I'm not seeing the traffic I'm looking for in my API model.

The endpoints you expected to see in your first Insights Project may not be appearing for the following reasons:

• The Insights Agent is seeing mostly health checks and infrastructure endpoints, and your other traffic isn't getting through.
• Your endpoints are encrypted. See What do I do if my traffic is encrypted? for workarounds.
• Your model is cluttered with endpoints that you don't want to see. You can filter them out as described below.

My API model is mostly health checks and infrastructure endpoints.

You may have been able to successfully generate an API model, but most of what you're seeing is health checks.

Load balancers and orchestration systems often use a health endpoint to verify whether a service is live. Similarly, your system may call AWS endpoints as part of its regular functioning. Because these endpoints get called regularly, regardless of whether there is other traffic, the health endpoints could block your API model.

The Insights Agent samples your traffic, rather than sending all of your traffic to Postman. As a result, health check and infrastructure endpoints can dominate the traffic that the Insights Agent sees. The Insights Agent's rate limiting (which defaults to 1000 calls per minute) may cause some API calls to be dropped. Therefore, filtering out the health endpoints ensures that this limit is used for important endpoints.

To increase the Insights Agent's ability to capture meaningful, non-health check data, you can set up filters on the Insights Agent.

Filter out endpoints by path

You can filter out traffic by using the --path-exclusions flag.

To remove a health check endpoint, for instance, use apidump with the --path-exclusions flag, specifying the path part of the health check.

For example, the following command causes all the /health endpoints on all hosts to be ignored by the Insights Agent:

apidump --project <projectID> –-path-exclusions ^/health$

The argument to --path-exclusions is a Go regular expression, which may match any part of the path. The special characters ^ and $ set the start and end of a string, preventing the filter from matching other paths that include the string /health, like /employee/health-benefits.

Filter out endpoints by IP address

If your model contains API calls to unnamed infrastructure services accessed by the IP address, you can remove them by using a regular expression in the --host-exclusions flag, as follows:

apidump --project <projectID> –-host-exclusions ^(\d)+\.(\d)+\.(\d)+\.(\d)+$

This removes all endpoints whose host is given by a dotted-quad IP address.