rel: Prep for v0.4.0 release (#60)

Release prep including an update to README.

CHANGELOG.md

@@ -1,5 +1,33 @@
 # dynsampler-go changelog
 
+## 0.4.0 2023-03-22
+
+This version contains two new samplers and some (backwards-compatible) changes to the API:
+- Many thanks to [Yi Zhao](https://github.com/yizzlez) for the contribution of the `WindowedThroughput` sampler. This sampler is like the Throughput sampler, but uses a moving average to accumulate sample rates across multiple sampling periods.
+- The new `EMAThroughput` sampler adjusts overall throughput to achieve a goal while also ensuring that all values in the key space are represented.
+- The `GetSampleRateMulti()` function allows a single request to represent multiple events. This is particularly useful when tail-sampling at the trace level (because each trace represents a number of spans).
+- All samplers now support specifying a `time.Duration` instead of a time in seconds. Fields like `ClearFrequencySec` are now deprecated and will be dropped in a future release.
+
+⚠️ As of this version, dynsampler-go requires and is tested on versions of Go 1.17 and greater.
+
+### Features
+
+- feat: EMAThroughput sampler (#58) | [Kent Quirk](https://github.com/kentquirk)
+- feat: Deprecate integer seconds and replace with time.Duration (#59) | [Kent Quirk](https://github.com/kentquirk)
+- feat: add GetSampleRateMulti (#53) | [Kent Quirk](https://github.com/kentquirk)
+- feat: Windowed Throughput Sampling (#45) | [Yi Zhao](https://github.com/yizzlez)
+  - fix: Fix flaky blocklist test (#52) | [Yi Zhao](https://github.com/yizzlez)
+
+### Maintenance
+
+- maint: Pull out common calculation into a function (#57) | [Kent Quirk](https://github.com/kentquirk)
+- maint: bump the go versions we support (#55) | [Kent Quirk](https://github.com/kentquirk)
+- maint(deps): bump github.com/stretchr/testify from 1.6.1 to 1.8.2 (#49) | [dependabot[bot]](https://github.com/dependabot[bot])
+- maint: remove buildevents from circle (#48) | [Jamie Danielson](https://github.com/JamieDanielson)
+- chore: Update workflow (#47) | [Tyler Helmuth](https://github.com/TylerHelmuth)
+- chore: Update CODEOWNERS (#46) | [Tyler Helmuth](https://github.com/TylerHelmuth)
+- chore: update dependabot.yml (#44) | [Kent Quirk](https://github.com/kentquirk)
+
 ## 0.3.0 2022-12-07
 
 ⚠️ As of this version, dynsampler-go is only tested on Go 1.16 or greater.

README.md

@@ -7,7 +7,7 @@ It contains several sampling algorithms to help you select a representative set
 
 A "sample rate" of 100 means that for every 100 requests, we capture a single event and indicate that it represents 100 similar requests.
 
-For full documentation, look at the [dynsampler godoc](https://godoc.org/github.com/honeycombio/dynsampler-go).
+For full documentation, look at the [official documentation](https://pkg.go.dev/github.com/honeycombio/dynsampler-go).
 
 For more information about using Honeycomb, see our [docs](https://honeycomb.io/docs).
 
@@ -21,6 +21,8 @@ Depending on the shape of your traffic, one may serve better than another, or yo
 * If your system has a completely homogeneous stream of requests: use `Static` sampling to use a constant sample rate.
 * If your system has a steady stream of requests and a well-known low cardinality partition key (e.g. http status): use `Static` sampling and override sample rates on a per-key basis (e.g. if you know want to sample `HTTP 200/OK` events at a different rate from `HTTP 503/Server Error`).
 * If your logging system has a strict cap on the rate it can receive events, use `TotalThroughput`, which will calculate sample rates based on keeping *the entire system's* representative event throughput right around (or under) particular cap.
+* If you need a throughput sampler that is responsive to spikes, but also averages sample rates over a longer period of time, use `WindowedThroughput`.
 * If your system has a rough cap on the rate it can receive events and your partitioned keyspace is fairly steady, use `PerKeyThroughput`, which will calculate sample rates based on keeping the event throughput roughly constant *per key/partition* (e.g. per user id)
 * The best choice for a system with a large key space and a large disparity between the highest volume and lowest volume keys is `AvgSampleRateWithMin` - it will increase the sample rate of higher volume traffic proportionally to the logarithm of the specific key's volume. If total traffic falls below a configured minimum, it stops sampling to avoid any sampling when the traffic is too low to warrant it.
 * `EMASampleRate` works like `AvgSampleRate`, but calculates sample rates based on a moving average (Exponential Moving Average) of many measurement intervals rather than a single isolated interval. In addition, it can detect large bursts in traffic and will trigger a recalculation of sample rates before the regular interval.
+* If you want the benefit of a key-based sampler that also has limits on throughput, use `EMAThroughput`. It will adjust sample rates across a key space to achieve a given throughput while still ensuring that all keys are represented.