Traceflow or port mirroring: which tool should you use?
Use Traceflow when you need to follow a synthetic packet through VMware NSX and identify the component or rule that forwards or drops it. Use port mirroring when you need a copy of real traffic for Wireshark or tcpdump. Start with Traceflow for path and policy validation; move to port mirroring only when packet-level evidence is required.
This guide applies to VMware NSX 4.x and NSX in VCF 9. Menu labels vary by release. The current Policy API uses paths under /policy/api/v1/infra/; several older Manager API examples are deprecated or removed in NSX 9. Confirm exact paths and request schemas against the API version exposed by your own NSX Manager before production use.
For the wider design context around NSX networking, platform dependencies, and workload placement, see the Hybrid Platform Architecture hub.
1. NSX-T Traceflow
How Traceflow Works
Traceflow lets you inject and trace synthetic packets through the NSX-T fabric, visualizing every hop, distributed firewall, logical switches, Tier-0/1 routers, edge nodes, and highlighting where packets are delivered or dropped.
Use Cases:
- Validate firewall policy behavior
- Troubleshoot VM-to-VM connectivity (overlay and VLAN)
- Diagnose misconfigurations or routing issues
Traceflow in Single-Site Topology
Diagram
Traceflow in NSX Manager
- Open Plan & Troubleshoot > Traffic Analysis > Traceflow. In releases that show a landing card, select Get Started.
- Select the source port or interface. Choose a destination supported by your release, then set the protocol and port that match the failed flow.
- Run the trace and follow each observation in order. Record the first drop, the reporting component, and the applied firewall, routing, NAT, or switching decision.
- If Traceflow reaches the expected NSX boundary but the application still fails, verify underlay routing and the destination independently, then use a narrowly scoped packet capture or port-mirroring session.
Broadcom’s current Traceflow UI example uses this workflow. Traceflow does not continue beyond the NSX environment and does not prove that a real application packet was generated.
Traceflow through the current Policy API
Current releases expose Traceflow through the Policy API. The older Manager endpoint /api/v1/traceflows is deprecated, and parts of that older interface were removed in NSX 9. Use the versioned Broadcom Traceflow API reference or download the OpenAPI specification directly from your manager before building automation.
| Operation | Current Policy API path | Purpose |
|---|---|---|
| List | GET /policy/api/v1/infra/traceflows | Inventory active Traceflow configurations. |
| Create or replace | PUT /policy/api/v1/infra/traceflows/{traceflow-id} | Start a version-matched Traceflow definition. |
| Status | GET /policy/api/v1/infra/traceflows/{traceflow-id}/status | Check whether the trace completed or failed. |
| Observations | GET /policy/api/v1/infra/traceflows/{traceflow-id}/observations | Retrieve the reported forwarding and drop observations. |
| Cleanup | DELETE /policy/api/v1/infra/traceflows/{traceflow-id} | Remove a non-transient configuration when it is no longer needed. |
A create request needs a valid source segment-port path or UUID plus a packet definition accepted by the deployed release. Those values are environment-specific. Build the request from your manager’s schema, validate it in nonproduction, and use a short-lived test ID rather than copying a generic payload into production.
PowerCLI and SDK boundary
Broadcom documents Connect-NsxtServer and service-binding cmdlets in the VMware NSX-T Data Center PowerCLI module. It does not document the high-level Start-NsxtTraceflow, Get-NsxtTraceflowResult, or New-NsxtPortMirroringSession commands that appeared in the earlier version of this article.
$credential = Get-Credential
$nsx = Connect-NsxtServer -Server 'nsx-manager.example.com' -Credential $credential
# Inspect the commands actually installed in this environment.
Get-Command -Name '*Nsxt*' | Sort-Object Name
For new automation, prefer the version-matched NSX Policy SDK or the manager’s OpenAPI schema. Treat older service-binding examples as compatibility code because Broadcom marks Get-NsxtPolicyService deprecated. Use least-privilege credentials, keep certificate validation enabled, and never embed a password in a script or article example.
Real-World Traceflow: Multi-Site with Edge
Diagram
Interpreting Traceflow Results
- Green check: Packet delivered, all hops successful
- Red X: Drop detected, with reason (firewall rule, routing loop, interface down)
- Hop-by-hop: DFW, logical switch, router, edge, and uplink actions
- Common Issues:
- Misapplied DFW rules
- Incorrect overlay-to-physical mapping
- Edge node routing or NAT issues
2. NSX-T Port Mirroring
Overview
Port mirroring copies selected real traffic to an analysis destination. It is appropriate when you need packet-level evidence, but it can expose sensitive data and consume host, overlay, and collector resources. Scope the source, direction, filter, packet length, and capture duration as narrowly as possible.
The current NSX Policy API schema exposes two profile types:
- LOGICAL_SPAN for logical port or workload-oriented mirroring inside the NSX environment.
- REMOTE_L3_SPAN for an IP-based remote destination, with GRE, ERSPAN II, or ERSPAN III encapsulation where supported.
Port Mirroring Topology Example
Diagram
Set up a controlled port-mirroring session
- Define the troubleshooting question, exact source workload or segment, traffic direction, protocol filter, and stop time before creating the session.
- Place the analyzer in an isolated destination with enough capacity and access controls for the traffic it may receive.
- Create a logical SPAN or remote L3 SPAN profile. For remote L3 SPAN, validate collector support, routing, MTU, and the selected GRE or ERSPAN encapsulation.
- Bind the profile only to the intended source port or segment, start a short capture, and confirm that the analyzer receives the expected direction and protocol.
- Stop the capture and remove the binding and temporary profile as soon as the evidence is collected.
Current port-mirroring API model
The current Policy API uses a two-part model: create a port-mirroring profile, then apply it with a port-monitoring profile binding map. The older article’s POST /api/v1/port-mirroring-sessions example does not represent this current model.
| Stage | Policy API path |
|---|---|
| Inventory profiles | GET /policy/api/v1/infra/port-mirroring-profiles |
| Create or replace a profile | PUT /policy/api/v1/infra/port-mirroring-profiles/{profile-id} |
| Apply to a segment port | PUT /policy/api/v1/infra/segments/{segment-id}/ports/{port-id}/port-monitoring-profile-binding-maps/{binding-id} |
| Clean up | Delete the binding first, then delete the temporary profile. |
Profile fields and binding paths vary with the selected type and release. Generate the request from the deployed manager’s schema, use a change-controlled nonproduction test, and verify realization before relying on the capture. Do not disable TLS validation or place administrator credentials on the command line.
Real-World Scenario
Set up remote port mirroring from a production VM segment to an Analyzer VM. Use Wireshark or tcpdump to inspect mirrored packets, analyze for packet loss, retransmissions, or traffic anomalies.
3. Use Cases and Troubleshooting
| Troubleshooting question | Traceflow | Port mirroring |
|---|---|---|
| Where does NSX forward or drop a synthetic packet? | Best fit | Not the primary tool |
| Which NSX firewall, routing, NAT, or switching decision acted? | Best fit | Packet evidence only |
| Did the application send real packets? | No | Best fit |
| Are retransmissions, loss, latency, or jitter visible in real traffic? | Limited to path validation | Best fit |
| Do you need protocol fields or payload-level evidence? | No production payload | Best fit, subject to policy |
Example: Troubleshooting Inter-Site Latency
- Use Traceflow to confirm correct routing and policy between sites.
- Use Port Mirroring to capture actual packets and diagnose network delay, loss, or retransmissions.
4. Best Practices, Limitations, and Gotchas
- Preserve trust: use a trusted NSX Manager certificate; do not normalize
-k,verify=False, or global certificate bypasses. - Protect credentials: prompt securely or use an approved secret store and a least-privilege troubleshooting account.
- Minimize capture scope: select the smallest source, direction, filter, snap length, and time window that can answer the question.
- Treat mirrored packets as sensitive data: obtain the required change, privacy, and security approval; isolate the analyzer and restrict access to capture files.
- Watch resource impact: monitor the source host, overlay, analyzer, and remote collector while mirroring is active.
- Clean up: stop the session and remove temporary bindings, profiles, credentials, and packet captures when the investigation ends.
- Know the boundary: Traceflow follows a synthetic packet inside NSX; use packet capture, host checks, and physical-network evidence for what lies beyond that boundary.
For the operating model around incident response, observability, and recovery, continue to Operations & Resilience.
5. Conclusion
Traceflow and port mirroring answer different questions. Start with Traceflow to locate an NSX path or policy decision, then move to a tightly scoped port-mirroring session only when real-packet evidence is necessary. Use the current Policy API or version-matched SDK, preserve certificate validation, and remove temporary troubleshooting objects after the investigation.
Disclaimer
The views expressed in this article are those of the author and do not represent the opinions of VMware, my employer, or any affiliated organization. Always refer to the official VMware documentation before production deployment.
Table of Contents 1. Introduction: Why YAML-Driven IaC for NSX-T? Modern IT organizations demand agility, repeatability, and compliance. Infrastructure as Code (IaC)...
2 thoughts on “NSX-T Traceflow and Port Mirroring Troubleshooting Guide”