Skip to content

Commit 597327f

Browse files
tbrockmanlalitb
tbrockman
and
lalitb
authored
Initial attempt at adding metric semconvs. (#1918)
Co-authored-by: Lalit Kumar Bhasin <labhas@microsoft.com>
1 parent 621a5a9 commit 597327f

13 files changed

+5732
-7399
lines changed

‎opentelemetry-semantic-conventions/CHANGELOG.md

+8
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
## vNext
44

5+
### Changed
6+
7+
- **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.
8+
9+
### Added
10+
11+
- Created `opentelemetry_semantic_conventions::metric` to store metric semantic conventions.
12+
513
## v0.15.0
614

715
### Changed

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

+30-12
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,17 @@ docker run --rm \
2525
-v "${CRATE_DIR}/scripts/templates:/templates" \
2626
-v "${CRATE_DIR}/src:/output" \
2727
otel/semconvgen:$SEMCOVGEN_VERSION \
28-
--only span,event,attribute_group,scope \
28+
-f /source code \
29+
--template /templates/semantic_attributes.rs.j2 \
30+
--output /output/attribute.rs \
31+
--parameters conventions=attribute
32+
33+
docker run --rm \
34+
-v "${CRATE_DIR}/semantic-conventions/model:/source" \
35+
-v "${CRATE_DIR}/scripts/templates:/templates" \
36+
-v "${CRATE_DIR}/src:/output" \
37+
otel/semconvgen:$SEMCOVGEN_VERSION \
38+
--only span,event,scope \
2939
-f /source code \
3040
--template /templates/semantic_attributes.rs.j2 \
3141
--output /output/trace.rs \
@@ -36,12 +46,21 @@ docker run --rm \
3646
-v "${CRATE_DIR}/scripts/templates:/templates" \
3747
-v "${CRATE_DIR}/src:/output" \
3848
otel/semconvgen:$SEMCOVGEN_VERSION \
39-
--only resource,attribute_group \
49+
--only resource \
4050
-f /source code \
4151
--template /templates/semantic_attributes.rs.j2 \
4252
--output /output/resource.rs \
4353
--parameters conventions=resource
4454

55+
docker run --rm \
56+
-v "${CRATE_DIR}/semantic-conventions/model:/source" \
57+
-v "${CRATE_DIR}/scripts/templates:/templates" \
58+
-v "${CRATE_DIR}/src:/output" \
59+
otel/semconvgen:$SEMCOVGEN_VERSION \
60+
-f /source code \
61+
--template /templates/semantic_metrics.rs.j2 \
62+
--output /output/metric.rs
63+
4564
SED=(sed -i)
4665
if [[ "$(uname)" = "Darwin" ]]; then
4766
SED=(sed -i "")
@@ -51,16 +70,15 @@ fi
5170
"${SED[@]}" "s/\(opentelemetry.io\/schemas\/\)[^\"]*\"/\1$SPEC_VERSION\"/" src/lib.rs
5271

5372
# handle doc generation failures
54-
"${SED[@]}" 's/\[2\]\.$//' src/resource.rs src/trace.rs # remove trailing [2] from few of the doc comments
73+
"${SED[@]}" 's/\[2\]\.$//' src/attribute.rs # remove trailing [2] from few of the doc comments
5574

56-
# Remove the messaging.client_id definition along with its comments from the generated files
57-
# - semconv "messaging.client_id" is deprecated
58-
# - semconv "messaging.client.id" is to be used instead
59-
# - Now because we use:
60-
# pub const {{attribute.fqn | to_const_name}}: &str = "{{attribute.fqn}}";
61-
# to generate the consts, where to_const_name replaces '.' with '_', we need to remove the old definition
62-
# to avoid conflicts with the new one. Refer - https://github.com/open-telemetry/semantic-conventions/issues/1031
63-
"${SED[@]}" '/\/\/\/ Deprecated, use `messaging.client.id` instead\./{N;N;N;N;d;}' src/trace.rs src/resource.rs
64-
"${SED[@]}" '/pub const MESSAGING_CLIENT_ID: &str = "messaging.client_id";/{N;d;}' src/trace.rs src/resource.rs
75+
# handle escaping ranges like [0,n] / [0.0, ...] in descriptions/notes which will cause broken intra-doc links
76+
# unescape any mistakenly escaped ranges which actually contained a link (not that we currently have any)
77+
expression='
78+
s/\[([a-zA-Z0-9\.\s]+,[a-zA-Z0-9\.\s]+)\]/\\[\1\\]/g
79+
s/\\\[([^\]]+)\]\(([^)]+)\)/[\1](\2)/g
80+
'
81+
"${SED[@]}" -E "${expression}" src/metric.rs
82+
"${SED[@]}" -E "${expression}" src/attribute.rs
6583

6684
cargo fmt

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

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
//! # Semantic Attributes
2+
//!
3+
//! 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

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
//! # Metric Semantic Conventions
2+
//!
3+
//! The [metric semantic conventions] define a set of standardized attributes to
4+
//! be used in `Meter`s.
5+
//!
6+
//! [metric semantic conventions]: https://github.com/open-telemetry/semantic-conventions/tree/main/model/metric
7+
//!
8+
//! ## Usage
9+
//!
10+
//! ```rust
11+
//! use opentelemetry::{global, KeyValue};
12+
//! use opentelemetry_semantic_conventions as semconv;
13+
//!
14+
//! // Assumes we already have an initialized `MeterProvider`
15+
//! // See: https://github.com/open-telemetry/opentelemetry-rust/blob/main/examples/metrics-basic/src/main.rs
16+
//! // for an example
17+
//! let meter = global::meter("mylibraryname");
18+
//! let histogram = meter
19+
//! .u64_histogram(semconv::metric::HTTP_SERVER_REQUEST_DURATION)
20+
//! .with_unit("By")
21+
//! .with_description("Duration of HTTP server requests.")
22+
//! .init();
23+
//! ```

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
//!
88
//! ## Usage
99
//!
10-
//! ```
10+
//! ```rust
1111
//! use opentelemetry::KeyValue;
1212
//! use opentelemetry_sdk::{trace::{config, TracerProvider}, Resource};
1313
//! use opentelemetry_semantic_conventions as semconv;

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

