Metrics table generation from yaml

semantic-conventions/CHANGELOG.md

@@ -4,7 +4,8 @@ Please update the changelog as part of any significant pull request.
 
 ## Unreleased
 
-- ...
+- Add definitions for metrics in YAML semconv, plus generation to markdown
+  ([#79](https://github.com/open-telemetry/build-tools/pull/79))
 
 ## v0.14.0
 

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.active_requests(metric_table) -->` will print a table describing a single metric 
+`http.server.active_requests`. 
+
 ## Code Generator
 
 The image supports [Jinja](https://jinja.palletsprojects.com/en/2.11.x/) templates to generate code from the models.

semantic-conventions/semconv.schema.json

@@ -16,6 +16,9 @@
 					},
 					{
 						"allOf": [{"$ref": "#/definitions/EventSemanticConvention"}]
+					},
+					{
+						"allOf": [{"$ref": "#/definitions/MetricSemanticConvention"}]
 					}
 				]
 			}
@@ -164,6 +167,33 @@
 				{"required": ["name"]}
 			]
 		},
+		"MetricSemanticConvention": {
+			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
+			"properties": {
+				"instrument": {
+					"type": "string",
+					"description": "The instrument used to record the metric.",
+					"enum": [
+						"counter",
+						"gauge",
+						"histogram",
+						"updowncounter"
+					]
+				},
+				"metric_name": {
+					"type": "string",
+					"description": "The name of the metric."
+				},
+				"type": {
+					"type": "string",
+					"const": "metric"
+				},
+				"unit": {
+					"type": "string",
+					"description": "The unit in which the metric is measured in."
+				}
+			}
+		},
 		"SemanticConvention": {
 			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
 			"required": ["type"],

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

@@ -16,7 +16,7 @@
 import typing
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Tuple, Union
+from typing import Dict, Tuple, Union
 
 from ruamel.yaml import YAML
 
@@ -247,7 +247,48 @@ def __init__(self, group):
 class MetricSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "metric"
 
-    allowed_keys = ()
+    allowed_keys: Tuple[str, ...] = BaseSemanticConvention.allowed_keys + (
+        "metric_name",
+        "unit",
+        "instrument",
+    )
+
+    yaml_to_markdown_instrument_repr: Dict[str, str] = {
+        "counter": "Counter",
+        "updowncounter": "UpDownCounter",
+        "histogram": "Histogram",
+        "gauge": "Gauge",
+    }
+
+    allowed_instruments: Tuple[str, ...] = tuple(
+        yaml_to_markdown_instrument_repr.keys()
+    ) + (None,)
+
+    def __init__(self, group):
+        super().__init__(group)
+        self.metric_name = group.get("metric_name")
+        self.unit = group.get("unit")
+        self.instrument = group.get("instrument")
+        self.instrument_markdown_fmt = self.yaml_to_markdown_instrument_repr.get(
+            self.instrument
+        )
+        self.validate()
+
+    def validate(self):
+        val_tuple = (self.metric_name, self.unit, self.instrument)
+        if not all(val_tuple) and any(val_tuple):
+            raise ValidationError.from_yaml_pos(
+                self._position,
+                "Either all or none of name, units, and instrument must be defined",
+            )
+
+        if self.instrument not in self.allowed_instruments:
+            raise ValidationError.from_yaml_pos(
+                self._position,
+                "Instrument '{}' is not a valid instrument name".format(
+                    self.instrument
+                ),
+            )
 
 
 @dataclass

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

@@ -29,7 +29,9 @@
     StabilityLevel,
 )
 from opentelemetry.semconv.model.semantic_convention import (
+    BaseSemanticConvention,
     EventSemanticConvention,
+    MetricSemanticConvention,
     SemanticConventionSet,
     UnitSemanticConvention,
 )
@@ -41,6 +43,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 +69,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  | Requirement Level |\n|---|---|---|---|---|\n"
@@ -186,6 +189,61 @@ def to_markdown_attr(
             )
         )
 
+    def to_markdown_attribute_table(
+        self, semconv: BaseSemanticConvention, output: io.StringIO
+    ):
+        attr_to_print = []
+        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)
+        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)
+        attr_sampling_relevant = [
+            attr for attr in attr_to_print if attr.sampling_relevant
+        ]
+        self.to_creation_time_attributes(attr_sampling_relevant, output)
+
+    @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 Type | Unit (UCUM) | Description    |\n"
+            "| -------- | --------------- | ----------- | -------------- |\n"
+        )
+        output.write(
+            "| `{}` | {} | `{}` | {} |\n".format(
+                semconv.metric_name,
+                semconv.instrument_markdown_fmt,
+                semconv.unit,
+                semconv.brief,
+            )
+        )
+
     def to_markdown_anyof(self, anyof: AnyOf, output: io.StringIO):
         """
         This method renders anyof constraints into markdown lists
@@ -428,31 +486,15 @@ 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))
+        if self.render_ctx.is_metric_table:
+            self.to_markdown_metric_table(semconv, output)
+        else:
+            if isinstance(semconv, EventSemanticConvention):
+                output.write("The event name MUST be `{}`.\n\n".format(semconv.name))
+            self.to_markdown_attribute_table(semconv, output)
 
-        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:
-                    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 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:
@@ -462,9 +504,4 @@ def _render_group(self, semconv, parameters, output):
         if isinstance(semconv, UnitSemanticConvention):
             self.to_markdown_unit_table(semconv.members, output)
 
-        attr_sampling_relevant = [
-            attr for attr in attr_to_print if attr.sampling_relevant
-        ]
-        self.to_creation_time_attributes(attr_sampling_relevant, output)
-
         output.write("<!-- endsemconv -->")

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

@@ -0,0 +1,16 @@
+# Test Markdown
+
+**`foo.size`**
+<!-- semconv metric.foo.size(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `foo.size` | Histogram | `{bars}` | Measures the size of foo. |
+<!-- endsemconv -->
+
+**Attributes for `foo.size`**
+<!-- semconv metric.foo.size -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: if and only if one was received/sent. |
+<!-- endsemconv -->

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

@@ -0,0 +1,9 @@
+# Test Markdown
+
+**`foo.size`**
+<!-- semconv metric.foo.size(metric_table) -->
+<!-- endsemconv -->
+
+**Attributes for `foo.size`**
+<!-- semconv metric.foo.size -->
+<!-- endsemconv -->

semantic-conventions/src/tests/data/yaml/metrics.yaml

@@ -0,0 +1,22 @@
+groups:
+  - id: metric.foo
+    prefix: foo
+    type: metric
+    brief: "This document defines foo."
+    note: >
+        Details about foo.
+
+  - id: metric.foo.size
+    prefix: foo
+    type: metric
+    extends: metric.foo
+    metric_name: foo.size
+    brief: "Measures the size of foo."
+    instrument: histogram
+    unit: "{bars}"
+    attributes:
+      - ref: http.method
+        requirement_level: required
+      - ref: http.status_code
+        requirement_level:
+          conditionally_required: "if and only if one was received/sent."

semantic-conventions/src/tests/semconv/model/test_correct_parse.py

@@ -14,11 +14,13 @@
 
 import os
 import unittest
+from typing import List, cast
 
 from opentelemetry.semconv.model.constraints import AnyOf, Include
 from opentelemetry.semconv.model.semantic_attribute import StabilityLevel
 from opentelemetry.semconv.model.semantic_convention import (
     EventSemanticConvention,
+    MetricSemanticConvention,
     SemanticConventionSet,
     SpanSemanticConvention,
 )
@@ -193,6 +195,44 @@ def test_http(self):
         }
         self.semantic_convention_check(list(semconv.models.values())[2], expected)
 
+    def test_metrics(self):
+        semconv = SemanticConventionSet(debug=False)
+        semconv.parse(self.load_file("yaml/metrics.yaml"))
+        self.assertEqual(len(semconv.models), 2)
+        semconv.parse(self.load_file("yaml/general.yaml"))
+        semconv.parse(self.load_file("yaml/http.yaml"))
+
+        metric_semconvs = cast(
+            List[MetricSemanticConvention], list(semconv.models.values())[:2]
+        )
+
+        expected = {
+            "id": "metric.foo",
+            "prefix": "foo",
+            "extends": "",
+            "n_constraints": 0,
+            "attributes": [],
+        }
+        self.semantic_convention_check(metric_semconvs[0], expected)
+
+        expected = {
+            "id": "metric.foo.size",
+            "prefix": "foo",
+            "extends": "metric.foo",
+            "n_constraints": 0,
+            "metric_name": "foo.size",
+            "unit": "{bars}",
+            "instrument": "histogram",
+            "attributes": [
+                "http.method",
+                "http.status_code",
+            ],
+        }
+        self.semantic_convention_check(metric_semconvs[1], expected)
+        self.assertEqual(metric_semconvs[1].unit, expected["unit"])
+        self.assertEqual(metric_semconvs[1].instrument, expected["instrument"])
+        self.assertEqual(metric_semconvs[1].metric_name, expected["metric_name"])
+
     def test_resource(self):
         semconv = SemanticConventionSet(debug=False)
         semconv.parse(self.load_file("yaml/cloud.yaml"))