At a glance
The results API adds two new views of network results:- a ranking of the ports most affected during a run;
- switch buffer-pool usage by tier.
- Parquet result files. Runs on the optimized execution path also list Parquet copies of their result files, ready to download.
- Fixes. The collectives summary now works for runs that contain a Barrier collective. A topology with a switch tier that has no capacity no longer fails validation with a division-by-zero error.
- Reliability. Results and log requests now fail quickly with a 503 or 504 when the simulation’s state cannot be read. Previously they could wait indefinitely.
- API specification. The specification adds the operations and values described below and documents the new statuses.
- Security. The release includes security updates.
The simulator software version stays at 4.8.1. The simulator build in this release updates its base image and carries the configuration-check fixes listed under Issues resolved.
No results change in this release. A configuration that ran on 0.1.2544 gives the same simulation results and the same output files. Four changes affect what the results API returns, without changing any existing value:No defaults change, and no model versions change.
- Results listings gain Parquet files. On the optimized execution path,
GET .../resultslists Parquet copies beside the CSV files. Code that downloads every listed file should filter bytype.- The RoCE transport summary gains a key.
transport.columnsgainsnumPktsRcvdSum, and the RoCE time series gainsintervalNumPktsRcvdSum.- Collectives summaries for runs with a Barrier collective. These previously failed and now return data. A Barrier has no ideal model, so its ideal ratios are reported as 0.
- Cached summaries are recomputed once. The first summary or time-series request for an existing run after the upgrade can take longer.
Issues resolved
Collectives summary for runs with a Barrier collective
GET /api/v1/simulations/{sim_id}/results/data?metric=collectives failed with a server error for any run whose trace contains a Barrier collective. The collectives output writes NA in a Barrier’s ideal-ratio columns, and the results service could not read it. The summary now returns data for these runs. A Barrier’s ideal ratios are reported as 0, because no ideal model exists for a Barrier.
Topology validation of a tier with no capacity
A topology in which a switch tier has no capacity in use, for example a spine tier with no downlinks, failed validation withException float division by zero (or Exception division by zero for chassis-capacity switches). Such a topology now passes this check, and the per-tier subscription-ratio note reports n/a for that tier. If the topology has another configuration error, that error is now reported instead of the division error.
Clearer error for a rack group with two NIC or host names
A rack group that names more than one NIC, or more than one host, is still refused, but with an error that states the problem. The old error showed only the second name, for exampleException 'nic2'. The new errors read:
More than one NIC name in <rack>, <group> (<names>): each host can be linked to only one NICMore than one host name in <rack>, <group> (<names>): a group can hold only one host name
Top ports and switch buffer pools
Top ports ranking
GET /api/v1/simulations/{sim_id}/results/data?metric=nd-stats&mode=topPorts ranks a run’s ports by how much each was affected during the run, and backs the Top ports by severity class chart in the web application’s results view. tier selects the network tier, and portsPerRanking sets how many ports each ranking returns, from 3 to 10; the default is 5.
Switch buffer-pool statistics
The results API now summarizes the switch buffer statistics that every Scala Switch writes (*-scala-switch-agg-buff-stats-*.csv). The new metric is metric=scala-switch-agg-buff-stats.
mode=summaryreturnsbufferPools.pools, one entry for each combination of tier, buffer class, direction and pool. Each entry gives:peakBytes,minBytesandmeanBytes;peakUtilPctandmeanUtilPct;bufferLimitBytes,switchCountandrowCount.
- Buffer classes.
bufferClassissharedBuffer,ingressUsageoregressQueue.directionisulordl, and it is omitted for shared buffers. mode=timeSeriesreturns one group for each pool, keyed{tier}:{bufferClass}:{direction}:{pool}.- Utilization above 100%. Utilization is computed from bytes and is not clamped, so a lossless egress pool can report more than 100%. The percentage columns of the CSV files are clamped at 100.
- No buffer rows. A finished run that has no buffer rows returns a summary without
bufferPools. mode=sampledreturns 501 for this metric.
RoCE received-packet total
The RoCE transport summary (metric=roce-transport-stats, mode=summary) gains numPktsRcvdSum in transport.columns. The RoCE time series gains intervalNumPktsRcvdSum.
Both are totals of received packets: the sum of the NIC’s received connection packets, ACKs, SACKs, NACKs, RDMA writes, RDMA sends and CNPs. The RoCE NIC records no total of its own. The UET transport summary does not change.
New in this release
Parquet result files
Runs on the optimized execution path now also provide their result files as Parquet, a compressed columnar format.- Listing.
GET /api/v1/simulations/{sim_id}/resultslists Parquet files astype: parquet, beside the CSV files.type=parquetlists only the Parquet files. - Download.
GET /api/v1/simulations/{sim_id}/results/download-urlreturns a download link for a Parquet file, as it does for a CSV file. - Complete or not listed. Parquet files for a result type, such as
nd-stats, are listed only when every CSV file of that type in the run has been converted and verified. Otherwise that result type is listed as CSV only. CSV files are always listed. - Columns. A Parquet file holds the columns the results service reads. Use the CSV file for the original columns. A CSV file that holds only a header has no Parquet file.
- Which runs. Parquet files are written when a run on the optimized execution path finishes. Runs on the standard path have CSV files only, and so do runs that finished before this release. Runs of more than 4,096 hosts use the standard path.
API specification changes
-
New query mode and parameter on
GET /api/v1/simulations/{sim_id}/results/data.modegainstopPorts.metricgainsscala-switch-agg-buff-stats.- The new query parameter
portsPerRankingapplies only tomode=topPorts. Any other request names it inX-Ignored-Params.
-
New schemas.
TopPortsDocument, with its ranking schemas.BufferPoolSummary,BufferPoolStats,BufferClassandBufferDirection.- The optional
SimulationSummary.bufferPools.
-
New response value.
ResultFile.type, and thetypefilter ofGET .../results, gainparquet. See Parquet result files. A client generated before this release fails on a listing that contains a Parquet file, so regenerate clients. -
Documented 503 and 504 statuses. These operations now document both:
GET .../results;GET .../results/download-url;GET .../logs.
GET .../results/datadocuments a 504 for the same cause. See Platform reliability and stability.
Web application
Results view
The results view adds these charts:- Summary tab.
- Top ports by severity class lists the ports most affected during the run, from the top ports ranking.
- Fabric link utilization shows the run’s mean transmit and receive utilization of fabric-switch links. It grades each against these bands, with a 70% target:
- Underused;
- Healthy;
- Heavily loaded;
- Saturated.
- Throughput tab. Scale-out uplink fairness per switch is a heat map of each switch’s uplink fairness (Jain index) over time.
- Congestion & drops tab.
- Head-of-line blocking severity by tier is a heat map, by tier, of the largest share of each step that a port spent paused while its egress queue held data.
- Five buffer-pool charts plot occupancy by tier, from the new buffer-pool statistics. An egress pool can read above 100%.
- Shared buffer pool usage by tier.
- Uplink ingress buffer pool usage by tier and Downlink ingress buffer pool usage by tier.
- Uplink egress queue pool usage by tier and Downlink egress queue pool usage by tier.
- Transport tab. The tab opens with two tables of end-of-run transport statistics, for RoCE and UET runs:
- Packets by direction;
- Reliability and latency.
- Workload tab. Completion time vs simulation time is a heat map of how many operations completed in each completion-time band across the run.
- Chart load failures. A chart that fails to load keeps its title and names the data it could not load.
- Chart downloads. The PNG, SVG and CSV downloads of the uplink fairness and head-of-line blocking charts now carry what the chart shows.
- Raw data files. The raw data files list shows Parquet files beside CSV files, and it has Next page and First page controls.
Traceset upload
Uploading a traceset from the web application is fixed. Uploads did not finish before, whatever the file size.- Every upload, small or large, now uses the same upload operations as the API.
- An upload now waits while the platform finishes copying a large file, instead of stopping after 10 seconds.
Model catalog changes
No model versions change in this release.Platform reliability and stability
- Results and logs no longer wait indefinitely. Reading a simulation’s state is now bounded in time. When the read cannot be completed, these operations return a status instead of holding the request open:
- Results, result downloads and logs return 503 when the simulation’s state cannot be read, and 504 when the read takes too long. Retry with backoff, with a limit on the number of attempts.
GET /api/v1/simulationsandGET /api/v1/simulations/{sim_id}return the simulation’s last recorded status.
- Very large summary requests are refused sooner. Some summary and time-series requests for the largest runs are too large to serve. These now return 413 before any data is read. Requests for the same result that are waiting on a refused request now get the same 413, instead of each one waiting and timing out.
- Clearer error when a result has no data. The 404 for a result with no data files now names the simulation, for example
No data files found for metric pfc in simulation sim_…. It used to sayin simulation unknown.
Security updates
This release contains security updates. We recommend upgrading. In keeping with our disclosure practice, we do not publish details of security fixes. Customers with a specific compliance question should contact their Scala representative.Documentation
API reference. It is updated for:- the switch buffer-pool statistics;
- the RoCE received-packet total;
- the
parquetfile type; - the new 503 and 504 statuses.
Not included in this release
The following remain open and are not addressed by 0.1.2840:- Chakra workloads on the Scala MRC NIC. A Chakra simulation on MRC NICs does not yet run to completion.
- Mapping files above 4,096 ranks. Mapping-file support covers simulations of up to 4,096 ranks. A larger simulation with a mapping file attached fails with
Mapping file <name> (<id>) could not be delivered. - Mapping files with the platform’s own Chakra tracesets. A simulation from such a configuration fails before the simulator starts. Mapping files work on tracesets you upload.
- Summary metrics for the largest result sets. Summaries for the largest runs, such as 8,192 ranks, can still be refused as too large. Raw result files remain available through the results download operations.
- Pre-simulation run-time estimation. There is still no supported way to tell in advance whether a trace will exceed the configured simulation time limit.
- ECN-marked packet counts received at the NIC. NIC-side receive counters for ECN-marked packets are not yet reported. Switch-side ECN information remains available.
- Mixed NIC types in a Chakra simulation. All servers in a Chakra simulation must use the same NIC type.
- Parquet files for standard-path and earlier runs. Runs on the standard path, including runs of more than 4,096 hosts, have CSV result files only. So do runs that finished before this release.
Upgrade notes
- Automatic updates. The updated simulator build is applied with the platform upgrade. No configuration changes are needed.
- First summary requests after the upgrade. Cached summaries and time series are recomputed once, so the first such request for an existing run can take longer.
-
Regenerate API clients. Regenerated clients pick up:
- the top ports mode;
- the buffer-pool metric and schemas;
- the
parquetfile type; - the documented 503 and 504 statuses.
-
Downloading every listed file. Results listings of optimized-path runs now include Parquet files. Filter by
typeif you want only CSV. - Retry on 503 and 504. Results, download and log requests can now return these statuses when the simulation’s state cannot be read in time. Retry with backoff and a bounded number of attempts.
-
RoCE transport readers. Code that reads
transport.columnsor the RoCE time series by a fixed key set must allow fornumPktsRcvdSumandintervalNumPktsRcvdSum. - Collectives readers. Runs with a Barrier collective now return collectives summaries. A Barrier’s ideal ratios are 0, so do not read 0 there as a measured result.