[mdatagen] Support logs

.chloggen/mdatagen-logs.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: cmd/mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add the foundational changes necessary for supporting logs data in `mdatagen`
+
+# One or more tracking issues or pull requests related to the change
+issues: [12571]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

cmd/mdatagen/internal/command.go

@@ -183,6 +183,12 @@ func run(ymlPath string) error {
 		toGenerate[filepath.Join(tmplDir, "metrics_test.go.tmpl")] = filepath.Join(codeDir, "generated_metrics_test.go")
 	}
 
+	if md.supportsSignal("logs") &&
+		(md.Status.Class == "receiver" || md.Status.Class == "scraper") {
+		toGenerate[filepath.Join(tmplDir, "logs.go.tmpl")] = filepath.Join(codeDir, "generated_logs.go")
+		toGenerate[filepath.Join(tmplDir, "logs_test.go.tmpl")] = filepath.Join(codeDir, "generated_logs_test.go")
+	}
+
 	// If at least one file to generate, will need the codeDir
 	if len(toGenerate) > 0 {
 		if err = os.MkdirAll(codeDir, 0o700); err != nil {

cmd/mdatagen/internal/embedded_templates_test.go

@@ -25,6 +25,8 @@ func TestEnsureTemplatesLoaded(t *testing.T) {
 			path.Join(rootDir, "documentation.md.tmpl"):        {},
 			path.Join(rootDir, "metrics.go.tmpl"):              {},
 			path.Join(rootDir, "metrics_test.go.tmpl"):         {},
+			path.Join(rootDir, "logs.go.tmpl"):                 {},
+			path.Join(rootDir, "logs_test.go.tmpl"):            {},
 			path.Join(rootDir, "resource.go.tmpl"):             {},
 			path.Join(rootDir, "resource_test.go.tmpl"):        {},
 			path.Join(rootDir, "config.go.tmpl"):               {},

cmd/mdatagen/internal/metadata.go

@@ -136,6 +136,10 @@ func (md *Metadata) validateAttributes(usedAttrs map[AttributeName]bool) error {
 }
 
 func (md *Metadata) supportsSignal(signal string) bool {
+	if md.Status == nil {
+		return false
+	}
+
 	for _, signals := range md.Status.Stability {
 		for _, s := range signals {
 			if s == signal {

cmd/mdatagen/internal/metadata_test.go

@@ -158,6 +158,11 @@ func TestValidateMetricDuplicates(t *testing.T) {
 	}
 }
 
+func TestSupportsSignal(t *testing.T) {
+	md := Metadata{}
+	assert.False(t, md.supportsSignal("logs"))
+}
+
 func contains(r string, rs []string) bool {
 	for _, s := range rs {
 		if s == r {

cmd/mdatagen/internal/templates/logs.go.tmpl

@@ -0,0 +1,105 @@
+// Code generated by mdatagen. DO NOT EDIT.
+
+package {{ .Package }}
+
+import (
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/pdata/pcommon"
+	"go.opentelemetry.io/collector/pdata/plog"
+	{{- if or isReceiver isScraper }}
+	"go.opentelemetry.io/collector/{{ .Status.Class }}"
+	{{- end }}
+	{{- if .SemConvVersion }}
+	conventions "go.opentelemetry.io/collector/semconv/v{{ .SemConvVersion }}"
+	{{- end }}
+)
+
+// LogsBuilder provides an interface for scrapers to report logs while taking care of all the transformations
+// required to produce log representation defined in metadata and user config.
+type LogsBuilder struct {
+	logsBuffer plog.Logs
+	logRecordsBuffer plog.LogRecordSlice
+	buildInfo       component.BuildInfo  // contains version information.
+}
+
+// LogBuilderOption applies changes to default logs builder.
+type LogBuilderOption interface {
+    apply(*LogsBuilder)
+}
+
+{{- if isReceiver }}
+func NewLogsBuilder(settings {{ .Status.Class }}.Settings) *LogsBuilder {
+	lb := &LogsBuilder{
+		logsBuffer:     plog.NewLogs(),
+		logRecordsBuffer: plog.NewLogRecordSlice(),
+		buildInfo:      settings.BuildInfo,
+	}
+
+	return lb
+}
+{{- end }}
+
+{{- if .ResourceAttributes }}
+// NewResourceBuilder returns a new resource builder that should be used to build a resource associated with for the emitted logs.
+func (lb *LogsBuilder) NewResourceBuilder() *ResourceBuilder {
+	return NewResourceBuilder(ResourceAttributesConfig{})
+}
+{{- end }}
+
+// ResourceLogsOption applies changes to provided resource logs.
+type ResourceLogsOption interface {
+    apply(plog.ResourceLogs)
+}
+
+type resourceLogsOptionFunc func(plog.ResourceLogs)
+
+func (rlof resourceLogsOptionFunc) apply(rl plog.ResourceLogs) {
+    rlof(rl)
+}
+
+// WithLogsResource sets the provided resource on the emitted ResourceLogs.
+// It's recommended to use ResourceBuilder to create the resource.
+func WithLogsResource(res pcommon.Resource) ResourceLogsOption {
+	return resourceLogsOptionFunc(func(rl plog.ResourceLogs) {
+		res.CopyTo(rl.Resource())
+	})
+}
+
+// AppendLogRecord adds a log record to the logs builder.
+func (lb *LogsBuilder) AppendLogRecord(lr plog.LogRecord) {
+	lr.MoveTo(lb.logRecordsBuffer.AppendEmpty())
+}
+
+// EmitForResource saves all the generated logs under a new resource and updates the internal state to be ready for
+// recording another set of log records as part of another resource. This function can be helpful when one scraper
+// needs to emit logs from several resources. Otherwise calling this function is not required,
+// just `Emit` function can be called instead.
+// Resource attributes should be provided as ResourceLogsOption arguments.
+func (lb *LogsBuilder) EmitForResource(options ...ResourceLogsOption) {
+	rl := lb.logsBuffer.ResourceLogs().AppendEmpty()
+	{{- if .SemConvVersion }}
+	rl.SetSchemaUrl(conventions.SchemaURL)
+	{{- end }}
+	ils := rl.ScopeLogs().AppendEmpty()
+	ils.Scope().SetName(ScopeName)
+	ils.Scope().SetVersion(lb.buildInfo.Version)
+
+	for _, op := range options {
+		op.apply(rl)
+	}
+
+    if lb.logRecordsBuffer.Len() > 0 {
+        lb.logRecordsBuffer.MoveAndAppendTo(ils.LogRecords())
+        lb.logRecordsBuffer = plog.NewLogRecordSlice()
+    }
+}
+
+// Emit returns all the logs accumulated by the logs builder and updates the internal state to be ready for
+// recording another set of logs. This function will be responsible for applying all the transformations required to
+// produce logs representation defined in metadata and user config.
+func (lb *LogsBuilder) Emit(options ...ResourceLogsOption) plog.Logs {
+	lb.EmitForResource(options...)
+    logs := lb.logsBuffer
+    lb.logsBuffer = plog.NewLogs()
+	return logs
+}