First cut at porting over markdown generation code from python into r…

…ust. Preserving existing logic/structure as much as is reasonable for now.

Cargo.toml

@@ -51,6 +51,7 @@ weaver_logger = { path = "crates/weaver_logger" }
 weaver_resolver = { path = "crates/weaver_resolver" }
 weaver_template = { path = "crates/weaver_template" }
 weaver_semconv = { path = "crates/weaver_semconv" }
+weaver_semconv_gen = { path = "crates/weaver_semconv_gen" }
 weaver_schema = { path = "crates/weaver_schema" }
 weaver_cache = { path = "crates/weaver_cache" }
 weaver_forge = { path = "crates/weaver_forge" }

crates/weaver_semconv_gen/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "weaver_semconv_gen"
+version = "0.1.0"
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+publish.workspace = true
+edition.workspace = true
+
+[dependencies]
+weaver_logger = { path = "../weaver_logger" }
+weaver_resolver = { path = "../weaver_resolver" }
+weaver_resolved_schema = { path = "../weaver_resolved_schema" }
+weaver_semconv = { path = "../weaver_semconv" }
+itertools = "0.12.1"
+
+thiserror.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true
+serde_json.workspace = true
+rayon.workspace = true
+walkdir.workspace = true

crates/weaver_semconv_gen/README.md

@@ -0,0 +1,5 @@
+# Semanticf Convention markdown updater
+
+Status: **Work-In-Progress**
+
+This crate duplicates the semconv templating from open-telemetry/build-tools.

crates/weaver_semconv_gen/data/http-common.yaml

