refactor: make Tag::from_value private and improve docs

ddcommon/src/tag.rs

@@ -31,8 +31,12 @@ impl Tag {
     }
 }
 
+/// Creates a tag from a key and value known at compile-time, and fails to
+/// compile if it's known to be invalid (it may still emit an invalid tag, not
+/// all tag validation is currently done client-side). If the key or value
+/// aren't known at compile-time, then use [Tag::new].
 // todo: what's a good way to keep these in-sync with Tag::from_value?
-// This can be a little more strict because it's compile-time evaluated.
+// This can be a little more strict because it's compitle-time evaluated.
 // https://docs.datadoghq.com/getting_started/tagging/#define-tags
 #[macro_export]
 macro_rules! tag {
@@ -85,9 +89,8 @@ impl Display for Tag {
 }
 
 impl Tag {
-    /// It's recommended to use Tag::new when possible, as tags that are in
-    /// the <KEY>:<VALUE> format are preferred.
-    pub fn from_value<'a, IntoCow>(chunk: IntoCow) -> Result<Self, Cow<'static, str>>
+    /// Validates a tag.
+    fn from_value<'a, IntoCow>(chunk: IntoCow) -> Result<Self, Cow<'static, str>>
     where
         IntoCow: Into<Cow<'a, str>>,
     {
@@ -118,6 +121,8 @@ impl Tag {
         Ok(Tag { value })
     }
 
+    /// Creates a tag from a key and value. It's preferred to use the `tag!`
+    /// macro when the key and value are both known at compile-time.
     pub fn new<K, V>(key: K, value: V) -> Result<Self, Cow<'static, str>>
     where
         K: AsRef<str>,

ddtelemetry/examples/tm-metrics-worker-test.rs

@@ -3,7 +3,7 @@
 
 use std::{error::Error, time::Duration, time::Instant};
 
-use ddcommon::tag::Tag;
+use ddcommon::tag;
 use ddtelemetry::{data, worker};
 
 macro_rules! timeit {
@@ -64,7 +64,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     handle.add_point(1.0, &dist_metric, Vec::new()).unwrap();
     handle.add_point(2.0, &dist_metric, Vec::new()).unwrap();
 
-    let tags = vec![Tag::from_value("foo:bar").unwrap()];
+    let tags = vec![tag!("foo", "bar")];
     handle.add_point(2.0, &ping_metric, tags.clone()).unwrap();
     handle.add_point(1.8, &dist_metric, tags).unwrap();
 

ddtelemetry/examples/tm-worker-test.rs

@@ -6,7 +6,7 @@ use std::{
     time::{Duration, Instant},
 };
 
-use ddcommon::tag::Tag;
+use ddcommon::tag;
 use ddtelemetry::{data, worker};
 
 macro_rules! timeit {
@@ -67,7 +67,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     handle.add_point(1.0, &dist_metric, Vec::new()).unwrap();
     handle.add_point(2.0, &dist_metric, Vec::new()).unwrap();
 
-    let tags = vec![Tag::from_value("foo:bar").unwrap()];
+    let tags = vec![tag!("foo", "bar")];
     handle.add_point(2.0, &ping_metric, tags.clone()).unwrap();
     handle.add_point(1.8, &dist_metric, tags).unwrap();
 

ddtelemetry/src/metrics.rs

@@ -220,6 +220,7 @@ impl MetricContexts {
 
 #[cfg(test)]
 mod tests {
+    use ddcommon::tag;
     use std::fmt::Debug;
 
     use super::*;
@@ -279,7 +280,7 @@ mod tests {
             false,
             MetricNamespace::Tracers,
         );
-        let extra_tags = vec![Tag::from_value("service:foobar").unwrap()];
+        let extra_tags = vec![tag!("service", "foobar")];
 
         buckets.add_point(context_key_1, 0.1, Vec::new());
         buckets.add_point(context_key_1, 0.2, Vec::new());

profiling-ffi/src/exporter.rs

@@ -511,9 +511,7 @@ mod tests {
     // which Miri cannot evaluate.
     #[cfg_attr(miri, ignore)]
     fn profile_exporter_new_and_delete() {
-        let mut tags = ddcommon_ffi::Vec::default();
-        let host = tag!("host", "localhost");
-        tags.push(host);
+        let tags = vec![tag!("host", "localhost")].into();
 
         let result = unsafe {
             ddog_prof_Exporter_new(