[mdatagen] Add test_metadata.yaml to generate sample code (open-telem…

…etry#16812)

This is needed to always have test coverage and visible result of all functionality available in the mdatagen tool, even if the functionality is not being used.

Makefile

@@ -243,6 +243,11 @@ generate:
  cd cmd/mdatagen && $(GOCMD) install .
  $(MAKE) for-all CMD="$(GOCMD) generate ./..."
 
+.PHONY: mdatagen-test
+mdatagen-test:
+ cd cmd/mdatagen && $(GOCMD) install .
+ cd cmd/mdatagen && $(GOCMD) generate ./...
+
 .PHONY: chlog-install
 chlog-install:
  cd $(TOOLS_MOD_DIR) && $(GOCMD) install go.opentelemetry.io/build-tools/chloggen

cmd/mdatagen/README.md

@@ -12,10 +12,25 @@ If adding a new receiver a `doc.go` file should also be added to trigger the gen
 
 ## Build
 
-When `go generate` is run (it is run automatically in the make build targets) there are a few special build directives in `doc.go` files:
+`make generate` triggers the following actions:
 
-* `make install-tools` results in `cmd/mdatagen` being installed to `GOBIN`
+1. `cd cmd/mdatagen && $(GOCMD) install .` to install `mdatagen` tool in`GOBIN`
 
-* `make generate` on root `opentelemetry-collector-contrib project` it will results in the code below
+2. All `go:generate mdatagen` directives that are usually defined in `doc.go` files of the metric scrapers will be 
+ executed. For example,
+ [/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/doc.go](../../receiver/hostmetricsreceiver/internal/scraper/cpuscraper/doc.go)
+ runs `mdatagen` for the [metadata.yaml](../../receiver/hostmetricsreceiver/internal/scraper/cpuscraper/metadata.yaml)
+ which generates the metrics builder code in
+ [internal/metadata](../../receiver/hostmetricsreceiver/internal/scraper/cpuscraper/internal/metadata)
+ and [documentation.md](../../receiver/hostmetricsreceiver/internal/scraper/cpuscraper/internal/metadata) with
+ generated documentation about emitted metrics.
 
-[/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/doc.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/doc.go) runs `mdatagen` for the `hostmetricsreceiver` metadata.yaml which generates the [/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/internal/metadata](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/internal/metadata) package which has Go files containing metric and label metadata.
+## Development
+
+In order to introduce support of a new functionality in metadata.yaml:
+
+1. Make code changes in the (generating code)[./loader.test] and (templates)[./templates/].
+2. Add usage of the new functionality in (metadata.yaml)[./metadata.yaml].
+3. Run `make mdatagen-test`.
+4. Make sure all tests are passing including (generated tests)[./internal/metadata/generated_metrics_test.go].
+5. Run `make generate`.

cmd/mdatagen/doc.go

@@ -0,0 +1,18 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http:https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Generate a test metrics builder from a sample metrics set covering all configuration options.
+//go:generate mdatagen metadata.yaml
+
+package main

cmd/mdatagen/documentation.md

@@ -0,0 +1,63 @@
+[comment]: <> (Code generated by mdatagen. DO NOT EDIT.)
+
+# testreceiver
+
+## Default Metrics
+
+The following metrics are emitted by default. Each of them can be disabled by applying the following configuration:
+
+```yaml
+metrics:
+ <metric_name>:
+ enabled: false
+```
+
+### default.metric
+
+Monotonic cumulative sum int metric enabled by default.
+
+Additional information.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| s | Sum | Int | Cumulative | true |
+
+#### Attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| string_attr | Attribute with any string value. | Any Str |
+| state | Integer attribute with overridden name. | Any Int |
+| enum_attr | Attribute with a known set of string values. | Str: ``red``, ``green``, ``blue`` |
+
+## Optional Metrics
+
+The following metrics are not emitted by default. Each of them can be enabled by applying the following configuration:
+
+```yaml
+metrics:
+ <metric_name>:
+ enabled: true
+```
+
+### optional.metric
+
+[DEPRECATED] Gauge double metric disabled by default.
+
+| Unit | Metric Type | Value Type |
+| ---- | ----------- | ---------- |
+| 1 | Gauge | Double |
+
+#### Attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| string_attr | Attribute with any string value. | Any Str |
+| boolean_attr | Attribute with a boolean value. | Any Bool |
+
+## Resource Attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| string.enum.resource.attr | Resource attribute with a known set of string values. | Str: ``one``, ``two`` |
+| string.resource.attr | Resource attribute with any string value. | Any Str |

cmd/mdatagen/go.mod

@@ -4,9 +4,12 @@ go 1.18
 
 require (
  github.com/stretchr/testify v1.8.1
+ go.opentelemetry.io/collector/component v0.66.1-0.20221202005155-1c54042beb70
  go.opentelemetry.io/collector/confmap v0.0.0-20221201172708-2bdff61fa52a
  go.opentelemetry.io/collector/pdata v0.66.1-0.20221202005155-1c54042beb70
+ go.opentelemetry.io/collector/semconv v0.66.1-0.20221202005155-1c54042beb70
  go.uber.org/multierr v1.8.0
+ go.uber.org/zap v1.24.0
 )
 
 require (
@@ -25,7 +28,12 @@ require (
  github.com/pelletier/go-toml v1.9.4 // indirect
  github.com/pmezard/go-difflib v1.0.0 // indirect
  github.com/rogpeppe/go-internal v1.8.0 // indirect
+ go.opentelemetry.io/collector v0.66.1-0.20221202005155-1c54042beb70 // indirect
+ go.opentelemetry.io/collector/consumer v0.66.1-0.20221202005155-1c54042beb70 // indirect
  go.opentelemetry.io/collector/featuregate v0.66.1-0.20221202005155-1c54042beb70 // indirect
+ go.opentelemetry.io/otel v1.11.1 // indirect
+ go.opentelemetry.io/otel/metric v0.33.0 // indirect
+ go.opentelemetry.io/otel/trace v1.11.1 // indirect
  go.uber.org/atomic v1.10.0 // indirect
  golang.org/x/net v0.0.0-20220722155237-a158d28d115b // indirect
  golang.org/x/sys v0.2.0 // indirect