+3-3
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
//!
88
//! ## Usage
99
//!
10-
//! ```
10+
//! ```rust
1111
//! use opentelemetry::KeyValue;
1212
//! use opentelemetry::{global, trace::Tracer as _};
1313
//! use opentelemetry_semantic_conventions as semconv;
@@ -16,8 +16,8 @@
1616
//! let _span = tracer
1717
//! .span_builder("span-name")
1818
//! .with_attributes(vec![
19-
//! KeyValue::new(semconv::trace::NET_PEER_NAME, "example.org"),
20-
//! KeyValue::new(semconv::trace::NET_PEER_PORT, 80i64),
19+
//! KeyValue::new(semconv::trace::CLIENT_ADDRESS, "example.org"),
20+
//! KeyValue::new(semconv::trace::CLIENT_PORT, 80i64),
2121
//! ])
2222
//! .start(&tracer);
2323
//! ```

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

+12-3
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,16 @@
66

77
{% include 'header_' + conventions + '.rs' %}
88

9-
{%- for attribute in attributes if attribute.is_local and not attribute.ref %}
9+
{%- for attribute in attributes %}
10+
{%- set x=attribute.__setattr__("fqn_const_name", (attribute.fqn | to_const_name)) %}
11+
{%- endfor %}
1012

13+
{%- for name, attrs in (attributes | groupby('fqn_const_name')) %}
14+
{%- set attribute = (attrs | selectattr('deprecated', 'none') | first) %}
15+
{%- set attribute = attribute if attribute else (attrs | first) %}
16+
{%- if conventions != 'attribute' %}
17+
pub use crate::attribute::{{ attribute.fqn_const_name }};
18+
{%- else %}
1119
/// {% filter escape %}{{attribute.brief | to_doc_brief}}.{% endfilter %}
1220
{%- if attribute.note %}
1321
///
@@ -23,8 +31,9 @@
2331
/// - `{{example}}`
2432
{%- endfor %}
2533
{%- endif %}
26-
{%- if (attribute.stability | string()) == "StabilityLevel.DEPRECATED" %}
34+
{%- if (attribute.deprecated) %}
2735
#[deprecated]
2836
{%- endif %}
29-
pub const {{attribute.fqn | to_const_name}}: &str = "{{attribute.fqn}}";
37+
pub const {{ attribute.fqn_const_name }}: &str = "{{attribute.fqn}}";
38+
{%- endif %}
3039
{%- endfor %}

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

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// DO NOT EDIT, this is an auto-generated file
2+
//
3+
// If you want to update the file:
4+
// - Edit the template at scripts{{template}}
5+
// - Run the script at scripts/generate-consts-from-spec.sh
6+
7+
{% include 'header_metric.rs' %}
8+
9+
{%- for metric in metrics %}
10+
/// ## Description
11+
/// {% filter escape %}{{ metric.brief | to_doc_brief }}.{% endfilter %}
12+
{%- if metric.note %}
13+
///
14+
{%- for line in metric.note.split('\n') %}
15+
/// {% filter escape %}{{ line }}{% endfilter %}
16+
{%- endfor %}
17+
{%- endif %}
18+
/// ## Metadata
19+
/// | | |
20+
/// |:-|:-
21+
/// | Instrument: | `{{ metric.instrument }}` |
22+
/// | Unit: | `{{ metric.unit }}` |
23+
/// | Status: | `{{ ((metric.stability | string()).split('.')[1].replace('_', ' ')) | capitalize }}` |
24+
{%- if metric.attributes %}
25+
///
26+
/// ## Attributes
27+
/// | Name | Requirement |
28+
/// |:-|:- |
29+
{%- endif %}
30+
{%- for attribute in metric.attributes %}
31+
{%- if attribute.ref %}
32+
{%- set ref = (attributes | selectattr('fqn', 'equalto', attribute.ref) | first) %}
33+
{%- if ref %}
34+
{%- if attribute.requirement_level %}
35+
{%- set req_level = ((attribute.requirement_level | string()).split('.')[1].replace('_', ' ')) | capitalize %}
36+
{%- set req_message = attribute.requirement_level_msg %}
37+
{%- else %}
38+
{%- set req_level = "Unspecified" %}
39+
{%- set req_message = '' %}
40+
{%- endif %}
41+
/// | [`crate::attribute::{{ ref.fqn | to_const_name }}`] | `{{ req_level }}`{{ (': ' + req_message if req_message else '') }}
42+
{%- endif %}
43+
{%- endif %}
44+
{%- endfor %}
45+
{%- if metric.examples %}
46+
///
47+
/// # Examples
48+
///
49+
{%- for example in metric.examples %}
50+
/// - `{{ example }}`
51+
{%- endfor %}
52+
{%- endif %}
53+
{%- if (metric.deprecated) %}
54+
#[deprecated]
55+
{%- endif %}
56+
pub const {{ metric.metric_name | to_const_name }}: &str = "{{ metric.metric_name }}";
57+
{%- endfor %}

0 commit comments

Comments
 (0)