From ea3aaa5ddc9c2601455fe0e630886f8934dbfdcd Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Tue, 30 May 2023 20:26:37 +0200 Subject: [PATCH 01/10] Start adding the status information to the metadata schema documentation --- cmd/mdatagen/README.md | 2 +- ...{metric-metadata.yaml => metadata-schema.yaml} | 15 +++++++++++++-- cmd/mdatagen/metadata.yaml | 7 ++++++- 3 files changed, 20 insertions(+), 4 deletions(-) rename cmd/mdatagen/{metric-metadata.yaml => metadata-schema.yaml} (79%) diff --git a/cmd/mdatagen/README.md b/cmd/mdatagen/README.md index 49f6bd39b61d..635e8c49b856 100644 --- a/cmd/mdatagen/README.md +++ b/cmd/mdatagen/README.md @@ -11,7 +11,7 @@ Current examples: * hostmetricsreceiver scrapers like the [cpuscraper](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/metadata.yaml) -See [metric-metadata.yaml](metric-metadata.yaml) for file format documentation. +See [metadata-schema.yaml](metadata-schema.yaml) for file format documentation. If adding a new receiver a `doc.go` file should also be added to trigger the generation. See below for details. diff --git a/cmd/mdatagen/metric-metadata.yaml b/cmd/mdatagen/metadata-schema.yaml similarity index 79% rename from cmd/mdatagen/metric-metadata.yaml rename to cmd/mdatagen/metadata-schema.yaml index 08f2f62ffe2c..88d5cfa7e9b3 100644 --- a/cmd/mdatagen/metric-metadata.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -1,6 +1,17 @@ -# Required: type of the receiver. +# Required: The type of the component. type: +# Required: A high-level view of the development status and use of this component +status: + # Required: The class of the component (For example receiver) + class: + # Required: The stability of the component - See https://github.com/open-telemetry/opentelemetry-collector#stability-levels + stability: + # Optional: The distributions that this component is bundled with (For example core or contrib) + distributions: []string + # Optional: A list of warnings that should be brought to the attention of developers looking to use this component + warnings: []string + # Optional: OTel Semantic Conventions version that will be associated with the scraped metrics. # This attribute should be set for metrics compliant with OTel Semantic Conventions. sem_conv_version: 1.9.0 @@ -31,7 +42,7 @@ attributes: # Required: attribute value type. type: -# Required: map of metric names with the key being the metric name and value +# Optional: map of metric names with the key being the metric name and value # being described below. metrics: : diff --git a/cmd/mdatagen/metadata.yaml b/cmd/mdatagen/metadata.yaml index d4dfe7cd3461..16b510240770 100644 --- a/cmd/mdatagen/metadata.yaml +++ b/cmd/mdatagen/metadata.yaml @@ -7,7 +7,12 @@ sem_conv_version: 1.9.0 status: class: receiver stability: - development: [metrics] + development: [logs] + beta: [traces] + stable: [metrics] + distributions: [contrib] + warnings: + - Any additonal information that should be brought to the consumer's attention resource_attributes: string.resource.attr: From dc15a1d1954639229439c6f81caa860b947140dd Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Tue, 30 May 2023 20:43:52 +0200 Subject: [PATCH 02/10] Remove cmd from the list of possible classes --- cmd/mdatagen/metadata-schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/mdatagen/metadata-schema.yaml b/cmd/mdatagen/metadata-schema.yaml index 88d5cfa7e9b3..f6d8fa093db1 100644 --- a/cmd/mdatagen/metadata-schema.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -4,7 +4,7 @@ type: # Required: A high-level view of the development status and use of this component status: # Required: The class of the component (For example receiver) - class: + class: # Required: The stability of the component - See https://github.com/open-telemetry/opentelemetry-collector#stability-levels stability: # Optional: The distributions that this component is bundled with (For example core or contrib) From 5de65ad49eea35862dd306bfca1c6d71d7a19e66 Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Tue, 30 May 2023 20:44:37 +0200 Subject: [PATCH 03/10] Fix spelling mistake Co-authored-by: Antoine Toulme --- cmd/mdatagen/metadata.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/mdatagen/metadata.yaml b/cmd/mdatagen/metadata.yaml index 16b510240770..4316c4a892bf 100644 --- a/cmd/mdatagen/metadata.yaml +++ b/cmd/mdatagen/metadata.yaml @@ -12,7 +12,7 @@ status: stable: [metrics] distributions: [contrib] warnings: - - Any additonal information that should be brought to the consumer's attention + - Any additional information that should be brought to the consumer's attention resource_attributes: string.resource.attr: From 5e4413fd98e3b2bc9469fc7cff2e85c38a411728 Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Tue, 30 May 2023 21:23:13 +0200 Subject: [PATCH 04/10] Update the value used for the development stability status Co-authored-by: Antoine Toulme --- cmd/mdatagen/metadata-schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/mdatagen/metadata-schema.yaml b/cmd/mdatagen/metadata-schema.yaml index f6d8fa093db1..f6f2a7e6abd2 100644 --- a/cmd/mdatagen/metadata-schema.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -6,7 +6,7 @@ status: # Required: The class of the component (For example receiver) class: # Required: The stability of the component - See https://github.com/open-telemetry/opentelemetry-collector#stability-levels - stability: + stability: # Optional: The distributions that this component is bundled with (For example core or contrib) distributions: []string # Optional: A list of warnings that should be brought to the attention of developers looking to use this component From 17da70f6350355254463ac2bed5a913a25a6d889 Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Fri, 2 Jun 2023 12:33:24 +0200 Subject: [PATCH 05/10] Fix the tests after updating the example metadata file --- .../internal/metadata/generated_status.go | 4 +++- cmd/mdatagen/loader_test.go | 16 ++++++++++------ 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/cmd/mdatagen/internal/metadata/generated_status.go b/cmd/mdatagen/internal/metadata/generated_status.go index 4d81725d0f92..d01939e96a40 100644 --- a/cmd/mdatagen/internal/metadata/generated_status.go +++ b/cmd/mdatagen/internal/metadata/generated_status.go @@ -8,5 +8,7 @@ import ( const ( Type = "test" - MetricsStability = component.StabilityLevelDevelopment + TracesStability = component.StabilityLevelBeta + LogsStability = component.StabilityLevelDevelopment + MetricsStability = component.StabilityLevelStable ) diff --git a/cmd/mdatagen/loader_test.go b/cmd/mdatagen/loader_test.go index 247259bf7b60..659b65489ecd 100644 --- a/cmd/mdatagen/loader_test.go +++ b/cmd/mdatagen/loader_test.go @@ -22,6 +22,16 @@ func Test_loadMetadata(t *testing.T) { want: metadata{ Type: "test", SemConvVersion: "1.9.0", + Status: &Status{ + Class: "receiver", + Stability: map[string][]string{ + "development": {"logs"}, + "beta": {"traces"}, + "stable": {"metrics"}, + }, + Distributions: []string{"contrib"}, + Warnings: []string{"Any additional information that should be brought to the consumer's attention"}, + }, ResourceAttributes: map[attributeName]attribute{ "string.resource.attr": { Description: "Resource attribute with any string value.", @@ -146,12 +156,6 @@ func Test_loadMetadata(t *testing.T) { }, }, ScopeName: "otelcol", - Status: &Status{ - Class: "receiver", - Stability: map[string][]string{ - "development": {"metrics"}, - }, - }, }, }, { From 137ab317fb47de0bb3c2d02105a1b380b9f89ae5 Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Fri, 2 Jun 2023 12:35:48 +0200 Subject: [PATCH 06/10] Document how to use mdatagen and the schema of metadata.yaml --- cmd/mdatagen/README.md | 60 +++++++++++++++++++------------ cmd/mdatagen/metadata-schema.yaml | 30 +++++++++------- 2 files changed, 55 insertions(+), 35 deletions(-) diff --git a/cmd/mdatagen/README.md b/cmd/mdatagen/README.md index 635e8c49b856..0ca79053de8d 100644 --- a/cmd/mdatagen/README.md +++ b/cmd/mdatagen/README.md @@ -1,42 +1,56 @@ # Metadata Generator -Components must contain a `metadata.yaml` file that documents various aspects of the component including: +Every component's documentation should include a brief description of the component and guidance on how to use it. +There is also some information about the component (or metadata) that should be included to help end-users understand the current state of the component and whether it is right for their use case. +Examples of this metadata about a component are: * its stability level * the distributions containing it * the types of pipelines it supports * metrics emitted in the case of a scraping receiver -Current examples: +The metadata generator defines a schema for specifying this information to ensure it is complete and well-formed. +The metadata generator is then able to ingest the metadata, validate it against the schema and produce documentation in a standardized format. +An example of how this generated documentation looks can be found in [documentation.md](./documentation.md). -* hostmetricsreceiver scrapers like the [cpuscraper](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/metadata.yaml) +## Using the Metadata Generator -See [metadata-schema.yaml](metadata-schema.yaml) for file format documentation. +In order for a component to benefit from the metadata generator (`mdatagen`) these requirements need to be met: +1. A `metadata.yaml` file containing the metadata needs to be included in the component +2. The component should declare a `go:generate mdatagen` directive which tells `mdatagen` what to generate -If adding a new receiver a `doc.go` file should also be added to trigger the generation. See below for details. +As an example, here is a minimal `metadata.yaml` for the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver): +```yaml +type: otlp +status: + class: receiver + stability: + beta: [logs] + stable: [metrics, traces] +``` -## Generating +Detailed information about the schema of `metadata.yaml` can be found in [metadata-schema.yaml](./metadata-schema.yaml). -`make generate` triggers the following actions: +The `go:generate mdatagen` directive is usually defined in a `doc.go` file in the same package as the component, for example: +```go +//go:generate mdatagen metadata.yaml -1. `cd cmd/mdatagen && $(GOCMD) install .` to install `mdatagen` tool in`GOBIN` +package main +``` -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. +Below are some more examples that can be used for reference: -## Development +* The ElasticSearch receiver has an extensive [metadata.yaml](../../receiver/elasticsearchreceiver/metadata.yaml) +* The host metrics receiver has internal subcomponents, each with their own `metadata.yaml` and `doc.go`. See [cpuscraper](../../receiver/hostmetricsreceiver/internal/scraper/cpuscraper) for example. -In order to introduce support of a new functionality in metadata.yaml: +You can run `cd cmd/mdatagen && $(GOCMD) install .` to install the `mdatagen` tool in `GOBIN` and then run `mdatagen metadata.yaml` to generate documentation for a specific component or you can run `make generate` to generate documentation for all components. -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`. +## Contributing to the Metadata Generator +The code for generating the documentation can be found in [loader.go](./loader.go) and the templates for rendering the documentation can be found in [templates](./templates). +When making updates to the metadata generator or introducing support for new functionality: + +1. Ensure the [metadata-schema.yaml](./metadata-schema.yaml) and [./metadata.yaml](metadata.yaml) files reflect the changes. +2. Run `make mdatagen-test`. +3. Make sure all tests are passing including [generated tests](./internal/metadata/generated_metrics_test.go). +4. Run `make generate`. diff --git a/cmd/mdatagen/metadata-schema.yaml b/cmd/mdatagen/metadata-schema.yaml index f6f2a7e6abd2..1c7fb28553b2 100644 --- a/cmd/mdatagen/metadata-schema.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -1,15 +1,21 @@ -# Required: The type of the component. +# Required: The type of the component - Usually the name. The type and class combined uniquely identify the component (eg. receiver/otlp) or subcomponent (eg. receiver/hostmetricsreceiver/cpu) type: -# Required: A high-level view of the development status and use of this component +# Required for components (Optional for subcomponents): A high-level view of the development status and use of this component status: # Required: The class of the component (For example receiver) class: # Required: The stability of the component - See https://github.com/open-telemetry/opentelemetry-collector#stability-levels - stability: - # Optional: The distributions that this component is bundled with (For example core or contrib) + stability: + development: [] + alpha: [] + beta: [] + stable: [] + deprecated: [] + unmaintained: [] + # Optional: The distributions that this component is bundled with (For example core or contrib). See statusdata.go for a list of common distros. distributions: []string - # Optional: A list of warnings that should be brought to the attention of developers looking to use this component + # Optional: A list of warnings that should be brought to the attention of users looking to use this component warnings: []string # Optional: OTel Semantic Conventions version that will be associated with the scraped metrics. @@ -24,7 +30,7 @@ resource_attributes: # Required: description of the attribute. description: # Optional: array of attribute values if they are static values (currently, only string type is supported). - enum: + enum: []string # Required: attribute value type. type: @@ -38,7 +44,7 @@ attributes: # Required: description of the attribute. description: # Optional: array of attribute values if they are static values (currently, only string type is supported). - enum: + enum: []string # Required: attribute value type. type: @@ -47,7 +53,7 @@ attributes: metrics: : # Required: whether the metric is collected by default. - enabled: # true | false + enabled: bool # Required: metric description. description: # Optional: extended documentation of the metric. @@ -68,11 +74,11 @@ metrics: # Required: metric type with its settings. : # Required for sum and gauge metrics: type of number data point values. - value_type: # int | double + value_type: # Required for sum metric: whether the metric is monotonic (no negative delta values). - monotonic: # true | false + monotonic: bool # Required for sum metric: whether reported values incorporate previous measurements # (cumulative) or not (delta). - aggregation: # delta | cumulative + aggregation: # Optional: array of attributes that were defined in the attributes section that are emitted by this metric. - attributes: + attributes: []string From 9c55cdbbfdb2b17017ecce0c678cb282ac2d5877 Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Mon, 5 Jun 2023 09:21:02 +0200 Subject: [PATCH 07/10] Add the stability levels for connectors --- cmd/mdatagen/metadata-schema.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/cmd/mdatagen/metadata-schema.yaml b/cmd/mdatagen/metadata-schema.yaml index 1c7fb28553b2..d6ec4ba5ddf2 100644 --- a/cmd/mdatagen/metadata-schema.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -7,12 +7,12 @@ status: class: # Required: The stability of the component - See https://github.com/open-telemetry/opentelemetry-collector#stability-levels stability: - development: [] - alpha: [] - beta: [] - stable: [] - deprecated: [] - unmaintained: [] + development: [] + alpha: [] + beta: [] + stable: [] + deprecated: [] + unmaintained: [] # Optional: The distributions that this component is bundled with (For example core or contrib). See statusdata.go for a list of common distros. distributions: []string # Optional: A list of warnings that should be brought to the attention of users looking to use this component From f87199c40682ab67813f045e04a4f1e8db4fcf3f Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Mon, 5 Jun 2023 12:39:13 +0200 Subject: [PATCH 08/10] Change the receiver type so the tests pass --- cmd/mdatagen/loader_test.go | 2 +- cmd/mdatagen/metadata.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/cmd/mdatagen/loader_test.go b/cmd/mdatagen/loader_test.go index 659b65489ecd..8fca2f8e432e 100644 --- a/cmd/mdatagen/loader_test.go +++ b/cmd/mdatagen/loader_test.go @@ -20,7 +20,7 @@ func Test_loadMetadata(t *testing.T) { { name: "metadata.yaml", want: metadata{ - Type: "test", + Type: "file", SemConvVersion: "1.9.0", Status: &Status{ Class: "receiver", diff --git a/cmd/mdatagen/metadata.yaml b/cmd/mdatagen/metadata.yaml index 4316c4a892bf..054ca3824143 100644 --- a/cmd/mdatagen/metadata.yaml +++ b/cmd/mdatagen/metadata.yaml @@ -1,6 +1,6 @@ # Sample metric metadata file with all available configurations. -type: test +type: file sem_conv_version: 1.9.0 From c5d92a60393ef77d8cd30c71d0129bd260bef7bf Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Mon, 5 Jun 2023 13:33:54 +0200 Subject: [PATCH 09/10] Update the generated documentation --- cmd/mdatagen/documentation.md | 2 +- cmd/mdatagen/internal/metadata/generated_config.go | 6 +++--- cmd/mdatagen/internal/metadata/generated_status.go | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/cmd/mdatagen/documentation.md b/cmd/mdatagen/documentation.md index 358512be86f2..4c649fea8320 100644 --- a/cmd/mdatagen/documentation.md +++ b/cmd/mdatagen/documentation.md @@ -1,6 +1,6 @@ [comment]: <> (Code generated by mdatagen. DO NOT EDIT.) -# test +# file ## Default Metrics diff --git a/cmd/mdatagen/internal/metadata/generated_config.go b/cmd/mdatagen/internal/metadata/generated_config.go index ff93bcb4ce55..973c02069f4a 100644 --- a/cmd/mdatagen/internal/metadata/generated_config.go +++ b/cmd/mdatagen/internal/metadata/generated_config.go @@ -23,7 +23,7 @@ func (ms *MetricConfig) Unmarshal(parser *confmap.Conf) error { return nil } -// MetricsConfig provides config for test metrics. +// MetricsConfig provides config for file metrics. type MetricsConfig struct { DefaultMetric MetricConfig `mapstructure:"default.metric"` DefaultMetricToBeRemoved MetricConfig `mapstructure:"default.metric.to_be_removed"` @@ -49,7 +49,7 @@ type ResourceAttributeConfig struct { Enabled bool `mapstructure:"enabled"` } -// ResourceAttributesConfig provides config for test resource attributes. +// ResourceAttributesConfig provides config for file resource attributes. type ResourceAttributesConfig struct { MapResourceAttr ResourceAttributeConfig `mapstructure:"map.resource.attr"` OptionalResourceAttr ResourceAttributeConfig `mapstructure:"optional.resource.attr"` @@ -78,7 +78,7 @@ func DefaultResourceAttributesConfig() ResourceAttributesConfig { } } -// MetricsBuilderConfig is a configuration for test metrics builder. +// MetricsBuilderConfig is a configuration for file metrics builder. type MetricsBuilderConfig struct { Metrics MetricsConfig `mapstructure:"metrics"` ResourceAttributes ResourceAttributesConfig `mapstructure:"resource_attributes"` diff --git a/cmd/mdatagen/internal/metadata/generated_status.go b/cmd/mdatagen/internal/metadata/generated_status.go index d01939e96a40..e9ab937c5055 100644 --- a/cmd/mdatagen/internal/metadata/generated_status.go +++ b/cmd/mdatagen/internal/metadata/generated_status.go @@ -7,7 +7,7 @@ import ( ) const ( - Type = "test" + Type = "file" TracesStability = component.StabilityLevelBeta LogsStability = component.StabilityLevelDevelopment MetricsStability = component.StabilityLevelStable From 8b6324f119a904b3d75eee2f9d9d5944ae9e2249 Mon Sep 17 00:00:00 2001 From: Dewald de Jager Date: Tue, 6 Jun 2023 15:46:02 +0200 Subject: [PATCH 10/10] Change the syntax used for string array types so that it is valid YAML --- cmd/mdatagen/metadata-schema.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cmd/mdatagen/metadata-schema.yaml b/cmd/mdatagen/metadata-schema.yaml index d6ec4ba5ddf2..b3c5444ab6ad 100644 --- a/cmd/mdatagen/metadata-schema.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -14,9 +14,9 @@ status: deprecated: [] unmaintained: [] # Optional: The distributions that this component is bundled with (For example core or contrib). See statusdata.go for a list of common distros. - distributions: []string + distributions: [string] # Optional: A list of warnings that should be brought to the attention of users looking to use this component - warnings: []string + warnings: [string] # Optional: OTel Semantic Conventions version that will be associated with the scraped metrics. # This attribute should be set for metrics compliant with OTel Semantic Conventions. @@ -30,7 +30,7 @@ resource_attributes: # Required: description of the attribute. description: # Optional: array of attribute values if they are static values (currently, only string type is supported). - enum: []string + enum: [string] # Required: attribute value type. type: @@ -44,7 +44,7 @@ attributes: # Required: description of the attribute. description: # Optional: array of attribute values if they are static values (currently, only string type is supported). - enum: []string + enum: [string] # Required: attribute value type. type: @@ -81,4 +81,4 @@ metrics: # (cumulative) or not (delta). aggregation: # Optional: array of attributes that were defined in the attributes section that are emitted by this metric. - attributes: []string + attributes: [string]