@@ -0,0 +1,87 @@
+groups:
+  - id: attributes.http.common
+    type: attribute_group
+    brief: "Describes HTTP attributes."
+    attributes:
+      - ref: http.request.method
+        requirement_level: required
+      - ref: http.response.status_code
+        requirement_level:
+          conditionally_required: If and only if one was received/sent.
+      - ref: error.type
+        requirement_level:
+          conditionally_required: If request has ended with an error.
+        examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500']
+        note: |
+          If the request fails with an error before response status code was sent or received,
+          `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
+          or a component-specific low cardinality error identifier.
+
+          If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
+          `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier.
+
+          The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
+          Instrumentations SHOULD document the list of errors they report.
+
+          The cardinality of `error.type` within one instrumentation library SHOULD be low, but
+          telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+          should be prepared for `error.type` to have high cardinality at query time, when no
+          additional filters are applied.
+
+          If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
+      - ref: network.protocol.name
+        examples: ['http', 'spdy']
+        requirement_level:
+          conditionally_required: If not `http` and `network.protocol.version` is set.
+      - ref: network.protocol.version
+        examples: ['1.0', '1.1', '2', '3']
+
+  - id: attributes.http.client
+    type: attribute_group
+    brief: 'HTTP Client attributes'
+    extends: attributes.http.common
+    attributes:
+      - ref: server.address
+        requirement_level: required
+        brief: >
+          Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.
+        note: >
+          If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then
+          `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
+      - ref: server.port
+        requirement_level: required
+        brief: >
+          Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.
+      - ref: url.scheme
+        requirement_level: opt_in
+        examples: ["http", "https"]
+
+  - id: attributes.http.server
+    type: attribute_group
+    brief: 'HTTP Server attributes'
+    extends: attributes.http.common
+    attributes:
+      - ref: http.route
+        requirement_level:
+          conditionally_required: If and only if it's available
+      - ref: server.address
+        brief: >
+          Name of the local HTTP server that received the request.
+        note: >
+          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+      - ref: server.port
+        brief: >
+          Port of the local HTTP server that received the request.
+        note: >
+          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+        requirement_level:
+          conditionally_required: If `server.address` is set.
+      - ref: url.scheme
+        requirement_level: required
+        examples: ["http", "https"]
+        note: >
+          The scheme of the original client request, if known
+          (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto),
+          [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto),
+          or a similar header).
+          Otherwise, the scheme of the immediate peer request.

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

@@ -0,0 +1,94 @@
+<!-- semconv trace.http.common(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. |
+| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
+| [`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] |
+| [`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. [4] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | Opt-In |
+| [`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. |
+| [`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 |
+| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. |
+| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | Conditionally Required: [6] |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`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 |
+
+**[1]:** If the request fails with an error before response status code was sent or received,
+`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
+or a component-specific low cardinality error identifier.
+
+If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
+`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier.
+
+The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
+Instrumentations SHOULD document the list of errors they report.
+
+The cardinality of `error.type` within one instrumentation library SHOULD be low, but
+telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+should be prepared for `error.type` to have high cardinality at query time, when no
+additional filters are applied.
+
+If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
+
+**[2]:** 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)
+and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`.
+
+If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override
+the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named
+OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods
+(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
+Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
+
+**[3]:** If and only if it's different than `http.request.method`.
+
+**[4]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
+Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
+The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
+
+**[5]:** The value SHOULD be normalized to lowercase.
+
+**[6]:** If not `http` and `network.protocol.version` is set.
+
+**[7]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+
+**[8]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible.
+
+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)
+
+`error.type` 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.
+
+| Value  | Description |
+|---|---|
+| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |
+
+`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.
+
+| Value  | Description |
+|---|---|
+| `CONNECT` | CONNECT method. |
+| `DELETE` | DELETE method. |
+| `GET` | GET method. |
+| `HEAD` | HEAD method. |
+| `OPTIONS` | OPTIONS method. |
+| `PATCH` | PATCH method. |
+| `POST` | POST method. |
+| `PUT` | PUT method. |
+| `TRACE` | TRACE method. |
+| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. |
+
+`network.transport` 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.
+
+| Value  | Description |
+|---|---|
+| `tcp` | TCP |
+| `udp` | UDP |
+| `pipe` | Named or anonymous pipe. |
+| `unix` | Unix domain socket |
+<!-- endsemconv -->

crates/weaver_semconv_gen/data/registry/client.yaml

@@ -0,0 +1,28 @@
+groups:
+  - id: client
+    prefix: client
+    type: attribute_group
+    brief: >
+      These attributes may be used to describe the client in a connection-based network interaction
+      where there is one side that initiates the connection (the client is the side that initiates the connection).
+      This covers all TCP network interactions since TCP is connection-based and one side initiates the
+      connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the
+      protocol / API doesn't expose a clear notion of client and server).
+      This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.
+    attributes:
+      - id: address
+        stability: stable
+        type: string
+        brief: "Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name."
+        note: >
+          When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent
+          the client address behind any intermediaries,  for example proxies, if it's available.
+        examples: ['client.example.com', '10.1.2.80', '/tmp/my.sock']
+      - id: port
+        stability: stable
+        type: int
+        brief: Client port number.
+        examples: [65123]
+        note: >
+          When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent
+          the client port behind any intermediaries,  for example proxies, if it's available.

crates/weaver_semconv_gen/data/registry/error.yaml

@@ -0,0 +1,35 @@
+groups:
+  - id: registry.error
+    type: attribute_group
+    prefix: error
+    brief: >
+      This document defines the shared attributes used to report an error.
+    attributes:
+      - id: type
+        stability: stable
+        brief: >
+          Describes a class of error the operation ended with.
+        type:
+          allow_custom_values: true
+          members:
+            - id: other
+              value: "_OTHER"
+              brief: >
+                A fallback error value to be used when the instrumentation doesn't define a custom value.
+        examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500']
+        note: |
+          The `error.type` SHOULD be predictable and SHOULD have low cardinality.
+          Instrumentations SHOULD document the list of errors they report.
+
+          The cardinality of `error.type` within one instrumentation library SHOULD be low.
+          Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+          should be prepared for `error.type` to have high cardinality at query time when no
+          additional filters are applied.
+
+          If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
+
+          If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
+          it's RECOMMENDED to:
+
+          * Use a domain-specific attribute
+          * Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.