Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,19 @@ MIT License
Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ Use FPGA/SFP datapath timestamping with custom SLA probe packets.
- [Architecture](#-architecture)
- [Packet flow](#-packet-flow)
- [Benchmark & analytics](#-benchmark--analytics)
- [Sample result package](#-sample-result-package)
- [Measurement credibility](docs/measurement-credibility.md)
- [Engineering metrics](docs/engineering-metrics.md)
- [SLA report template](reports/sla_report.template.md)
Expand Down Expand Up @@ -127,6 +128,23 @@ The same flow is checked by GitHub Actions in `synthetic-sla-demo.yml`. The inpu

![SLA dashboard](docs/assets/sla_dashboard.svg)

The dashboard is populated with the baseline metrics from the committed
sample result package under `results/sample-test-1/`.

---

## Sample result package

The repository includes a small checked-in result set that reviewers can open
without generating new data:

- [Sample summary](results/sample-test-1/summary.md)
- [Sample plot package](results/sample-test-1/plots/README.md)
- [Filled report example](reports/sla_report.example.md)

It is intentionally compact, but it gives the repository one concrete
measurement artifact path instead of only templates.

---

## 🧪 Case study
Expand Down
16 changes: 8 additions & 8 deletions docs/assets/sla_dashboard.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions reports/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ This directory is intended for generated measurement reports.
| Artifact | Purpose |
|---|---|
| `sla_report.md` | engineering SLA summary |
| `sla_report.example.md` | filled example based on committed sample metrics |
| `latency_distribution.png` | delay analysis |
| `jitter_histogram.png` | jitter visibility |
| `packet_loss_timeline.png` | transport stability |
Expand Down
71 changes: 37 additions & 34 deletions reports/sla_report.example.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@

| Field | Value |
|---|---|
| Scenario | software vs datapath timing comparison |
| Measurement window | example synthetic interval |
| SLA status | TBD |
| Main observation | timestamp origin strongly affects confidence |
| Scenario | baseline network test with two SFP modules in a serial path |
| Measurement window | sample exported interval from `results/sample-test-1/` |
| SLA status | PASS |
| Main observation | stable microsecond-scale delay with negligible loss and near line-rate throughput |

## Measurement topology

Expand All @@ -23,54 +23,57 @@ probe generator

| Item | Description |
|---|---|
| Timestamp origin | software or datapath |
| Clock source | documented per scenario |
| Uncertainty | explicitly listed in the report |
| Main risk | OS noise or clock drift, depending on method |
| Timestamp origin | sample exported summary from the repository result package |
| Clock source | not modeled in detail in this example package |
| Uncertainty | low for documentation review, still not a substitute for calibrated hardware validation |
| Main risk | the sample package demonstrates reporting structure more strongly than clock-origin rigor |

## SLA thresholds
## Example acceptance thresholds

| Metric | Threshold | Measured | Status |
|---|---:|---:|---|
| p95 latency | TBD | TBD | TBD |
| p99 latency | TBD | TBD | TBD |
| RMS jitter | TBD | TBD | TBD |
| Packet loss | TBD | TBD | TBD |
| RTT avg | <= 15.0 us | 12.4 us | PASS |
| RTT max | <= 20.0 us | 16.8 us | PASS |
| Jitter | <= 1.0 us | 0.4 us | PASS |
| Packet loss | <= 0.01% | 0.0001% | PASS |
| Throughput | >= 9.5 Gbps | 9.8 Gbps | PASS |

## Latency distribution
## Available artifacts

Expected artifact:
- `results/sample-test-1/summary.md`
- `results/sample-test-1/plots/sample-metrics.svg`
- `docs/assets/sla_dashboard.svg`

```text
reports/latency_distribution.svg
```
## Delay and directionality

## Jitter analysis
The committed sample package reports:

Expected artifact:
- RTT min: 11.7 us
- RTT avg: 12.4 us
- RTT max: 16.8 us
- OWD forward: 6.1 us
- OWD reverse: 6.3 us

```text
reports/jitter_histogram.svg
```
The forward and reverse directions are close enough to treat the path as balanced in this example.

## Packet-loss timeline
## Jitter and loss interpretation

Expected artifact:
The sample run shows low timing variation and effectively zero loss:

```text
reports/packet_loss_timeline.svg
```
- jitter: 0.4 us
- packet loss: 0.0001%
- throughput: 9.8 Gbps

That combination is consistent with a clean baseline path rather than congestion, queue buildup or bursty impairment.

## Root-cause hypothesis

Potential explanations:

- queue buildup;
- unstable host timing;
- packet burst effects;
- clock uncertainty;
- link-level issues.
- no strong fault signal is visible in the sample package;
- residual variation is consistent with a healthy baseline export;
- deeper root-cause work would need packet-level traces and timestamp-origin details.

## Engineering conclusion

The report should state whether the SLA conclusion is valid, uncertain or blocked by missing timing assumptions.
The committed result package is suitable as a reviewer-facing example because it contains a concrete summary, a concrete plot artifact and a filled report. It still does not replace calibrated hardware validation, but it closes the gap between pure templates and real measurement evidence.
16 changes: 11 additions & 5 deletions results/sample-test-1/plots/README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
# Plots

Place exported latency, jitter or throughput plots here.
This folder stores small reviewer-facing plot artifacts derived from the
committed sample result package.

Suggested files:
- latency-histogram.png
- jitter-timeseries.png
- throughput-summary.png
## Available files

- `sample-metrics.svg` - compact summary of delay, jitter, packet loss and throughput.

## Suggested future additions

- `latency-histogram.png`
- `jitter-timeseries.png`
- `throughput-summary.png`
62 changes: 62 additions & 0 deletions results/sample-test-1/plots/sample-metrics.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading