From f05a0f24160750cb45155796297f39750d8a3ac5 Mon Sep 17 00:00:00 2001
From: Julian Tescher <jatescher@gmail.com>
Date: Sat, 30 Jan 2021 13:43:54 -0800
Subject: [PATCH] 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
---
 tracing-opentelemetry/src/layer.rs | 5 +++--
 tracing-opentelemetry/src/lib.rs   | 9 +++------
 2 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/tracing-opentelemetry/src/layer.rs b/tracing-opentelemetry/src/layer.rs
index 799245277e..c88cb2f97e 100644
--- a/tracing-opentelemetry/src/layer.rs
+++ b/tracing-opentelemetry/src/layer.rs
@@ -586,6 +586,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::*;
@@ -657,7 +658,7 @@ mod tests {
         let subscriber = tracing_subscriber::registry().with(layer().with_tracer(tracer.clone()));
 
         tracing::collect::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();
@@ -679,7 +680,7 @@ mod tests {
         let _g = existing_cx.attach();
 
         tracing::collect::with_default(subscriber, || {
-            tracing::debug_span!("request", otel.kind = "Server");
+            tracing::debug_span!("request", otel.kind = %SpanKind::Server);
         });
 
         let recorded_trace_id = tracer
diff --git a/tracing-opentelemetry/src/lib.rs b/tracing-opentelemetry/src/lib.rs
index 4cff524fbc..262f1d4cae 100644
--- a/tracing-opentelemetry/src/lib.rs
+++ b/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.