{"id":47669941,"url":"https://github.com/algoryn-io/pulse","last_synced_at":"2026-05-01T04:03:44.669Z","repository":{"id":342730207,"uuid":"1174922505","full_name":"algoryn-io/pulse","owner":"algoryn-io","description":"Programmable load testing engine in Go with arrival-rate scheduling, thresholds, and structured JSON output.","archived":false,"fork":false,"pushed_at":"2026-04-26T23:11:50.000Z","size":428,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T00:24:00.207Z","etag":null,"topics":["cli","golang","http","load-testing","observability","performance-testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/algoryn-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-07T01:55:04.000Z","updated_at":"2026-04-26T23:11:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/algoryn-io/pulse","commit_stats":null,"previous_names":["jmgo38/pulse"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/algoryn-io/pulse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algoryn-io%2Fpulse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algoryn-io%2Fpulse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algoryn-io%2Fpulse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algoryn-io%2Fpulse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/algoryn-io","download_url":"https://codeload.github.com/algoryn-io/pulse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algoryn-io%2Fpulse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32484353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","golang","http","load-testing","observability","performance-testing"],"created_at":"2026-04-02T12:30:29.798Z","updated_at":"2026-05-01T04:03:44.652Z","avatar_url":"https://github.com/algoryn-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pulse: High-Precision Performance Testing for Algoryn Fabric\n\n[![CI](https://github.com/algoryn-io/pulse/actions/workflows/ci.yml/badge.svg)](https://github.com/algoryn-io/pulse/actions)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/algoryn-io/pulse)](https://go.dev/doc/install)\n[![Latest Release](https://img.shields.io/github/v/release/algoryn-io/pulse)](https://github.com/algoryn-io/pulse/releases)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Go Reference](https://pkg.go.dev/badge/algoryn.io/pulse.svg)](https://pkg.go.dev/algoryn.io/pulse)\n\n**Pulse** is a load and reliability testing tool built for the Algoryn Fabric stack. It drives HTTP workloads with predictable arrival rates, reports latency and error metrics you can trust in CI, and enforces SLOs through configurable pass/fail thresholds. The runtime combines **Go** for high-throughput orchestration and **C++** for **constant-memory, high-dynamic-range (HDR) latency histograms**, so performance metrics stay accurate and lightweight even on long, heavy runs.\n\n---\n\n## Architecture highlights\n\n### Hybrid engine\n\n- **Go** — Schedules load across **constant, ramp, step, and spike** phases, bounds concurrency with a limiter, and runs scenarios at the target requests-per-second. This layer is where scale and determinism come from: token-bucket pacing, goroutine lifecycle, and the `pulse` / library API.\n- **C++ (via cgo)** — A native **HDR-style logarithmic histogram** records every latency sample in **O(1)** time with a **fixed bucket count**. The engine covers roughly **1 microsecond to 60 seconds** on a single run with **sub-microsecond** resolution in the low-latency regime and a **stable, constant memory footprint** (no unbounded per-sample storage in the hot path). Percentiles (**P50, P90, P95, P99**) are derived from that histogram, then combined in Go with exact **min, max, and mean** tracking.\n\nThis split keeps the scheduler and network I/O in idiomatic, concurrent Go while entrusting percentile math to a compact, allocation-friendly path suited to long campaigns and high sample counts.\n\n### Fabric integration\n\nPulse depends on [`algoryn.io/fabric`](https://github.com/algoryn-io/fabric) **v0.2.0+** for shared contracts, including **Protocol Buffer** messages under `algoryn.io/fabric/gen/go/fabric/v1`.\n\n- **`ToRunEvent`** maps a `pulse.Result` into the legacy Go types `metrics.RunEvent` / `metrics.MetricSnapshot` (`algoryn.io/fabric/metrics`).\n- **`ToRunEventProto`** returns the same data as **`fabric.v1.RunEvent`** (with **`fabric.v1.MetricSnapshot`** inside), using Fabric’s **`RunEventToProto`** helper so timestamps are **`google.protobuf.Timestamp`**.\n- **`ToFabricRunEmit`** returns a matched pair: the full **`RunEvent`** protobuf and a **`fabric.v1.Event`** with **`EVENT_TYPE_RUN_COMPLETED`** (payload built with **`RunCompletedPayloadToProto`**), sharing one **`run_id`** so tools like **Beacon** can correlate summary events with detailed snapshots. The envelope timestamp uses **`timestamppb.Now()`**.\n- Set **`Config.Service`** (optional) to populate **`MetricSnapshot.service`** and the run-completed payload; use **`Config.OnFabricEmit`** to receive both protobuf messages after each run (after threshold evaluation, same ordering as **`OnResult`**).\n\nThe CLI still prints human JSON for operators; wire **`OnFabricEmit`** (or call **`ToRunEventProto`**) when you need **proto/binary** or **protojson** on the wire.\n\n---\n\n## Key features\n\n| Area | What you get |\n|------|----------------|\n| **Load model** | **Multi-phase** tests: **Constant**, **Ramp**, **Step**, and **Spike** — arrival-rate (RPS) driven, not a vague “VUs” count. |\n| **Latency** | **P50, P90, P95, P99** (plus min, mean, max) from the **C++ histogram**; stable under load, bounded memory. |\n| **Configuration** | **YAML** test definitions: target, phases, `maxConcurrency`, and optional **thresholds** (error rate, mean / P95 / P99 latency). |\n| **Output** | **Text** (human-readable) and **JSON** (automation, CI artifacts); combine `--json` and `--out` to mirror JSON to a file. |\n| **API** | Use **`pulse.Run`**, `OnResult` hooks, optional **`OnFabricEmit`** for **Fabric protobuf** (`RunEvent` + `RunCompleted` event), and **middleware** for chaos-style scenarios; **`RunT`** for `go test` integration. |\n| **Tooling** | Optional **`mockserver`** for local demos; see [`examples/`](examples/). |\n\n---\n\n## Installation\n\n### Requirements\n\n- **Go** — Version compatible with [`go.mod`](go.mod) (see badge above).\n- **C/C++ toolchain for cgo** — Pulse links a small C++ stats library. You need a working C++17 compiler the Go toolchain can invoke:\n  - **macOS**: Xcode Command Line Tools (`clang++`) are typically enough.\n  - **Linux**: **GCC** or **Clang** with `g++` / `clang++` and `libstdc++` or `libc++` as appropriate for your distribution.\n\nSet `CC` and `CXX` if you use a non-default compiler:\n\n```sh\nexport CC=clang\nexport CXX=clang++\n```\n\n### Get Pulse\n\n**From the module** (for library use):\n\n```sh\ngo get algoryn.io/pulse@latest\n```\n\n**From a clone of this repository:**\n\n```sh\ngo install ./cmd/pulse\ngo install ./cmd/mockserver   # optional, for local testing\n```\n\nEnsure your `GOBIN` (or `GOPATH/bin`) is on `PATH` so the `pulse` binary is found.\n\n---\n\n## Usage\n\n### Run a test\n\n```sh\npulse run path/to/config.yaml\n```\n\n**Useful flags**\n\n| Flag | Description |\n|------|-------------|\n| `--json` | Print results as **JSON** on stdout. |\n| `--out \u003cfile\u003e` | Write the same JSON object to a file (can be combined with `--json`). |\n\n**Exit codes** — `0` success; `2` run finished but **thresholds failed**; `1` for usage, config, I/O, or other failures (including mixed error types).\n\n### Sample YAML\n\n```yaml\n# Steady load with latency SLOs (example: local mock server on :8080)\nphases:\n  - type: constant\n    duration: 5s\n    arrivalRate: 20\n\ntarget:\n  method: GET\n  url: http://localhost:8080\n\nmaxConcurrency: 4\n\nthresholds:\n  maxMeanLatency: 100ms\n  maxP95Latency: 150ms\n  maxP99Latency: 200ms\n```\n\nRun against a live target or, for a quick check, start the bundled mock in another terminal: `go run ./cmd/mockserver -mode healthy` and point the URL at it. More examples live under [`examples/`](examples/).\n\n### JSON result shape (summary)\n\nThe JSON report includes `summary` (totals, RPS, `duration_ms`), `latency` with **`min_ms`**, **`p50_ms`**, **`mean_ms`**, **`p90_ms`**, **`p95_ms`**, **`p99_ms`**, **`max_ms`**, `status_codes`, `errors`, per-threshold rows, and `passed`.\n\n---\n\n## Ecosystem\n\nPulse is part of the **Algoryn Fabric** ecosystem: shared contracts under `algoryn.io/fabric` help **Relay**, **Beacon**, and other tools present and consume performance and reliability data in a **consistent** way. Pulse focuses on *generating* evidence under load; Fabric types carry that evidence to the rest of the stack.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgoryn-io%2Fpulse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falgoryn-io%2Fpulse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgoryn-io%2Fpulse/lists"}