Merge pull request #118 from jsuereth/fix-subtle-issues

(fix) Fixes some subtle issues in weaver-semconv-gen

crates/weaver_semconv_gen/data/http-span-full-attribute-table.md

@@ -1,16 +1,16 @@
 <!-- semconv trace.http.common(full) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`http.request.method_original`](../attributes-registry/http.md) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | `Conditionally Required` [3] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`http.response.header.<key>`](../attributes-registry/http.md) | string[] | HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values. [7] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`http.request.method_original`](/docs/attributes-registry/http.md) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | `Conditionally Required` [3] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`http.response.status_code`](/docs/attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`network.protocol.version`](/docs/attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`http.response.header.<key>`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values. [7] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
 **[1]:** HTTP request method value SHOULD be "known" to the instrumentation.
 By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
@@ -60,7 +60,7 @@ The attribute value MUST consist of either multiple header values as an array of
 
 The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all):
 
-* [`http.request.method`](../attributes-registry/http.md)
+* [`http.request.method`](/docs/attributes-registry/http.md)
 
 `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 

crates/weaver_semconv_gen/data/user-agent.md

@@ -0,0 +1,13 @@
+# Tests if user_agent becomes user-agent
+
+<!-- semconv registry.user_agent -->
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`user_agent.name`](/docs/attributes-registry/user-agent.md) | string | Name of the user-agent extracted from original. Usually refers to the browser's name. [1] | `Safari`; `YourApp` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`user_agent.version`](/docs/attributes-registry/user-agent.md) | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2`; `1.0.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version`
+
+**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name`
+<!-- endsemconv -->

crates/weaver_semconv_gen/src/gen.rs

@@ -142,7 +142,13 @@ impl<'a> AttributeView<'a> {
     }
 
     fn write_registry_link<T: Write>(&self, out: &mut T, prefix: &str) -> Result<(), Error> {
-        let reg_name = self.attribute.name.split('.').next().unwrap_or("");
+        let reg_name = self
+            .attribute
+            .name
+            .split('.')
+            .next()
+            .unwrap_or("")
+            .replace('_', "-");
         // TODO - We should try to link to the name itself, instead
         // of just the correct group.
         Ok(write!(out, "{prefix}/{reg_name}.md")?)
@@ -191,6 +197,9 @@ impl<'a> AttributeView<'a> {
                 write!(out, " | ")?;
                 if let Some(v) = m.brief.as_ref() {
                     write!(out, "{}", v.trim())?;
+                } else {
+                    // Use the value as the description if missing a brief.
+                    write!(out, "{}", m.value)?;
                 }
                 // Stability.
                 write!(out, " | ")?;

crates/weaver_semconv_gen/src/lib.rs

@@ -271,20 +271,21 @@ mod tests {
     #[test]
     fn test_http_semconv() -> Result<(), Error> {
         let lookup = ResolvedSemconvRegistry::try_from_path("data/**/*.yaml")?;
-        let attribute_registry_url = "../attributes-registry";
+        let attribute_registry_url = "/docs/attributes-registry";
         // Check our test files.
-        force_print_error(update_markdown(
+        for test in [
             "data/http-span-full-attribute-table.md",
-            &lookup,
-            true,
-            Some(attribute_registry_url),
-        ));
-        force_print_error(update_markdown(
             "data/http-metric-semconv.md",
-            &lookup,
-            true,
-            Some(attribute_registry_url),
-        ));
+            "data/user-agent.md",
+        ] {
+            println!("--- Running test: {test} ---");
+            force_print_error(update_markdown(
+                test,
+                &lookup,
+                true,
+                Some(attribute_registry_url),
+            ));
+        }
         Ok(())
     }
 

crates/weaver_semconv_gen/src/parser.rs

@@ -72,7 +72,7 @@ fn parse_markdown_gen_parameters(input: &str) -> IResult<&str, Vec<MarkdownGenPa
 
 /// nom parser for semconv ids.
 fn parse_id(input: &str) -> IResult<&str, &str> {
-    recognize(many0_count(alt((alpha1, tag(".")))))(input)
+    recognize(many0_count(alt((alpha1, tag("."), tag("_"), tag("-")))))(input)
 }
 
 /// nom parser for <!-- semconv {id}({args}) -->
@@ -131,6 +131,9 @@ mod tests {
 
     #[test]
     fn recognizes_header() {
+        assert!(is_markdown_snippet_directive(
+            "<!-- semconv registry.user_agent -->"
+        ));
         assert!(is_markdown_snippet_directive(
             "<!-- semconv my.id(full) -->"
         ));