{"id":28909118,"url":"https://github.com/bbortt/snow-white","last_synced_at":"2026-06-27T06:01:03.300Z","repository":{"id":299855640,"uuid":"570325948","full_name":"bbortt/snow-white","owner":"bbortt","description":"An awesome pairing with, well.. do you know Snow White and the Jaeger?","archived":false,"fork":false,"pushed_at":"2026-06-24T18:46:24.000Z","size":7161,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-24T19:14:07.037Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbortt.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":"2022-11-24T22:48:27.000Z","updated_at":"2026-06-24T18:28:26.000Z","dependencies_parsed_at":"2025-07-25T21:30:35.655Z","dependency_job_id":"ebf19137-7afd-4de6-b903-9c00311ae26a","html_url":"https://github.com/bbortt/snow-white","commit_stats":null,"previous_names":["bbortt/snow-white"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/bbortt/snow-white","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbortt%2Fsnow-white","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbortt%2Fsnow-white/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbortt%2Fsnow-white/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbortt%2Fsnow-white/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbortt","download_url":"https://codeload.github.com/bbortt/snow-white/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbortt%2Fsnow-white/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34843147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"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":[],"created_at":"2025-06-21T17:07:13.868Z","updated_at":"2026-06-27T06:01:03.292Z","avatar_url":"https://github.com/bbortt.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eSnow-White 🍎\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\".github/logo.png\" alt=\"Snow-White Logo\" width=\"100px\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ci\u003eOpenAPI coverage and quality insights powered by OpenTelemetry.\u003c/i\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://bbortt.github.io/snow-white\"\u003e» Documentation\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/bbortt/snow-white/releases\"\u003e\n    \u003cimg alt=\"GitHub Release\" src=\"https://img.shields.io/github/v/release/bbortt/snow-white\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/bbortt/snow-white/actions/workflows/branches.yml\"\u003e\n    \u003cimg alt=\"GitHub Actions Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/bbortt/snow-white/branches.yml\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://sonarcloud.io/project/overview?id=bbortt_snow-white\"\u003e\n    \u003cimg alt=\"Sonar Reliability Rating\" src=\"https://sonarcloud.io/api/project_badges/measure?project=bbortt_snow-white\u0026metric=reliability_rating\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://sonarcloud.io/project/overview?id=bbortt_snow-white\"\u003e\n    \u003cimg alt=\"Sonar Coverage\" src=\"https://img.shields.io/sonar/coverage/bbortt_snow-white?server=https%3A%2F%2Fsonarcloud.io\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nSnow-White connects your OpenAPI specifications with runtime telemetry data to answer a simple question: **which parts\nof your API are actually being tested?**\n\nIt correlates [OpenTelemetry (OTEL)](https://opentelemetry.io) traces emitted by your application with the endpoints\ndeclared in your API specifications - then validates coverage against configurable quality gates.\n\nSnow-White works with **black-box test suites** (system tests, integration tests) as well as **live production traffic\n**.\n\nIt currently provides insights into:\n\n- **Coverage** - which endpoints were exercised and which were not\n- **API Performance** - response time analysis across operations\n\n## Documentation\n\nFull documentation is available at **[bbortt.github.io/snow-white](https://bbortt.github.io/snow-white)**.\n\n| Section                                                          | Description                                                 |\n| ---------------------------------------------------------------- | ----------------------------------------------------------- |\n| [Deployment](https://bbortt.github.io/snow-white/deployment)     | Install Snow-White with Helm and configure your environment |\n| [Onboarding](https://bbortt.github.io/snow-white/onboarding)     | Step-by-step guide to integrating your service              |\n| [Architecture](https://bbortt.github.io/snow-white/architecture) | Component overview and event-driven design                  |\n| [Workflows](https://bbortt.github.io/snow-white/workflows)       | CI/CD pipeline patterns and quality gate workflows          |\n| [CLI Reference](https://bbortt.github.io/snow-white/cli)         | Full CLI command reference                                  |\n| [Requirements](https://bbortt.github.io/snow-white/requirements) | System and dependency requirements                          |\n| [License](https://bbortt.github.io/snow-white/license)           | Licensing details and commercial use                        |\n\n## Installation (for providers)\n\nSnow-White can be installed easily using Helm.\nDetailed instructions and available options are described\nin [\"Deployment\"](https://bbortt.github.io/snow-white/deployment).\n\nIndividual images could also be used for a custom installation.\nThe Docker compose file `dev/docker-compose.yaml` may be used as a starting point.\n\n## Onboarding (for users)\n\nSee [\"Onboarding\"](https://bbortt.github.io/snow-white/onboarding) for a step-by-step guide to integrating your service\nwith Snow-White.\n\n## General Concept\n\nHere's a high-level overview of Snow-White.\nFor a detailed component and data-flow breakdown, see\nthe [Architecture](https://bbortt.github.io/snow-white/architecture) docs.\n\n1. **Synchronize API Specs** - Snow-White imports OpenAPI specifications from your central interface repository.\n2. **Ingest Telemetry** - It listens to OpenTelemetry tracing data emitted by your applications.\n3. **Correlate \u0026 Analyze** - Traces are matched with API operations using service, API name, and version metadata.\n4. **Evaluate Quality Gates** - Results are validated against your configured thresholds.\n5. **Visualize or Export Results** - Coverage and performance insights can be viewed in reports or integrated into CI\n   pipelines.\n\n### Annotating APIs\n\nThe core idea behind Snow-White is that it can only interpret runtime telemetry (e.g. traces) if it knows which API the\ndata belongs to.\nThis is achieved by a common annotation model applied both to the specifications and to the telemetry data.\n\nEvery API must declare a few key identifiers:\n\n- **Service Name**: Identifies the logical unit or application that exposes the API.\n  - _Required_, because different applications may have identically named endpoints (e.g. `/health`).\n- **API Name**: Identifies the API within the service.\n- **Version**: Specifies the API version.\n\nWith OpenAPI, this is expressed using vendor extensions:\n\n```yaml\nopenapi: 3.1.2\ninfo:\n  title: Ping-Pong API\n  description: A simple API for ping-pong interactions to demonstrate OpenAPI coverage calculation\n  version: 1.0.0\n  x-api-name: ping-pong\n  x-service-name: example-application\n```\n\nThese annotations are the **linking key** between specifications and runtime telemetry.\n\n### Making Specifications Available\n\nSnow-White needs access to the API specifications.\nThis is typically done by publishing them to a central HTTP-based service interface repository, where Snow-White can\nfetch and synchronize them.\n\n👉 For details, see the [`api-sync-job` documentation](./microservices/api-sync-job) (handles synchronization and version\nmanagement).\n\n### Connecting Runtime Data\n\nNext, the running service must provide OpenTelemetry (OTEL) tracing data.\n\nAt the moment, only tracing is relevant (metrics and logs are not used yet).\nThe traces must be enhanced with the same annotation information used in the specifications:\n\n- Service Name: [`service.name` attribute](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service)\n- API Name: [`api.name` attribute](./semantic-convention/openapi.md)\n- API Version: [`api.version` attribute](./semantic-convention/openapi.md)\n\nThis enrichment ensures that Snow-White can correlate a runtime span to the correct API specification.\n\nTo simplify this, the project provides:\n\n- [**OpenAPI Generator Plugin**](./toolkit/openapi-generator) - Generates code that automatically attaches the right\n  annotations.\n- [**Spring Web Autoconfiguration**](./toolkit/spring-web-autoconfiguration) - Automatically enriches spans with API\n  metadata in Spring-based services.\n\n### Coverage Calculation\n\nOnce both inputs are in place (specifications + traces), you can trigger a coverage calculation.\nThis can be done via the [CLI](./toolkit/cli).\n\nThe CLI allows you to synchronize APIs, trigger coverage analysis, and validate results against quality gates directly\nfrom your local environment or CI pipeline.\n\nCoverage results are validated against Quality-Gate Configurations.\nThese configurations define the rules and thresholds that your API data must satisfy.\nSnow-White comes with predefined quality gates to get started quickly, and you can customize them later.\n\n## Development \u0026 Contributing\n\nWe welcome contributions!\nWhether you're fixing a bug, adding a feature, or improving the documentation - thank you 🙌\n\nTo get started:\n\n1. Read our [`DEVELOPMENT.md`](./DEVELOPMENT.md) for a step-by-step guide on setting up your local environment.\n2. Open a Pull Request or file an issue if you’ve found something worth improving.\n3. Make sure to follow the coding style and commit conventions described in [`DEVELOPMENT.md`](./DEVELOPMENT.md).\n\n### Local Setup (Quick Start)\n\n**Prerequisites:** Java 25, Node.js 22, Docker or Podman (with Compose).\n\n```shell\ngit clone https://github.com/bbortt/snow-white.git\ncd snow-white\n\n# Build all modules (including the CLI and generated sources)\n./mvnw -Pnode package\n\n# Start the development environment\ndocker compose -f dev/docker-compose.yaml up -d\n```\n\n\u003e A manual InfluxDB token setup step is required before traces can flow.\n\u003e See [`DEVELOPMENT.md`](./DEVELOPMENT.md) for the full walkthrough.\n\n### Contributing Guidelines\n\n- Keep commits small and focused.\n  Follow [Conventional Commits](https://www.conventionalcommits.org) (`feat:`, `fix:`, `chore:`, etc.).\n- All new features should include tests.\n- Run the full build before opening a PR: `./mvnw -Pnode verify`\n- Open an issue first for larger changes so we can align on direction before you invest time coding.\n\nPlease be respectful and constructive in all interactions.\n\n## License\n\nThis project is licensed under\nthe [Polyform Small Business License 1.0.0](https://polyformproject.org/licenses/small-business/1.0.0).\n\nThis means you can freely use, modify, and distribute the software **if your company generates less than $1 million USD\nin annual revenue** and meets other conditions in the license.\n\nIf your company exceeds this threshold or you intend to use Snow-White commercially, please reach out for licensing\noptions: [timon.borter@gmx.ch].\n\nSee the [LICENSE](./LICENSE) file for full details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbortt%2Fsnow-white","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbortt%2Fsnow-white","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbortt%2Fsnow-white/lists"}