Initial attempt at adding metric semconvs. (#1918)

Co-authored-by: Lalit Kumar Bhasin <labhas@microsoft.com>

opentelemetry-semantic-conventions/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## vNext
 
+### Changed
+
+- **Breaking** Moved duplicated (and unrelated) attributes from `opentelemetry_semantic_conventions::trace` and `opentelemetry_semantic_conventions::resource` into `opentelemetry_semantic_conventions::attribute` (which now contains all semantic attributes). `trace` and `resource` now only contain references to attributes which fall under their respective category.
+
+### Added
+
+- Created `opentelemetry_semantic_conventions::metric` to store metric semantic conventions.
+
 ## v0.15.0
 
 ### Changed

opentelemetry-semantic-conventions/scripts/generate-consts-from-spec.sh

@@ -25,7 +25,17 @@ docker run --rm \
 	-v "${CRATE_DIR}/scripts/templates:/templates" \
 	-v "${CRATE_DIR}/src:/output" \
 	otel/semconvgen:$SEMCOVGEN_VERSION \
-  --only span,event,attribute_group,scope \
+  -f /source code \
+	--template /templates/semantic_attributes.rs.j2 \
+	--output /output/attribute.rs \
+	--parameters conventions=attribute
+
+docker run --rm \
+	-v "${CRATE_DIR}/semantic-conventions/model:/source" \
+	-v "${CRATE_DIR}/scripts/templates:/templates" \
+	-v "${CRATE_DIR}/src:/output" \
+	otel/semconvgen:$SEMCOVGEN_VERSION \
+  --only span,event,scope \
   -f /source code \
 	--template /templates/semantic_attributes.rs.j2 \
 	--output /output/trace.rs \
@@ -36,12 +46,21 @@ docker run --rm \
 	-v "${CRATE_DIR}/scripts/templates:/templates" \
 	-v "${CRATE_DIR}/src:/output" \
 	otel/semconvgen:$SEMCOVGEN_VERSION \
-  --only resource,attribute_group \
+  --only resource \
   -f /source code \
 	--template /templates/semantic_attributes.rs.j2 \
 	--output /output/resource.rs \
 	--parameters conventions=resource
 
+docker run --rm \
+	-v "${CRATE_DIR}/semantic-conventions/model:/source" \
+	-v "${CRATE_DIR}/scripts/templates:/templates" \
+	-v "${CRATE_DIR}/src:/output" \
+	otel/semconvgen:$SEMCOVGEN_VERSION \
+  -f /source code \
+	--template /templates/semantic_metrics.rs.j2 \
+	--output /output/metric.rs
+
 SED=(sed -i)
 if [[ "$(uname)" = "Darwin" ]]; then
   SED=(sed -i "")
@@ -51,16 +70,15 @@ fi
 "${SED[@]}" "s/\(opentelemetry.io\/schemas\/\)[^\"]*\"/\1$SPEC_VERSION\"/" src/lib.rs
 
 # handle doc generation failures
-"${SED[@]}" 's/\[2\]\.$//' src/resource.rs src/trace.rs # remove trailing [2] from few of the doc comments
+"${SED[@]}" 's/\[2\]\.$//' src/attribute.rs # remove trailing [2] from few of the doc comments
 
-# Remove the messaging.client_id definition along with its comments from the generated files
-#   - semconv "messaging.client_id" is deprecated
-#   - semconv "messaging.client.id" is to be used instead
-#   - Now because we use:
-#      	pub const {{attribute.fqn | to_const_name}}: &str = "{{attribute.fqn}}";
-#     to generate the consts, where to_const_name replaces '.' with '_', we need to remove the old definition
-#	  to avoid conflicts with the new one. Refer - https://github.com/open-telemetry/semantic-conventions/issues/1031
-"${SED[@]}" '/\/\/\/ Deprecated, use `messaging.client.id` instead\./{N;N;N;N;d;}' src/trace.rs src/resource.rs
-"${SED[@]}" '/pub const MESSAGING_CLIENT_ID: &str = "messaging.client_id";/{N;d;}' src/trace.rs src/resource.rs
+# handle escaping ranges like [0,n] / [0.0, ...] in descriptions/notes which will cause broken intra-doc links
+# unescape any mistakenly escaped ranges which actually contained a link (not that we currently have any)
+expression='
+  s/\[([a-zA-Z0-9\.\s]+,[a-zA-Z0-9\.\s]+)\]/\\[\1\\]/g
+  s/\\\[([^\]]+)\]\(([^)]+)\)/[\1](\2)/g
+'
+"${SED[@]}" -E "${expression}" src/metric.rs
+"${SED[@]}" -E "${expression}" src/attribute.rs
 
 cargo fmt

opentelemetry-semantic-conventions/scripts/templates/header_attribute.rs

@@ -0,0 +1,3 @@
+//! # Semantic Attributes
+//!
+//! The entire set of semantic attributes (or [conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)) defined by the project. The resource, metric, and trace modules reference these attributes.

opentelemetry-semantic-conventions/scripts/templates/header_metric.rs

@@ -0,0 +1,23 @@
+//! # Metric Semantic Conventions
+//!
+//! The [metric semantic conventions] define a set of standardized attributes to
+//! be used in `Meter`s.
+//!
+//! [metric semantic conventions]: https://github.com/open-telemetry/semantic-conventions/tree/main/model/metric
+//!
+//! ## Usage
+//!
+//! ```rust
+//! use opentelemetry::{global, KeyValue};
+//! use opentelemetry_semantic_conventions as semconv;
+//!
+//! // Assumes we already have an initialized `MeterProvider`
+//! // See: https://github.com/open-telemetry/opentelemetry-rust/blob/main/examples/metrics-basic/src/main.rs
+//! // for an example
+//! let meter = global::meter("mylibraryname");
+//! let histogram = meter
+//!     .u64_histogram(semconv::metric::HTTP_SERVER_REQUEST_DURATION)
+//!     .with_unit("By")
+//!     .with_description("Duration of HTTP server requests.")
+//!     .init();
+//! ```

