Metrics table generation from yaml

semantic-conventions/README.md

@@ -83,6 +83,9 @@ convention that have the tag `network`.
 `<!-- semconv http.server(tag=network, full) -->` will print the constraints and attributes of both `http` and `http.server`
 semantic conventions that have the tag `network`.
 
+`<!-- semconv metric.http.server(metric_table) -->` will print a table of metrics with all metrics prefixed with 
+`metric.http.server`.
+
 ## Code Generator
 
 The image supports [Jinja](https://jinja.palletsprojects.com/en/2.11.x/) templates to generate code from the models.

semantic-conventions/dev-requirements.txt

@@ -1,4 +1,4 @@
-black==21.8b0
+black==22.3.0
 mypy==0.910
 pytest==6.2.5
 flake8==3.9.2

semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py

@@ -53,6 +53,32 @@ def parse(span_kind_value):
         return kind_map.get(span_kind_value)
 
 
+class InstrumentKind(Enum):
+    COUNTER = 1
+    UP_DOWN_COUNTER = 2
+    HISTOGRAM = 3
+    GAUGE = 4
+
+    @staticmethod
+    def parse(instrument_kind_value):
+        return InstrumentKind.kind_map().get(instrument_kind_value)
+
+    @staticmethod
+    def kind_map():
+        return {
+            "Counter": InstrumentKind.COUNTER,
+            "UpDownCounter": InstrumentKind.UP_DOWN_COUNTER,
+            "Histogram": InstrumentKind.HISTOGRAM,
+            "Gauge": InstrumentKind.GAUGE,
+        }
+
+    def __str__(self):
+        # reverse lookup kind_map()
+        return next(filter(lambda i: i[1] is self, InstrumentKind.kind_map().items()))[
+            0
+        ]
+
+
 def parse_semantic_convention_type(type_value):
     # Gracefully transition to the new types
     if type_value is None:
@@ -238,7 +264,43 @@ def __init__(self, group):
 class MetricSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "metric"
 
-    allowed_keys = ()
+    allowed_keys: Tuple[str, ...] = BaseSemanticConvention.allowed_keys + ("metrics",)
+
+    class Metric:
+        def __init__(self, metric, parent_prefix, position):
+            self.id: str = metric.get("id")
+            self.fqn = "{}.{}".format(parent_prefix, self.id)
+            self._position = position
+            self.units: str = metric.get("units")
+            self.brief: str = metric.get("brief")
+            instrument_str = metric.get("instrument")
+            self.instrument: InstrumentKind = InstrumentKind.parse(instrument_str)
+
+            if None in [instrument_str, self.id, self.units, self.brief]:
+                raise ValidationError.from_yaml_pos(
+                    self._position,
+                    "id, instrument, units, and brief must all be defined for concrete metrics",
+                )
+            if self.instrument is None:
+                raise ValidationError.from_yaml_pos(
+                    self._position,
+                    "Instrument '{}' is not a valid instrument name".format(
+                        metric.get("instrument")
+                    ),
+                )
+
+    def __init__(self, group):
+        super().__init__(group)
+        self.metrics = ()
+        if group.get("metrics"):
+            self.metrics: Tuple[MetricSemanticConvention.Metric, ...] = tuple(
+                map(
+                    lambda m: MetricSemanticConvention.Metric(
+                        m, self.prefix, self._position
+                    ),
+                    group.get("metrics"),
+                )
+            )
 
 
 @dataclass

semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py

@@ -30,6 +30,7 @@
 )
 from opentelemetry.semconv.model.semantic_convention import (
     EventSemanticConvention,
+    MetricSemanticConvention,
     SemanticConventionSet,
     UnitSemanticConvention,
 )
@@ -41,6 +42,7 @@ class RenderContext:
     def __init__(self):
         self.is_full = False
         self.is_remove_constraint = False
+        self.is_metric_table = False
         self.group_key = ""
         self.enums = []
         self.notes = []
@@ -66,7 +68,7 @@ class MarkdownRenderer:
     )
     p_end = re.compile("<!--\\s*endsemconv\\s*-->")
     default_break_conditional_labels = 50
-    valid_parameters = ["tag", "full", "remove_constraints"]
+    valid_parameters = ["tag", "full", "remove_constraints", "metric_table"]
 
     prelude = "<!-- semconv {} -->\n"
     table_headers = "| Attribute  | Type | Description  | Examples  | Required |\n|---|---|---|---|---|\n"
@@ -174,6 +176,31 @@ def to_markdown_attr(
             )
         )
 
