# Changelog

All notable changes to Clarvynn will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0] - 2024-12-04

Initial public release of Clarvynn - the control plane for OpenTelemetry that enforces Purposeful Observability through Deferred Head Sampling.

### Added
- Comprehensive test suite (296 tests, 100% pass rate)
  - Unit tests for CPL engine, policy cache, production adapter
  - Integration tests for span processor, log processor, TraceState exporter
  - Thread-safety and performance benchmarks
  - Test documentation in `tests/README.md`
- OpenTelemetry SDK compatibility testing script (`scripts/test_otel_compatibility.py`)


### Changed
- Simplified CPL schema: removed unused `rate` field from conditions
  - Matched conditions are now always sampled at 100% (the core value proposition)
  - `base_rate` still controls probabilistic sampling for unmatched traffic
- Cleaned up ProductionCPLAdapter to focus on file-only mode (current implementation)
  - Removed unused gRPC parameters and background sync code
  - Future dynamic updates will be implemented via file watching
- **Breaking**: Updated log processor to support OTel SDK 1.39+ API changes
  - `LogData` class removed in 1.39, now uses `ReadWriteLogRecord` directly
  - Backward compatible with 1.20-1.38 via version detection

### Fixed
- Improved hash distribution for timestamp-based log sampling using golden ratio constant
- Fixed documentation inconsistencies (package name, API examples, policy format)
- Fixed CLI import paths (`adapters.base` → `core.cpl_engine.python.base`)
- Removed obsolete pytest filterwarnings for `LogDeprecatedInitWarning` (removed in 1.39)

### Compatibility
- **OpenTelemetry SDK**: Tested and verified with versions 1.25.0 - 1.39.0
  - Narrowed from 1.20.0 to reduce maintenance burden
  - Users on older SDK versions should upgrade (1.25.0 released March 2024)
- **Python**: Supports 3.9, 3.10, 3.11, 3.12 (Python 3.8 EOL October 2024)

### Planned
- File watching for automatic policy reload (hot-reload)
- Java adapter support
- Node.js adapter support
- Go adapter support
- Rust-based CPL engine with WebAssembly
- Web UI for policy management

---

## [0.1.0] - Unreleased

### Initial Release

**Status:** Alpha - Ready for testing and early adoption

This is the first public release of Clarvynn! While we consider this production-quality code, the API may evolve based on user feedback before v1.0.0.

### Added

#### Core Features
- **Tail-based sampling** for OpenTelemetry Python applications
  - Sampling decisions made AFTER span completion (sees errors, latency, all attributes)
  - Dramatically more accurate than head-based sampling
  
- **CPL (Conditions-based Policy Language)**
  - Human-readable YAML-based policy definition
  - 10 condition patterns supported:
    - Error detection (`status_code >= 500`)
    - Latency thresholds (`duration_ms > 1000`)
    - HTTP method filtering (`method == "POST"`)
    - Path-based rules (`path contains "/api"`)
    - Logical operators (`AND`, `OR`, `NOT`)
    - Comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`, `contains`, `not contains`)
    - Parentheses for precedence (`(A OR B) AND C`)
  - Full expression parser using `pyparsing`
  
- **W3C TraceContext Level 2 support**
  - Consistent distributed sampling using `tracestate`
  - Critical traces marked with `ot=th:0` for 100% downstream capture
  - Complete end-to-end traces for errors/slow requests across microservices
  
- **Log-trace correlation**
  - Logs sampled consistently with their associated traces
  - No orphaned logs or traces
  - Trace decision cache for cross-signal consistency

#### OpenTelemetry Integration
- **Zero-code-change integration** via `opentelemetry-instrument`
- Drop-in replacement for standard OpenTelemetry configuration
- Works with existing auto-instrumentation libraries:
  - Flask (`opentelemetry-instrumentation-flask`)
  - Django (`opentelemetry-instrumentation-django`)
  - FastAPI (`opentelemetry-instrumentation-fastapi`)

#### CLI Tools
- `clarvynn init` - Generate starter policy configuration
- `clarvynn validate` - Validate policy syntax and structure
- Environment variable configuration:
  - `CLARVYNN_ENABLED` - Enable/disable Clarvynn
  - `CLARVYNN_POLICY_PATH` - Path to policy YAML file
  - `CLARVYNN_LOG_LEVEL` - Set log verbosity (debug, info, warning, error, silent)

#### Developer Experience
- Comprehensive examples for Flask, Django, FastAPI
- Policy templates for common use cases
- Detailed documentation:
  - Getting Started Guide
  - Configuration Reference
  - Framework Integration Guide
  - Architecture Deep Dive
  - CPL Language Reference
  - W3C TraceContext Level 2 Explanation

### Performance
- Sub-millisecond policy evaluation (< 50µs typical)
- Minimal memory overhead (< 10MB)
- Zero impact when disabled
- Efficient policy caching

### Compatibility
- **OpenTelemetry SDK**: 1.20.0 - 1.38.0 (tested)
- **Python**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13

### Documentation
- Complete API documentation
- 5-minute quick start guide
- Real-world examples
- Troubleshooting guide
- Adapter development guide (for future language support)

### Known Limitations
- **Python only** - Java/Node.js/Go support planned for v2.0.0
- **CLI only** - No web UI yet (planned for future release)
- **Limited operators** - More CPL operators will be added based on user feedback
- **OTLP export only** - Other exporters (Jaeger, Zipkin) planned for future releases

### Breaking Changes
- None (initial release)

### Migration Guide
- None (initial release)

---

## Version History

- **v0.1.0** (Jan 2025) - Initial alpha release
- **v1.0.0** (Planned Q2 2025) - Production-ready, stable API
- **v2.0.0** (Planned Q3 2025) - Multi-language support with Rust/Wasm

---

## How to Upgrade

### From source installation to v0.1.0
```bash
pip install clarvynn==0.1.0
```

### Future upgrades
```bash
# Check current version
pip show clarvynn

# Upgrade to latest
pip install --upgrade clarvynn

# Upgrade to specific version
pip install clarvynn==0.2.0
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.

---

## Support

- **GitHub Issues**: https://github.com/clarvynn/clarvynn/issues
- **Discussions**: https://github.com/clarvynn/clarvynn/discussions
- **Documentation**: https://github.com/clarvynn/clarvynn/tree/main/docs

---

[Unreleased]: https://github.com/clarvynn/clarvynn/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/clarvynn/clarvynn/releases/tag/v0.1.0

