https://github.com/bbortt/snow-white
An awesome pairing with, well.. do you know Snow White and the Jaeger?
https://github.com/bbortt/snow-white
Last synced: 8 days ago
JSON representation
An awesome pairing with, well.. do you know Snow White and the Jaeger?
- Host: GitHub
- URL: https://github.com/bbortt/snow-white
- Owner: bbortt
- License: other
- Created: 2022-11-24T22:48:27.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-06-24T18:46:24.000Z (10 days ago)
- Last Synced: 2026-06-24T19:14:07.037Z (10 days ago)
- Language: Java
- Homepage:
- Size: 6.83 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Snow-White 🍎
OpenAPI coverage and quality insights powered by OpenTelemetry.
Snow-White connects your OpenAPI specifications with runtime telemetry data to answer a simple question: **which parts
of your API are actually being tested?**
It correlates [OpenTelemetry (OTEL)](https://opentelemetry.io) traces emitted by your application with the endpoints
declared in your API specifications - then validates coverage against configurable quality gates.
Snow-White works with **black-box test suites** (system tests, integration tests) as well as **live production traffic
**.
It currently provides insights into:
- **Coverage** - which endpoints were exercised and which were not
- **API Performance** - response time analysis across operations
## Documentation
Full documentation is available at **[bbortt.github.io/snow-white](https://bbortt.github.io/snow-white)**.
| Section | Description |
| ---------------------------------------------------------------- | ----------------------------------------------------------- |
| [Deployment](https://bbortt.github.io/snow-white/deployment) | Install Snow-White with Helm and configure your environment |
| [Onboarding](https://bbortt.github.io/snow-white/onboarding) | Step-by-step guide to integrating your service |
| [Architecture](https://bbortt.github.io/snow-white/architecture) | Component overview and event-driven design |
| [Workflows](https://bbortt.github.io/snow-white/workflows) | CI/CD pipeline patterns and quality gate workflows |
| [CLI Reference](https://bbortt.github.io/snow-white/cli) | Full CLI command reference |
| [Requirements](https://bbortt.github.io/snow-white/requirements) | System and dependency requirements |
| [License](https://bbortt.github.io/snow-white/license) | Licensing details and commercial use |
## Installation (for providers)
Snow-White can be installed easily using Helm.
Detailed instructions and available options are described
in ["Deployment"](https://bbortt.github.io/snow-white/deployment).
Individual images could also be used for a custom installation.
The Docker compose file `dev/docker-compose.yaml` may be used as a starting point.
## Onboarding (for users)
See ["Onboarding"](https://bbortt.github.io/snow-white/onboarding) for a step-by-step guide to integrating your service
with Snow-White.
## General Concept
Here's a high-level overview of Snow-White.
For a detailed component and data-flow breakdown, see
the [Architecture](https://bbortt.github.io/snow-white/architecture) docs.
1. **Synchronize API Specs** - Snow-White imports OpenAPI specifications from your central interface repository.
2. **Ingest Telemetry** - It listens to OpenTelemetry tracing data emitted by your applications.
3. **Correlate & Analyze** - Traces are matched with API operations using service, API name, and version metadata.
4. **Evaluate Quality Gates** - Results are validated against your configured thresholds.
5. **Visualize or Export Results** - Coverage and performance insights can be viewed in reports or integrated into CI
pipelines.
### Annotating APIs
The core idea behind Snow-White is that it can only interpret runtime telemetry (e.g. traces) if it knows which API the
data belongs to.
This is achieved by a common annotation model applied both to the specifications and to the telemetry data.
Every API must declare a few key identifiers:
- **Service Name**: Identifies the logical unit or application that exposes the API.
- _Required_, because different applications may have identically named endpoints (e.g. `/health`).
- **API Name**: Identifies the API within the service.
- **Version**: Specifies the API version.
With OpenAPI, this is expressed using vendor extensions:
```yaml
openapi: 3.1.2
info:
title: Ping-Pong API
description: A simple API for ping-pong interactions to demonstrate OpenAPI coverage calculation
version: 1.0.0
x-api-name: ping-pong
x-service-name: example-application
```
These annotations are the **linking key** between specifications and runtime telemetry.
### Making Specifications Available
Snow-White needs access to the API specifications.
This is typically done by publishing them to a central HTTP-based service interface repository, where Snow-White can
fetch and synchronize them.
👉 For details, see the [`api-sync-job` documentation](./microservices/api-sync-job) (handles synchronization and version
management).
### Connecting Runtime Data
Next, the running service must provide OpenTelemetry (OTEL) tracing data.
At the moment, only tracing is relevant (metrics and logs are not used yet).
The traces must be enhanced with the same annotation information used in the specifications:
- Service Name: [`service.name` attribute](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service)
- API Name: [`api.name` attribute](./semantic-convention/openapi.md)
- API Version: [`api.version` attribute](./semantic-convention/openapi.md)
This enrichment ensures that Snow-White can correlate a runtime span to the correct API specification.
To simplify this, the project provides:
- [**OpenAPI Generator Plugin**](./toolkit/openapi-generator) - Generates code that automatically attaches the right
annotations.
- [**Spring Web Autoconfiguration**](./toolkit/spring-web-autoconfiguration) - Automatically enriches spans with API
metadata in Spring-based services.
### Coverage Calculation
Once both inputs are in place (specifications + traces), you can trigger a coverage calculation.
This can be done via the [CLI](./toolkit/cli).
The CLI allows you to synchronize APIs, trigger coverage analysis, and validate results against quality gates directly
from your local environment or CI pipeline.
Coverage results are validated against Quality-Gate Configurations.
These configurations define the rules and thresholds that your API data must satisfy.
Snow-White comes with predefined quality gates to get started quickly, and you can customize them later.
## Development & Contributing
We welcome contributions!
Whether you're fixing a bug, adding a feature, or improving the documentation - thank you 🙌
To get started:
1. Read our [`DEVELOPMENT.md`](./DEVELOPMENT.md) for a step-by-step guide on setting up your local environment.
2. Open a Pull Request or file an issue if you’ve found something worth improving.
3. Make sure to follow the coding style and commit conventions described in [`DEVELOPMENT.md`](./DEVELOPMENT.md).
### Local Setup (Quick Start)
**Prerequisites:** Java 25, Node.js 22, Docker or Podman (with Compose).
```shell
git clone https://github.com/bbortt/snow-white.git
cd snow-white
# Build all modules (including the CLI and generated sources)
./mvnw -Pnode package
# Start the development environment
docker compose -f dev/docker-compose.yaml up -d
```
> A manual InfluxDB token setup step is required before traces can flow.
> See [`DEVELOPMENT.md`](./DEVELOPMENT.md) for the full walkthrough.
### Contributing Guidelines
- Keep commits small and focused.
Follow [Conventional Commits](https://www.conventionalcommits.org) (`feat:`, `fix:`, `chore:`, etc.).
- All new features should include tests.
- Run the full build before opening a PR: `./mvnw -Pnode verify`
- Open an issue first for larger changes so we can align on direction before you invest time coding.
Please be respectful and constructive in all interactions.
## License
This project is licensed under
the [Polyform Small Business License 1.0.0](https://polyformproject.org/licenses/small-business/1.0.0).
This means you can freely use, modify, and distribute the software **if your company generates less than $1 million USD
in annual revenue** and meets other conditions in the license.
If your company exceeds this threshold or you intend to use Snow-White commercially, please reach out for licensing
options: [timon.borter@gmx.ch].
See the [LICENSE](./LICENSE) file for full details.