diff --git a/cmd/mdatagen/internal/loader_test.go b/cmd/mdatagen/internal/loader_test.go index e5b8afbd741..bd1d2604878 100644 --- a/cmd/mdatagen/internal/loader_test.go +++ b/cmd/mdatagen/internal/loader_test.go @@ -448,6 +448,42 @@ func TestLoadMetadata(t *testing.T) { }, ScopeName: "go.opentelemetry.io/collector/internal/receiver/samplereceiver", ShortFolderName: "sample", + ExampleConfigs: []ExampleConfig{ + { + Name: "Basic Configuration", + Description: "This example demonstrates the most basic configuration for the sample receiver with default settings.", + Config: `sample: + metrics: + default.metric: + enabled: true +`, + }, + { + Name: "Advanced Configuration", + Description: "This example shows an advanced configuration with custom metrics enabled and resource attributes configured.", + Config: `sample: + metrics: + default.metric: + enabled: true + optional.metric: + enabled: true + resource_attributes: + string.resource.attr: + enabled: true + optional.resource.attr: + enabled: true +`, + }, + { + Name: "Minimal Configuration", + Description: "A minimal configuration suitable for testing environments with only essential metrics.", + Config: `sample: + metrics: + metric.input_type: + enabled: true +`, + }, + }, Tests: Tests{Host: "newMdatagenNopHost()"}, }, }, diff --git a/cmd/mdatagen/internal/metadata.go b/cmd/mdatagen/internal/metadata.go index d5355273e72..d55ea3ae94d 100644 --- a/cmd/mdatagen/internal/metadata.go +++ b/cmd/mdatagen/internal/metadata.go @@ -44,6 +44,8 @@ type Metadata struct { ScopeName string `mapstructure:"scope_name"` // ShortFolderName is the shortened folder name of the component, removing class if present ShortFolderName string `mapstructure:"-"` + // ExampleConfigs are example configuration snippets for the component. + ExampleConfigs []ExampleConfig `mapstructure:"example_configs"` // Tests is the set of tests generated with the component Tests Tests `mapstructure:"tests"` // PackageName is the name of the package where the component is defined. @@ -521,3 +523,12 @@ type EntityAttributeRef struct { // Ref is the reference to a resource attribute. Ref AttributeName `mapstructure:"ref"` } + +type ExampleConfig struct { + // Name is a descriptive name for the example configuration. + Name string `mapstructure:"name"` + // Description provides context about when this configuration should be used. + Description string `mapstructure:"description"` + // Config is the example configuration snippet in YAML format. + Config string `mapstructure:"config"` +} diff --git a/cmd/mdatagen/internal/sampleconnector/generated_component_test.go b/cmd/mdatagen/internal/sampleconnector/generated_component_test.go index 08dde142959..d97d2ee1944 100644 --- a/cmd/mdatagen/internal/sampleconnector/generated_component_test.go +++ b/cmd/mdatagen/internal/sampleconnector/generated_component_test.go @@ -8,7 +8,6 @@ import ( "testing" "github.com/stretchr/testify/require" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/component/componenttest" "go.opentelemetry.io/collector/confmap/confmaptest" diff --git a/cmd/mdatagen/internal/sampleconnector/generated_package_test.go b/cmd/mdatagen/internal/sampleconnector/generated_package_test.go index 22b159e0fec..05823a52b62 100644 --- a/cmd/mdatagen/internal/sampleconnector/generated_package_test.go +++ b/cmd/mdatagen/internal/sampleconnector/generated_package_test.go @@ -3,9 +3,8 @@ package sampleconnector import ( - "testing" - "go.uber.org/goleak" + "testing" ) func TestMain(m *testing.M) { diff --git a/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics.go b/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics.go index 475e719db5c..cd714c28cd5 100644 --- a/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics.go +++ b/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics.go @@ -7,13 +7,12 @@ import ( "strconv" "time" - conventions "go.opentelemetry.io/otel/semconv/v1.9.0" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/connector" "go.opentelemetry.io/collector/filter" "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/pmetric" + conventions "go.opentelemetry.io/otel/semconv/v1.9.0" ) // AttributeEnumAttr specifies the value enum_attr attribute. diff --git a/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics_test.go b/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics_test.go index 32e55353c2c..6c8b0322a74 100644 --- a/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics_test.go +++ b/cmd/mdatagen/internal/sampleconnector/internal/metadata/generated_metrics_test.go @@ -6,12 +6,11 @@ import ( "testing" "github.com/stretchr/testify/assert" - "go.uber.org/zap" - "go.uber.org/zap/zaptest/observer" - "go.opentelemetry.io/collector/connector/connectortest" "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/pmetric" + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" ) type testDataSet int diff --git a/cmd/mdatagen/internal/samplefactoryreceiver/generated_component_test.go b/cmd/mdatagen/internal/samplefactoryreceiver/generated_component_test.go index 38cf1def51e..73d64b781aa 100644 --- a/cmd/mdatagen/internal/samplefactoryreceiver/generated_component_test.go +++ b/cmd/mdatagen/internal/samplefactoryreceiver/generated_component_test.go @@ -8,7 +8,6 @@ import ( "testing" "github.com/stretchr/testify/require" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/component/componenttest" "go.opentelemetry.io/collector/confmap/confmaptest" diff --git a/cmd/mdatagen/internal/samplefactoryreceiver/generated_package_test.go b/cmd/mdatagen/internal/samplefactoryreceiver/generated_package_test.go index 70c4b90fee3..7d5b7784376 100644 --- a/cmd/mdatagen/internal/samplefactoryreceiver/generated_package_test.go +++ b/cmd/mdatagen/internal/samplefactoryreceiver/generated_package_test.go @@ -3,9 +3,8 @@ package samplefactoryreceiver import ( - "testing" - "go.uber.org/goleak" + "testing" ) func TestMain(m *testing.M) { diff --git a/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs.go b/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs.go index 7510fb02b72..90b9107d28a 100644 --- a/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs.go +++ b/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs.go @@ -3,12 +3,11 @@ package metadata import ( - conventions "go.opentelemetry.io/otel/semconv/v1.9.0" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/plog" "go.opentelemetry.io/collector/receiver" + conventions "go.opentelemetry.io/otel/semconv/v1.9.0" ) // LogsBuilder provides an interface for scrapers to report logs while taking care of all the transformations diff --git a/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs_test.go b/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs_test.go index 1992e9c96bf..8bf5b84fbc5 100644 --- a/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs_test.go +++ b/cmd/mdatagen/internal/samplefactoryreceiver/internal/metadata/generated_logs_test.go @@ -3,16 +3,14 @@ package metadata import ( - "testing" - "time" - "github.com/stretchr/testify/assert" - "go.uber.org/zap" - "go.uber.org/zap/zaptest/observer" - "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/plog" "go.opentelemetry.io/collector/receiver/receivertest" + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" + "testing" + "time" ) func TestLogsBuilderAppendLogRecord(t *testing.T) { diff --git a/cmd/mdatagen/internal/sampleprocessor/generated_component_test.go b/cmd/mdatagen/internal/sampleprocessor/generated_component_test.go index 26bf0ad844a..7aac919bff1 100644 --- a/cmd/mdatagen/internal/sampleprocessor/generated_component_test.go +++ b/cmd/mdatagen/internal/sampleprocessor/generated_component_test.go @@ -9,7 +9,6 @@ import ( "time" "github.com/stretchr/testify/require" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/component/componenttest" "go.opentelemetry.io/collector/confmap/confmaptest" diff --git a/cmd/mdatagen/internal/sampleprocessor/generated_package_test.go b/cmd/mdatagen/internal/sampleprocessor/generated_package_test.go index 6abd0d88121..46ca93c316f 100644 --- a/cmd/mdatagen/internal/sampleprocessor/generated_package_test.go +++ b/cmd/mdatagen/internal/sampleprocessor/generated_package_test.go @@ -3,9 +3,8 @@ package sampleprocessor import ( - "testing" - "go.uber.org/goleak" + "testing" ) func TestMain(m *testing.M) { diff --git a/cmd/mdatagen/internal/sampleprocessor/internal/metadata/generated_config_test.go b/cmd/mdatagen/internal/sampleprocessor/internal/metadata/generated_config_test.go index 66f4d0ad959..6cd0d6575c6 100644 --- a/cmd/mdatagen/internal/sampleprocessor/internal/metadata/generated_config_test.go +++ b/cmd/mdatagen/internal/sampleprocessor/internal/metadata/generated_config_test.go @@ -9,7 +9,6 @@ import ( "github.com/google/go-cmp/cmp" "github.com/google/go-cmp/cmp/cmpopts" "github.com/stretchr/testify/require" - "go.opentelemetry.io/collector/confmap/confmaptest" ) diff --git a/cmd/mdatagen/internal/samplereceiver/documentation.md b/cmd/mdatagen/internal/samplereceiver/documentation.md index 25fa9c66b74..ced32b75ec5 100644 --- a/cmd/mdatagen/internal/samplereceiver/documentation.md +++ b/cmd/mdatagen/internal/samplereceiver/documentation.md @@ -2,6 +2,51 @@ # sample +## Example Configurations + +### Basic Configuration + +This example demonstrates the most basic configuration for the sample receiver with default settings. + +```yaml +sample: + metrics: + default.metric: + enabled: true + +``` + +### Advanced Configuration + +This example shows an advanced configuration with custom metrics enabled and resource attributes configured. + +```yaml +sample: + metrics: + default.metric: + enabled: true + optional.metric: + enabled: true + resource_attributes: + string.resource.attr: + enabled: true + optional.resource.attr: + enabled: true + +``` + +### Minimal Configuration + +A minimal configuration suitable for testing environments with only essential metrics. + +```yaml +sample: + metrics: + metric.input_type: + enabled: true + +``` + ## Default Metrics The following metrics are emitted by default. Each of them can be disabled by applying the following configuration: diff --git a/cmd/mdatagen/internal/samplereceiver/generated_component_test.go b/cmd/mdatagen/internal/samplereceiver/generated_component_test.go index 99fa261656c..51dd41ca74d 100644 --- a/cmd/mdatagen/internal/samplereceiver/generated_component_test.go +++ b/cmd/mdatagen/internal/samplereceiver/generated_component_test.go @@ -7,8 +7,9 @@ import ( "context" "testing" - "github.com/stretchr/testify/require" + "gopkg.in/yaml.v3" + "github.com/stretchr/testify/require" "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/component/componenttest" "go.opentelemetry.io/collector/confmap/confmaptest" @@ -101,3 +102,56 @@ func (mnh *mdatagenNopHost) GetExtensions() map[component.ID]component.Component func (mnh *mdatagenNopHost) GetFactory(_ component.Kind, _ component.Type) component.Factory { return nil } + +func TestExampleConfigs(t *testing.T) { + tests := []struct { + name string + config string + description string + }{ + { + name: "Basic Configuration", + description: "This example demonstrates the most basic configuration for the sample receiver with default settings.", + config: `sample: + metrics: + default.metric: + enabled: true +`, + }, + { + name: "Advanced Configuration", + description: "This example shows an advanced configuration with custom metrics enabled and resource attributes configured.", + config: `sample: + metrics: + default.metric: + enabled: true + optional.metric: + enabled: true + resource_attributes: + string.resource.attr: + enabled: true + optional.resource.attr: + enabled: true +`, + }, + { + name: "Minimal Configuration", + description: "A minimal configuration suitable for testing environments with only essential metrics.", + config: `sample: + metrics: + metric.input_type: + enabled: true +`, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Test that the example config is valid YAML + var config map[string]any + err := yaml.Unmarshal([]byte(tt.config), &config) + require.NoError(t, err, "Example config '%s' should be valid YAML: %s", tt.name, tt.description) + require.NotNil(t, config, "Example config '%s' should produce a non-nil config", tt.name) + }) + } +} diff --git a/cmd/mdatagen/internal/samplereceiver/generated_package_test.go b/cmd/mdatagen/internal/samplereceiver/generated_package_test.go index ba2afcd94ca..dd6c357391f 100644 --- a/cmd/mdatagen/internal/samplereceiver/generated_package_test.go +++ b/cmd/mdatagen/internal/samplereceiver/generated_package_test.go @@ -3,9 +3,8 @@ package samplereceiver import ( - "testing" - "go.uber.org/goleak" + "testing" ) func TestMain(m *testing.M) { diff --git a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs.go b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs.go index 965481b46ef..4d74ffc47b9 100644 --- a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs.go +++ b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs.go @@ -4,15 +4,13 @@ package metadata import ( "context" - - conventions "go.opentelemetry.io/otel/semconv/v1.37.0" - "go.opentelemetry.io/otel/trace" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/filter" "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/plog" "go.opentelemetry.io/collector/receiver" + conventions "go.opentelemetry.io/otel/semconv/v1.9.0" + "go.opentelemetry.io/otel/trace" ) type EventAttributeOption interface { diff --git a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs_test.go b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs_test.go index 6a4bc4709b2..2b49c981a1a 100644 --- a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs_test.go +++ b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_logs_test.go @@ -4,17 +4,15 @@ package metadata import ( "context" - "testing" - "time" - "github.com/stretchr/testify/assert" - "go.opentelemetry.io/otel/trace" - "go.uber.org/zap" - "go.uber.org/zap/zaptest/observer" - "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/plog" "go.opentelemetry.io/collector/receiver/receivertest" + "go.opentelemetry.io/otel/trace" + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" + "testing" + "time" ) type eventsTestDataSet int diff --git a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics.go b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics.go index a8fb3a631a4..bfe7b8c9f3a 100644 --- a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics.go +++ b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics.go @@ -7,13 +7,12 @@ import ( "strconv" "time" - conventions "go.opentelemetry.io/otel/semconv/v1.37.0" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/filter" "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/pmetric" "go.opentelemetry.io/collector/receiver" + conventions "go.opentelemetry.io/otel/semconv/v1.9.0" ) // AttributeEnumAttr specifies the value enum_attr attribute. diff --git a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics_test.go b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics_test.go index b0dc2ce98b1..d893da0bee3 100644 --- a/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics_test.go +++ b/cmd/mdatagen/internal/samplereceiver/internal/metadata/generated_metrics_test.go @@ -6,12 +6,11 @@ import ( "testing" "github.com/stretchr/testify/assert" - "go.uber.org/zap" - "go.uber.org/zap/zaptest/observer" - "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/pmetric" "go.opentelemetry.io/collector/receiver/receivertest" + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" ) type testDataSet int diff --git a/cmd/mdatagen/internal/samplereceiver/internal/metadatatest/generated_telemetrytest.go b/cmd/mdatagen/internal/samplereceiver/internal/metadatatest/generated_telemetrytest.go index 361a3643203..ee2848e02a3 100644 --- a/cmd/mdatagen/internal/samplereceiver/internal/metadatatest/generated_telemetrytest.go +++ b/cmd/mdatagen/internal/samplereceiver/internal/metadatatest/generated_telemetrytest.go @@ -6,13 +6,12 @@ import ( "testing" "github.com/stretchr/testify/require" - "go.opentelemetry.io/otel/sdk/metric/metricdata" - "go.opentelemetry.io/otel/sdk/metric/metricdata/metricdatatest" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/component/componenttest" "go.opentelemetry.io/collector/receiver" "go.opentelemetry.io/collector/receiver/receivertest" + "go.opentelemetry.io/otel/sdk/metric/metricdata" + "go.opentelemetry.io/otel/sdk/metric/metricdata/metricdatatest" ) func NewSettings(tt *componenttest.Telemetry) receiver.Settings { diff --git a/cmd/mdatagen/internal/samplereceiver/metadata.yaml b/cmd/mdatagen/internal/samplereceiver/metadata.yaml index c1ede02b02f..c08bd180384 100644 --- a/cmd/mdatagen/internal/samplereceiver/metadata.yaml +++ b/cmd/mdatagen/internal/samplereceiver/metadata.yaml @@ -6,6 +6,36 @@ github_project: open-telemetry/opentelemetry-collector sem_conv_version: 1.37.0 +example_configs: + - name: Basic Configuration + description: This example demonstrates the most basic configuration for the sample receiver with default settings. + config: | + sample: + metrics: + default.metric: + enabled: true + - name: Advanced Configuration + description: This example shows an advanced configuration with custom metrics enabled and resource attributes configured. + config: | + sample: + metrics: + default.metric: + enabled: true + optional.metric: + enabled: true + resource_attributes: + string.resource.attr: + enabled: true + optional.resource.attr: + enabled: true + - name: Minimal Configuration + description: A minimal configuration suitable for testing environments with only essential metrics. + config: | + sample: + metrics: + metric.input_type: + enabled: true + status: disable_codecov_badge: true class: receiver @@ -16,8 +46,8 @@ status: deprecated: [profiles] deprecation: profiles: - migration: "no migration needed" - date: "2025-02-05" + migration: 'no migration needed' + date: '2025-02-05' distributions: [] unsupported_platforms: [freebsd, illumos] codeowners: @@ -141,7 +171,7 @@ events: default.event.to_be_removed: enabled: true - description: "[DEPRECATED] Example to-be-removed event enabled by default." + description: '[DEPRECATED] Example to-be-removed event enabled by default.' extended_documentation: The event will be removed soon. warnings: if_enabled: This event is deprecated and will be removed soon. @@ -150,9 +180,10 @@ events: default.event.to_be_renamed: enabled: false - description: "[DEPRECATED] Example event disabled by default." + description: '[DEPRECATED] Example event disabled by default.' extended_documentation: The event will be renamed soon. - attributes: [string_attr, boolean_attr, boolean_attr2, conditional_string_attr] + attributes: + [string_attr, boolean_attr, boolean_attr2, conditional_string_attr] warnings: if_configured: This event is deprecated and will be renamed soon. @@ -184,7 +215,7 @@ metrics: default.metric.to_be_removed: enabled: true - description: "[DEPRECATED] Non-monotonic delta sum double metric enabled by default." + description: '[DEPRECATED] Non-monotonic delta sum double metric enabled by default.' extended_documentation: The metric will be removed soon. stability: level: deprecated @@ -212,22 +243,23 @@ metrics: optional.metric: enabled: false - description: "[DEPRECATED] Gauge double metric disabled by default." + description: '[DEPRECATED] Gauge double metric disabled by default.' stability: level: deprecated - unit: "1" + unit: '1' gauge: value_type: double - attributes: [string_attr, boolean_attr, boolean_attr2, conditional_string_attr] + attributes: + [string_attr, boolean_attr, boolean_attr2, conditional_string_attr] warnings: if_configured: This metric is deprecated and will be removed soon. optional.metric.empty_unit: enabled: false - description: "[DEPRECATED] Gauge double metric disabled by default." + description: '[DEPRECATED] Gauge double metric disabled by default.' stability: level: deprecated - unit: "" + unit: '' gauge: value_type: double attributes: [string_attr, boolean_attr] @@ -256,7 +288,7 @@ telemetry: level: deprecated from: v0.110.0 description: Number of times the batch was sent due to a size trigger - unit: "{times}" + unit: '{times}' sum: value_type: int monotonic: true @@ -275,7 +307,7 @@ telemetry: description: Queue capacity - sync gauge example. stability: level: development - unit: "{items}" + unit: '{items}' gauge: value_type: int queue_length: @@ -284,7 +316,7 @@ telemetry: level: alpha description: This metric is optional and therefore not initialized in NewTelemetryBuilder. extended_documentation: For example this metric only exists if feature A is enabled. - unit: "{items}" + unit: '{items}' optional: true gauge: async: true diff --git a/cmd/mdatagen/internal/samplescraper/documentation.md b/cmd/mdatagen/internal/samplescraper/documentation.md index ee027ef5138..81b87133955 100644 --- a/cmd/mdatagen/internal/samplescraper/documentation.md +++ b/cmd/mdatagen/internal/samplescraper/documentation.md @@ -2,6 +2,18 @@ # sample +## Example Configurations + +### Default Configuration + +Basic configuration for the sample scraper with default metrics enabled. + +```yaml +sample: + collection_interval: 30s + +``` + ## Default Metrics The following metrics are emitted by default. Each of them can be disabled by applying the following configuration: diff --git a/cmd/mdatagen/internal/samplescraper/generated_component_test.go b/cmd/mdatagen/internal/samplescraper/generated_component_test.go index bfa30b0c4cc..bb9005e2e8e 100644 --- a/cmd/mdatagen/internal/samplescraper/generated_component_test.go +++ b/cmd/mdatagen/internal/samplescraper/generated_component_test.go @@ -7,8 +7,9 @@ import ( "context" "testing" - "github.com/stretchr/testify/require" + "gopkg.in/yaml.v3" + "github.com/stretchr/testify/require" "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/component/componenttest" "go.opentelemetry.io/collector/confmap/confmaptest" @@ -93,3 +94,29 @@ func (mnh *mdatagenNopHost) GetExtensions() map[component.ID]component.Component func (mnh *mdatagenNopHost) GetFactory(_ component.Kind, _ component.Type) component.Factory { return nil } + +func TestExampleConfigs(t *testing.T) { + tests := []struct { + name string + config string + description string + }{ + { + name: "Default Configuration", + description: "Basic configuration for the sample scraper with default metrics enabled.", + config: `sample: + collection_interval: 30s +`, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Test that the example config is valid YAML + var config map[string]any + err := yaml.Unmarshal([]byte(tt.config), &config) + require.NoError(t, err, "Example config '%s' should be valid YAML: %s", tt.name, tt.description) + require.NotNil(t, config, "Example config '%s' should produce a non-nil config", tt.name) + }) + } +} diff --git a/cmd/mdatagen/internal/samplescraper/generated_package_test.go b/cmd/mdatagen/internal/samplescraper/generated_package_test.go index c9e22693395..04292470111 100644 --- a/cmd/mdatagen/internal/samplescraper/generated_package_test.go +++ b/cmd/mdatagen/internal/samplescraper/generated_package_test.go @@ -3,9 +3,8 @@ package samplescraper import ( - "testing" - "go.uber.org/goleak" + "testing" ) func TestMain(m *testing.M) { diff --git a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs.go b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs.go index 187b564f16a..51021210666 100644 --- a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs.go +++ b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs.go @@ -3,12 +3,11 @@ package metadata import ( - conventions "go.opentelemetry.io/otel/semconv/v1.37.0" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/plog" "go.opentelemetry.io/collector/scraper" + conventions "go.opentelemetry.io/otel/semconv/v1.9.0" ) // LogsBuilder provides an interface for scrapers to report logs while taking care of all the transformations diff --git a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs_test.go b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs_test.go index 4e69cbe09fc..7304aa36077 100644 --- a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs_test.go +++ b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_logs_test.go @@ -3,16 +3,14 @@ package metadata import ( - "testing" - "time" - "github.com/stretchr/testify/assert" - "go.uber.org/zap" - "go.uber.org/zap/zaptest/observer" - "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/plog" "go.opentelemetry.io/collector/scraper/scrapertest" + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" + "testing" + "time" ) func TestLogsBuilderAppendLogRecord(t *testing.T) { diff --git a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics.go b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics.go index 296bacb7593..955c756c93c 100644 --- a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics.go +++ b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics.go @@ -7,13 +7,12 @@ import ( "strconv" "time" - conventions "go.opentelemetry.io/otel/semconv/v1.37.0" - "go.opentelemetry.io/collector/component" "go.opentelemetry.io/collector/filter" "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/pmetric" "go.opentelemetry.io/collector/scraper" + conventions "go.opentelemetry.io/otel/semconv/v1.9.0" ) // AttributeEnumAttr specifies the value enum_attr attribute. diff --git a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics_test.go b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics_test.go index a2e2b5e55c0..cfbd7f6e0d5 100644 --- a/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics_test.go +++ b/cmd/mdatagen/internal/samplescraper/internal/metadata/generated_metrics_test.go @@ -6,12 +6,11 @@ import ( "testing" "github.com/stretchr/testify/assert" - "go.uber.org/zap" - "go.uber.org/zap/zaptest/observer" - "go.opentelemetry.io/collector/pdata/pcommon" "go.opentelemetry.io/collector/pdata/pmetric" "go.opentelemetry.io/collector/scraper/scrapertest" + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" ) type testDataSet int diff --git a/cmd/mdatagen/internal/samplescraper/metadata.yaml b/cmd/mdatagen/internal/samplescraper/metadata.yaml index 27b7cb91b66..38e032caf3a 100644 --- a/cmd/mdatagen/internal/samplescraper/metadata.yaml +++ b/cmd/mdatagen/internal/samplescraper/metadata.yaml @@ -5,6 +5,13 @@ github_project: open-telemetry/opentelemetry-collector sem_conv_version: 1.37.0 +example_configs: + - name: Default Configuration + description: Basic configuration for the sample scraper with default metrics enabled. + config: | + sample: + collection_interval: 30s + status: disable_codecov_badge: true class: scraper @@ -118,7 +125,7 @@ metrics: default.metric.to_be_removed: enabled: true - description: "[DEPRECATED] Non-monotonic delta sum double metric enabled by default." + description: '[DEPRECATED] Non-monotonic delta sum double metric enabled by default.' extended_documentation: The metric will be removed soon. stability: level: deprecated @@ -146,10 +153,10 @@ metrics: optional.metric: enabled: false - description: "[DEPRECATED] Gauge double metric disabled by default." + description: '[DEPRECATED] Gauge double metric disabled by default.' stability: level: deprecated - unit: "1" + unit: '1' gauge: value_type: double attributes: [string_attr, boolean_attr, boolean_attr2] @@ -158,10 +165,10 @@ metrics: optional.metric.empty_unit: enabled: false - description: "[DEPRECATED] Gauge double metric disabled by default." + description: '[DEPRECATED] Gauge double metric disabled by default.' stability: level: deprecated - unit: "" + unit: '' gauge: value_type: double attributes: [string_attr, boolean_attr] diff --git a/cmd/mdatagen/internal/templates/component_test.go.tmpl b/cmd/mdatagen/internal/templates/component_test.go.tmpl index 1437e6637c5..2a962f0f619 100644 --- a/cmd/mdatagen/internal/templates/component_test.go.tmpl +++ b/cmd/mdatagen/internal/templates/component_test.go.tmpl @@ -14,6 +14,10 @@ import ( {{- if and (not (and .Tests.SkipLifecycle .Tests.SkipShutdown)) (or isExporter isProcessor) }} "time" {{- end }} + {{- if .ExampleConfigs }} + + "gopkg.in/yaml.v3" + {{- end }} "github.com/stretchr/testify/require" "go.opentelemetry.io/collector/component" @@ -615,3 +619,32 @@ func (mnh *mdatagenNopHost) GetFactory(_ component.Kind, _ component.Type) compo return nil } {{- end }} + +{{- if .ExampleConfigs }} + +func TestExampleConfigs(t *testing.T) { + tests := []struct { + name string + config string + description string + }{ + {{- range $idx, $example := .ExampleConfigs }} + { + name: {{ printf "%q" $example.Name }}, + description: {{ printf "%q" $example.Description }}, + config: {{ printf "`%s`" $example.Config }}, + }, + {{- end }} + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Test that the example config is valid YAML + var config map[string]any + err := yaml.Unmarshal([]byte(tt.config), &config) + require.NoError(t, err, "Example config '%s' should be valid YAML: %s", tt.name, tt.description) + require.NotNil(t, config, "Example config '%s' should produce a non-nil config", tt.name) + }) + } +} +{{- end }} diff --git a/cmd/mdatagen/internal/templates/config_test.go.tmpl b/cmd/mdatagen/internal/templates/config_test.go.tmpl index 781a115c4a0..61f5d95e939 100644 --- a/cmd/mdatagen/internal/templates/config_test.go.tmpl +++ b/cmd/mdatagen/internal/templates/config_test.go.tmpl @@ -9,8 +9,10 @@ import ( "github.com/google/go-cmp/cmp" "github.com/google/go-cmp/cmp/cmpopts" "github.com/stretchr/testify/require" + {{- if or .Metrics .Events }} "go.opentelemetry.io/collector/confmap" + {{- end }} "go.opentelemetry.io/collector/confmap/confmaptest" ) diff --git a/cmd/mdatagen/internal/templates/documentation.md.tmpl b/cmd/mdatagen/internal/templates/documentation.md.tmpl index d8b88254404..f2037b67780 100644 --- a/cmd/mdatagen/internal/templates/documentation.md.tmpl +++ b/cmd/mdatagen/internal/templates/documentation.md.tmpl @@ -112,6 +112,24 @@ **Parent Component:** {{ .Parent }} {{- end }} +{{- if .ExampleConfigs }} + +## Example Configurations + +{{- range $example := .ExampleConfigs }} + +### {{ $example.Name }} + +{{ $example.Description }} + +```yaml +{{ $example.Config }} +``` + +{{- end }} + +{{- end }} + {{- if .Metrics }} ## Default Metrics diff --git a/cmd/mdatagen/metadata-schema.yaml b/cmd/mdatagen/metadata-schema.yaml index e11880d26b3..6595e6a2333 100644 --- a/cmd/mdatagen/metadata-schema.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -10,18 +10,58 @@ scope_name: string # Optional: The name of the package that mdatagen generates. If not set, the name "metadata" will be used. generated_package_name: string +# Optional: Array of example configuration snippets for the component. Used to demonstrate common use cases. +example_configs: + - # Required: A descriptive name for the example configuration. + name: string + # Required: Description providing context about when this configuration should be used. + description: string + # Required: The example configuration snippet in YAML format. + config: | + key: value + # 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/blob/main/docs/component-stability.md#stability-levels stability: - development: [] - alpha: [] - beta: [] - stable: [] - deprecated: [] - unmaintained: [] + development: + [ + , + ] + alpha: + [ + , + ] + beta: + [ + , + ] + stable: + [ + , + ] + deprecated: + [ + , + ] + unmaintained: + [ + , + ] # Required for deprecated components: The deprecation information for the deprecated components - See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information deprecation: : @@ -133,9 +173,10 @@ metrics: monotonic: bool # Required for sum metric: whether reported values incorporate previous measurements # (cumulative) or not (delta). - aggregation_temporality: - # Optional: Indicates the type the metric needs to be parsed from. If set, the generated - # functions will parse the value from string to value_type. + aggregation_temporality: + + # Optional: Indicates the type the metric needs to be parsed from. If set, the generated + # functions will parse the value from string to value_type. input_type: string # Optional: array of attributes that were defined in the attributes section that are emitted by this metric. attributes: [string] @@ -188,7 +229,6 @@ tests: top: [string] # Optional: array of strings representing functions that should be ignore via IgnoreTopFunction any: [string] # Optional: array of strings representing functions that should be ignore via IgnoreAnyFunction - # Optional: map of metric names with the key being the metric name and value # being described below. telemetry: