Update README.md

README.md

@@ -126,3 +126,29 @@ Tests can be run by typing `make test`.
 
 If you make any changes to the code, run `make format` in order to automatically
 format the code according to Go [standards](https://golang.org/doc/effective_go.html#formatting).
+
+
+ ## Metrics Emission and Compatibility
+
+ This library can emit metrics using either `github.com/armon/go-metrics` or `github.com/hashicorp/go-metrics`. Choosing between the libraries is controlled via build tags. 
+
+ **Build Tags**
+ * `armonmetrics` - Using this tag will cause metrics to be routed to `armon/go-metrics`
+ * `hashicorpmetrics` - Using this tag will cause all metrics to be routed to `hashicorp/go-metrics`
+
+ If no build tag is specified, the default behavior is to use `armon/go-metrics`. 
+
+ **Deprecating `armon/go-metrics`**
+
+ Emitting metrics to `armon/go-metrics` is officially deprecated. Usage of `armon/go-metrics` will remain the default until mid-2025 with opt-in support continuing to the end of 2025.
+
+ **Migration**
+ To migrate an application currently using the older `armon/go-metrics` to instead use `hashicorp/go-metrics` the following should be done.
+
+ 1. Upgrade libraries using `armon/go-metrics` to consume `hashicorp/go-metrics/compat` instead. This should involve only changing import statements. All repositories in the `hashicorp` namespace
+ 2. Update an applications library dependencies to those that have the compatibility layer configured.
+ 3. Update the application to use `hashicorp/go-metrics` for configuring metrics export instead of `armon/go-metrics`
+    * Replace all application imports of `github.com/armon/go-metrics` with `github.com/hashicorp/go-metrics`
+    * Instrument your build system to build with the `hashicorpmetrics` tag.
+
+ Eventually once the default behavior changes to use `hashicorp/go-metrics` by default (mid-2025), you can drop the `hashicorpmetrics` build tag.