+    @staticmethod
+    def to_markdown_metric_table(
+        semconv: MetricSemanticConvention, output: io.StringIO
+    ):
+        """
+        This method renders metrics as markdown table entry
+        """
+        if not isinstance(semconv, MetricSemanticConvention):
+            raise ValueError(
+                "semconv `{}` was specified with `metric_table`, but it is not a metric convention".format(
+                    semconv.semconv_id
+                )
+            )
+
+        output.write(
+            "| Name     | Instrument    | Unit (UCUM) | Description    |\n"
+            "| -------- | ------------- | ----------- | -------------- |\n"
+        )
+        for metric in semconv.metrics:
+            output.write(
+                "| `{}` | {} | `{}` | {} |\n".format(
+                    metric.fqn, metric.instrument, metric.units, metric.brief
+                )
+            )
+
     def to_markdown_anyof(self, anyof: AnyOf, output: io.StringIO):
         """
         This method renders anyof constraints into markdown lists
@@ -416,31 +443,36 @@ def _render_group(self, semconv, parameters, output):
         self.render_ctx.is_remove_constraint = "remove_constraints" in parameters
         self.render_ctx.group_key = parameters.get("tag")
         self.render_ctx.is_full = "full" in parameters
+        self.render_ctx.is_metric_table = "metric_table" in parameters
 
         if isinstance(semconv, EventSemanticConvention):
             output.write("The event name MUST be `{}`.\n\n".format(semconv.name))
 
         attr_to_print = []
-        attr: SemanticAttribute
-        for attr in sorted(
-            semconv.attributes, key=lambda a: "" if a.ref is None else a.ref
-        ):
-            if self.render_ctx.group_key is not None:
-                if attr.tag == self.render_ctx.group_key:
+        if self.render_ctx.is_metric_table:
+            self.to_markdown_metric_table(semconv, output)
+        else:
+            attr: SemanticAttribute
+            for attr in sorted(
+                semconv.attributes, key=lambda a: "" if a.ref is None else a.ref
+            ):
+                if self.render_ctx.group_key is not None:
+                    if attr.tag == self.render_ctx.group_key:
+                        attr_to_print.append(attr)
+                    continue
+                if self.render_ctx.is_full or attr.is_local:
                     attr_to_print.append(attr)
-                continue
-            if self.render_ctx.is_full or attr.is_local:
-                attr_to_print.append(attr)
-        if self.render_ctx.group_key is not None and not attr_to_print:
-            raise ValueError(
-                "No attributes retained for '{}' filtering by '{}'".format(
-                    semconv.semconv_id, self.render_ctx.group_key
+            if self.render_ctx.group_key is not None and not attr_to_print:
+                raise ValueError(
+                    "No attributes retained for '{}' filtering by '{}'".format(
+                        semconv.semconv_id, self.render_ctx.group_key
+                    )
                 )
-            )
-        if attr_to_print:
-            output.write(MarkdownRenderer.table_headers)
-            for attr in attr_to_print:
-                self.to_markdown_attr(attr, output)
+            if attr_to_print:
+                output.write(MarkdownRenderer.table_headers)
+                for attr in attr_to_print:
+                    self.to_markdown_attr(attr, output)
+
         self.to_markdown_notes(output)
         if not self.render_ctx.is_remove_constraint:
             for cnst in semconv.constraints:

semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md

@@ -0,0 +1,76 @@
+
+## Common Attributes
+
+The following attributes SHOULD be included on all HTTP metrics for both server and client. 
+
+<!-- semconv metric.http -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). An empty Host header should also be reported, see note. [1] | `www.example.org` | See attribute alternatives |
+| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Yes |
+| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See attribute alternative |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | No |
+
+**[1]:** When the header is present but empty the attribute SHOULD be set to the empty string. Note that this is a valid situation that is expected in certain cases, according the aforementioned [section of RFC 7230](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is not set the attribute MUST NOT be set.
+<!-- endsemconv -->
+
+## HTTP Client 
+
+### HTTP Client Metrics
+
+<!-- semconv metric.http.client(metric_table,remove_constraints) -->
+| Name     | Instrument    | Unit (UCUM) | Description    |
+| -------- | ------------- | ----------- | -------------- |
+| `metric.http.client.duration` | Histogram | `ms` | Measures the duration of the outbound HTTP request. |
+<!-- endsemconv -->
+
+### HTTP Client Attributes
+
+The following attributes SHOULD be included on HTTP Client metrics, where applicable and available.
+
+<!-- semconv metric.http.client -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below |
+| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | See below |
+| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | See below |
+
+**Additional attribute requirements:** At least one of the following sets of attributes is required:
+
+* `http.url`
+* `http.scheme`, `http.host`, `http.target`
+* `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target`
+* `http.scheme`, `net.peer.ip`, `net.peer.port`, `http.target`
+<!-- endsemconv -->
+
+## HTTP Server
+
+### HTTP Server Metrics
+
+<!-- semconv metric.http.server(metric_table,remove_constraints) -->
+| Name     | Instrument    | Unit (UCUM) | Description    |
+| -------- | ------------- | ----------- | -------------- |
+| `metric.http.server.duration` | Histogram | `ms` | Measures the duration of the inbound HTTP request. |
+| `metric.http.server.active_requests` | UpDownCounter | `{requests}` | Measures the number of concurrent HTTP requests that are currently in-flight. |
+<!-- endsemconv -->
+
+### HTTP Server Attributes
+
+The following attributes SHOULD be included on HTTP Server metrics, where applicable and available.
+
+<!-- semconv metric.http.server -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `http.server_name` | string | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). [1] | `example.com` | See below |
+| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | See below |
+| `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | See below |
+
+**[1]:** `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.
+
+**Additional attribute requirements:** At least one of the following sets of attributes is required:
+
+* `http.scheme`, `http.host`, `http.target`
+* `http.scheme`, `http.server_name`, `net.host.port`, `http.target`
+* `http.scheme`, `net.host.name`, `net.host.port`, `http.target`
+* `http.url`
+<!-- endsemconv -->