opentelemetry: clarify otel.kind field usage in docs (#1218)

This patch resolves the field value capitalization ambiguity currently
in `otel.kind` by instead recommending an enum value. This also brings
type safety to the value, further reducing the risk of typos and other
misuse.

Resolves #1209

Author: jtescher

tracing-opentelemetry/src/layer.rs

@@ -585,6 +585,7 @@ impl Timings {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use opentelemetry::trace::SpanKind;
     use std::sync::{Arc, Mutex};
     use std::time::SystemTime;
     use tracing_subscriber::prelude::*;
@@ -656,7 +657,7 @@ mod tests {
         let subscriber = tracing_subscriber::registry().with(layer().with_tracer(tracer.clone()));
 
         tracing::subscriber::with_default(subscriber, || {
-            tracing::debug_span!("request", otel.kind = "Server");
+            tracing::debug_span!("request", otel.kind = %SpanKind::Server);
         });
 
         let recorded_kind = tracer.0.lock().unwrap().as_ref().unwrap().span_kind.clone();
@@ -678,7 +679,7 @@ mod tests {
         let _g = existing_cx.attach();
 
         tracing::subscriber::with_default(subscriber, || {
-            tracing::debug_span!("request", otel.kind = "Server");
+            tracing::debug_span!("request", otel.kind = %SpanKind::Server);
         });
 
         let recorded_trace_id = tracer

tracing-opentelemetry/src/lib.rs

@@ -22,18 +22,15 @@
 //! * `otel.name`: Override the span name sent to OpenTelemetry exporters.
 //! Setting this field is useful if you want to display non-static information
 //! in your span name.
-//! * `otel.kind`: Set the span kind to one of the supported OpenTelemetry
-//! [span kinds]. The value should be a string of any of the supported values:
-//! `SERVER`, `CLIENT`, `PRODUCER`, `CONSUMER` or `INTERNAL`. Other values are
-//! silently ignored.
+//! * `otel.kind`: Set the span kind to one of the supported OpenTelemetry [span kinds].
 //!
-//! [span kinds]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#spankind
+//! [span kinds]: https://docs.rs/opentelemetry/latest/opentelemetry/trace/enum.SpanKind.html
 //!
 //! ### Semantic Conventions
 //!
 //! OpenTelemetry defines conventional names for attributes of common
 //! operations. These names can be assigned directly as fields, e.g.
-//! `trace_span!("request", "otel.kind" = "client", "http.url" = ..)`, and they
+//! `trace_span!("request", "otel.kind" = %SpanKind::Client, "http.url" = ..)`, and they
 //! will be passed through to your configured OpenTelemetry exporter. You can
 //! find the full list of the operations and their expected field names in the
 //! [semantic conventions] spec.