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"}]
 					}
 				]
 			}
@@ -51,6 +54,7 @@
 						"span",
 						"resource",
 						"metric",
+						"metric_group",
 						"event",
 						"scope"
 					],
@@ -164,6 +168,49 @@
 				{"required": ["name"]}
 			]
 		},
+		"MetricGroupSemanticConvention": {
+			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
+			"required": ["type"],
+			"properties": {
+				"type": {
+					"type": "string",
+					"const": "metric_group"
+				}
+			}
+		},
+		"MetricSemanticConvention": {
+			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
+			"required": [
+				"type",
+				"metric_name",
+				"instrument",
+				"unit"
+			],
+			"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
 
@@ -244,10 +244,55 @@ def __init__(self, group):
         self.members = UnitMember.parse(group.get("members"))
 
 
-class MetricSemanticConvention(BaseSemanticConvention):
+class MetricGroupSemanticConvention(BaseSemanticConvention):
+    GROUP_TYPE_NAME = "metric_group"
+
+
+class MetricSemanticConvention(MetricGroupSemanticConvention):
     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()
+    )
+
+    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):
+            raise ValidationError.from_yaml_pos(
+                self._position,
+                "All of metric_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
@@ -543,6 +588,7 @@ def attributes(self):
         SpanSemanticConvention,
         ResourceSemanticConvention,
         EventSemanticConvention,
+        MetricGroupSemanticConvention,
         MetricSemanticConvention,
         UnitSemanticConvention,
         ScopeSemanticConvention,

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,31 @@
+# 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 -->
+
+**`foo.active_eggs`**
+<!-- semconv metric.foo.active_eggs(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `foo.active_eggs` | UpDownCounter | `{cartons}` | Measures how many eggs are currently active. |
+<!-- endsemconv -->
+
+**Attributes for `foo.active_eggs`**
+<!-- semconv metric.foo.active_eggs -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `bar.egg.type` | string | Type of egg. | `chicken`; `emu`; `dragon` | Conditionally Required: if available to instrumentation. |
+| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Optional |
+<!-- endsemconv -->

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

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

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

@@ -0,0 +1,42 @@
+groups:
+  - id: metric.foo
+    prefix: bar
+    type: metric_group
+    brief: "This document defines foo."
+    note: >
+        Details about foo.
+    attributes: 
+      - id: egg.type
+        type: string
+        brief: 'Type of egg.'
+        examples: ["chicken", "emu", "dragon"]
+
+  - 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."
+
+  - id: metric.foo.active_eggs
+    prefix: foo
+    type: metric
+    extends: metric.foo
+    metric_name: foo.active_eggs
+    brief: "Measures how many eggs are currently active."
+    instrument: updowncounter
+    unit: "{cartons}"
+    attributes: 
+      - ref: http.method
+        requirement_level: optional
+      - ref: bar.egg.type
+        requirement_level: 
+          conditionally_required: "if available to instrumentation."