opentelemetry-semantic-conventions/scripts/templates/header_resource.rs

@@ -7,7 +7,7 @@
 //!
 //! ## Usage
 //!
-//! ```
+//! ```rust
 //! use opentelemetry::KeyValue;
 //! use opentelemetry_sdk::{trace::{config, TracerProvider}, Resource};
 //! use opentelemetry_semantic_conventions as semconv;

opentelemetry-semantic-conventions/scripts/templates/header_trace.rs

@@ -7,7 +7,7 @@
 //!
 //! ## Usage
 //!
-//! ```
+//! ```rust
 //! use opentelemetry::KeyValue;
 //! use opentelemetry::{global, trace::Tracer as _};
 //! use opentelemetry_semantic_conventions as semconv;
@@ -16,8 +16,8 @@
 //! let _span = tracer
 //!     .span_builder("span-name")
 //!     .with_attributes(vec![
-//!         KeyValue::new(semconv::trace::NET_PEER_NAME, "example.org"),
-//!         KeyValue::new(semconv::trace::NET_PEER_PORT, 80i64),
+//!         KeyValue::new(semconv::trace::CLIENT_ADDRESS, "example.org"),
+//!         KeyValue::new(semconv::trace::CLIENT_PORT, 80i64),
 //!     ])
 //!     .start(&tracer);
 //! ```

opentelemetry-semantic-conventions/scripts/templates/semantic_attributes.rs.j2

@@ -6,8 +6,16 @@
 
 {% include 'header_' + conventions + '.rs' %}
 
-{%- for attribute in attributes if attribute.is_local and not attribute.ref %}
+{%- for attribute in attributes %}
+{%- set x=attribute.__setattr__("fqn_const_name", (attribute.fqn | to_const_name)) %}
+{%- endfor %}
 
+{%- for name, attrs in (attributes | groupby('fqn_const_name')) %}
+{%- set attribute = (attrs | selectattr('deprecated', 'none') | first) %}
+{%- set attribute = attribute if attribute else (attrs | first) %}
+{%- if conventions != 'attribute' %}
+pub use crate::attribute::{{ attribute.fqn_const_name }};
+{%- else %}
 /// {% filter escape %}{{attribute.brief | to_doc_brief}}.{% endfilter %}
 {%- if attribute.note %}
 ///
@@ -23,8 +31,9 @@
 /// - `{{example}}`
 {%- endfor %}
 {%- endif %}
-{%- if (attribute.stability | string()) == "StabilityLevel.DEPRECATED"  %}
+{%- if (attribute.deprecated) %}
 #[deprecated]
 {%- endif %}
-pub const {{attribute.fqn | to_const_name}}: &str = "{{attribute.fqn}}";
+pub const {{ attribute.fqn_const_name }}: &str = "{{attribute.fqn}}";
+{%- endif %}
 {%- endfor %}

opentelemetry-semantic-conventions/scripts/templates/semantic_metrics.rs.j2

@@ -0,0 +1,57 @@
+// DO NOT EDIT, this is an auto-generated file
+//
+// If you want to update the file:
+// - Edit the template at scripts{{template}}
+// - Run the script at scripts/generate-consts-from-spec.sh
+
+{% include 'header_metric.rs' %}
+
+{%- for metric in metrics %}
+/// ## Description
+/// {% filter escape %}{{ metric.brief | to_doc_brief }}.{% endfilter %}
+{%- if metric.note %}
+/// 
+{%- for line in metric.note.split('\n') %}
+/// {% filter escape %}{{ line }}{% endfilter %}
+{%- endfor %}
+{%- endif %}
+/// ## Metadata
+/// | | |
+/// |:-|:-
+/// | Instrument: | `{{ metric.instrument }}` |
+/// | Unit: | `{{ metric.unit }}` |
+/// | Status: | `{{ ((metric.stability | string()).split('.')[1].replace('_', ' ')) | capitalize }}`  |
+{%- if metric.attributes %}
+///
+/// ## Attributes
+/// | Name | Requirement |
+/// |:-|:- |
+{%- endif %}
+{%- for attribute in metric.attributes %}
+{%- if attribute.ref %}
+{%- set ref = (attributes | selectattr('fqn', 'equalto', attribute.ref) | first) %}
+{%- if ref %}
+{%- if attribute.requirement_level %}
+{%- set req_level = ((attribute.requirement_level | string()).split('.')[1].replace('_', ' ')) | capitalize %}
+{%- set req_message = attribute.requirement_level_msg %}
+{%- else %}
+{%- set req_level = "Unspecified" %}
+{%- set req_message = '' %}
+{%- endif %}
+/// | [`crate::attribute::{{ ref.fqn | to_const_name }}`] | `{{ req_level }}`{{ (': ' + req_message if req_message else '') }}
+{%- endif %}
+{%- endif %}
+{%- endfor %}
+{%- if metric.examples %}
+///
+/// # Examples
+///
+{%- for example in metric.examples %}
+/// - `{{ example }}`
+{%- endfor %}
+{%- endif %}
+{%- if (metric.deprecated) %}
+#[deprecated]
+{%- endif %}
+pub const {{ metric.metric_name | to_const_name }}: &str = "{{ metric.metric_name }}";
+{%- endfor %}