You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Implements automatic documentation generation for component feature gates
via mdatagen, addressing issue #14067.
Changes:
- Extended metadata-schema.yaml with feature_gates section
- Added FeatureGate types and validation to metadata.go
- Created documentation template for feature gates
- Integrated into documentation generation pipeline
- Added test data and test cases
- Updated README with usage examples
All tests passing (282 tests) and lint checks clean.
Signed-off-by: SACHIN <[email protected]>
Every component's documentation should include a brief description of the component and guidance on how to use it.
14
16
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.
15
17
Examples of this metadata about a component are:
16
18
17
-
* its stability level
18
-
* the distributions containing it
19
-
* the types of pipelines it supports
20
-
* metrics emitted in the case of a scraping receiver, a scraper, or a connector
19
+
- its stability level
20
+
- the distributions containing it
21
+
- the types of pipelines it supports
22
+
- metrics emitted in the case of a scraping receiver, a scraper, or a connector
21
23
22
24
The metadata generator defines a schema for specifying this information to ensure it is complete and well-formed.
23
25
The metadata generator is then able to ingest the metadata, validate it against the schema and produce documentation in a standardized format.
@@ -26,10 +28,12 @@ An example of how this generated documentation looks can be found in [documentat
26
28
## Using the Metadata Generator
27
29
28
30
In order for a component to benefit from the metadata generator (`mdatagen`) these requirements need to be met:
31
+
29
32
1. A yaml file containing the metadata that needs to be included in the component
30
33
2. The component should declare a `go:generate mdatagen` directive which tells `mdatagen` what to generate
31
34
32
35
As an example, here is a minimal `metadata.yaml` for the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver):
36
+
33
37
```yaml
34
38
type: otlp
35
39
status:
@@ -42,6 +46,7 @@ status:
42
46
Detailed information about the schema of `metadata.yaml` can be found in [metadata-schema.yaml](./metadata-schema.yaml).
43
47
44
48
The `go:generate mdatagen` directive is usually defined in a `doc.go` file in the same package as the component, for example:
49
+
45
50
```go
46
51
//go:generate mdatagen metadata.yaml
47
52
@@ -50,11 +55,48 @@ package main
50
55
51
56
Below are some more examples that can be used for reference:
52
57
53
-
* The ElasticSearch receiver has an extensive [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/elasticsearchreceiver/metadata.yaml)
54
-
* The host metrics receiver has internal subcomponents, each with their own `metadata.yaml` and `doc.go`. See [cpuscraper](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver/internal/scraper/cpuscraper) for example.
58
+
-The ElasticSearch receiver has an extensive [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/elasticsearchreceiver/metadata.yaml)
59
+
-The host metrics receiver has internal subcomponents, each with their own `metadata.yaml` and `doc.go`. See [cpuscraper](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver/internal/scraper/cpuscraper) for example.
55
60
56
61
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.
57
62
63
+
### Feature Gates Documentation
64
+
65
+
The metadata generator supports automatic documentation generation for feature gates used by components. Feature gates are documented by adding a `feature_gates` section to your `metadata.yaml`:
66
+
67
+
```yaml
68
+
type: mycomponent
69
+
status:
70
+
class: receiver
71
+
stability:
72
+
beta: [metrics, traces]
73
+
74
+
feature_gates:
75
+
mycomponent.newFeature:
76
+
description: 'Enables new feature functionality that improves performance'
This will generate a "Feature Gates" section in the component's `documentation.md` file with a table containing:
90
+
91
+
- **Feature Gate**: The gate identifier
92
+
- **Stage**: The lifecycle stage (alpha, beta, stable, deprecated)
93
+
- **Description**: Brief description of what the gate controls
94
+
- **From Version**: Version when the gate was introduced
95
+
- **To Version**: Version when stable/deprecated gates will be removed (if applicable)
96
+
- **Reference**: Link to additional contextual information
97
+
98
+
The feature gate definitions should correspond to actual gates registered in your component code using the [Feature Gates API](../../featuregate/README.md).
99
+
58
100
### Generate multiple metadata packages
59
101
60
102
By default, `mdatagen` will generate a package called `metadata` in the `internal` directory. If you want to generate a package with a different name, you can use the `generated_package_name` configuration field to provide an alternate name.
iflen(md.Metrics) !=0||len(md.Telemetry.Metrics) !=0||len(md.ResourceAttributes) !=0||len(md.Events) !=0 { // if there's metrics or internal metrics or events, generate documentation for them
175
+
iflen(md.Metrics) !=0||len(md.Telemetry.Metrics) !=0||len(md.ResourceAttributes) !=0||len(md.Events) !=0||len(md.FeatureGates) !=0{ // if there's metrics or internal metrics or events or feature gates, generate documentation for them
| `{{ $gateID }}` | {{ $gate.Stage }} | {{ $gate.Description }} | {{ if $gate.FromVersion }}{{ $gate.FromVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ToVersion }}{{ $gate.ToVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ReferenceURL }}[Link]({{ $gate.ReferenceURL }}){{ else }}N/A{{ end }} |
278
+
{{- end }}
279
+
280
+
For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.
| `{{ $gateID }}` | {{ $gate.Stage }} | {{ $gate.Description }} | {{ if $gate.FromVersion }}{{ $gate.FromVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ToVersion }}{{ $gate.ToVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ReferenceURL }}[Link]({{ $gate.ReferenceURL }}){{ else }}N/A{{ end }} |
11
+
{{- end }}
12
+
13
+
For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.
|`sample.feature.gate`| alpha | This is a sample feature gate for testing purposes | v0.100.0 | N/A |[Link](https://github.com/open-telemetry/opentelemetry-collector/issues/12345)|
12
+
|`stable.feature.gate`| stable | This is a stable feature gate | v0.90.0 | v0.95.0 |[Link](https://github.com/open-telemetry/opentelemetry-collector/issues/11111)|
13
+
14
+
For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.
0 commit comments