From a8640325c7beb599efb099bbe52e7a8eec0f772b Mon Sep 17 00:00:00 2001 From: Dmitrii Anoshin Date: Thu, 14 Apr 2022 15:16:36 -0700 Subject: [PATCH] Update pdata godoc strings (#5226) - Use copy of the godoc comments from pdata/internal instead of mentioning aliases in pdata/p public API docs. - Update godoc strings in both pdata/p and pdata/internal to keep them consistent. --- .../cmd/pdatagen/internal/base_slices.go | 53 ++-- .../cmd/pdatagen/internal/base_structs.go | 33 +-- pdata/internal/cmd/pdatagen/internal/files.go | 10 +- pdata/internal/cmd/pdatagen/main.go | 7 +- pdata/internal/common.go | 4 +- pdata/internal/logs.go | 4 +- pdata/internal/metrics.go | 2 +- pdata/internal/spanid.go | 2 +- pdata/internal/traceid.go | 2 +- pdata/internal/traces.go | 2 +- pdata/pcommon/alias.go | 57 ++++- pdata/pcommon/generated_common_alias.go | 19 +- pdata/pcommon/generated_resource_alias.go | 8 +- pdata/pcommon/spanid_alias.go | 6 +- pdata/pcommon/timestamp_alias.go | 5 +- pdata/pcommon/traceid_alias.go | 6 +- pdata/plog/alias.go | 7 +- pdata/plog/generated_alias.go | 58 ++++- pdata/pmetric/alias.go | 33 ++- pdata/pmetric/generated_alias.go | 227 +++++++++++++++--- pdata/ptrace/alias.go | 47 +++- pdata/ptrace/generated_alias.go | 108 +++++++-- 22 files changed, 518 insertions(+), 182 deletions(-) diff --git a/pdata/internal/cmd/pdatagen/internal/base_slices.go b/pdata/internal/cmd/pdatagen/internal/base_slices.go index d1656da03fd..b1a9255ead4 100644 --- a/pdata/internal/cmd/pdatagen/internal/base_slices.go +++ b/pdata/internal/cmd/pdatagen/internal/base_slices.go @@ -111,11 +111,18 @@ func fillTest${structName}(tv ${structName}) { } }` -const commonSliceAliasTemplate = `// ${structName} is an alias for ${refPackage}.${structName} struct. -${extraStructComment}type ${structName} = ${refPackage}.${structName} +const commonSliceAliasTemplate = `// ${structName} logically represents a slice of ${elementName}. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use New${structName} function to create new instances. +// Important: zero-initialized instance is not valid for use. +type ${structName} = internal.${structName} -// New${structName} is an alias for a function to create ${structName}. -${extraNewComment}var New${structName} = ${refPackage}.New${structName}` +// New${structName} creates a ${structName} with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. +var New${structName} = internal.New${structName}` const slicePtrTemplate = `// ${structName} logically represents a slice of ${elementName}. // @@ -477,26 +484,13 @@ func (ss *sliceOfPtrs) templateFields() func(name string) string { } } -func (ss *sliceOfPtrs) generateAlias(sb *strings.Builder, deprecatedInFavor string) { +func (ss *sliceOfPtrs) generateAlias(sb *strings.Builder) { sb.WriteString(os.Expand(commonSliceAliasTemplate, func(name string) string { switch name { case "structName": return ss.structName - case "refPackage": - if deprecatedInFavor == "" { - return "internal" - } - return deprecatedInFavor - case "extraStructComment": - if deprecatedInFavor != "" { - return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + "." + ss.structName + " instead.\n" - } - return "" - case "extraNewComment": - if deprecatedInFavor != "" { - return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + ".New" + ss.structName + " instead.\n" - } - return "" + case "elementName": + return ss.element.structName default: panic(name) } @@ -545,26 +539,13 @@ func (ss *sliceOfValues) templateFields() func(name string) string { } } -func (ss *sliceOfValues) generateAlias(sb *strings.Builder, deprecatedInFavor string) { +func (ss *sliceOfValues) generateAlias(sb *strings.Builder) { sb.WriteString(os.Expand(commonSliceAliasTemplate, func(name string) string { switch name { case "structName": return ss.structName - case "refPackage": - if deprecatedInFavor == "" { - return "internal" - } - return deprecatedInFavor - case "extraStructComment": - if deprecatedInFavor != "" { - return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + "." + ss.structName + " instead.\n" - } - return "" - case "extraNewComment": - if deprecatedInFavor != "" { - return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + ".New" + ss.structName + " instead.\n" - } - return "" + case "elementName": + return ss.element.structName default: panic(name) } diff --git a/pdata/internal/cmd/pdatagen/internal/base_structs.go b/pdata/internal/cmd/pdatagen/internal/base_structs.go index 9ec676e3e11..ece6caf3aa8 100644 --- a/pdata/internal/cmd/pdatagen/internal/base_structs.go +++ b/pdata/internal/cmd/pdatagen/internal/base_structs.go @@ -78,11 +78,17 @@ const messageValueGenerateTestTemplate = `func generateTest${structName}() ${str const messageValueFillTestHeaderTemplate = `func fillTest${structName}(tv ${structName}) {` const messageValueFillTestFooterTemplate = `}` -const messageValueAliasTemplate = `// ${structName} is an alias for ${refPackage}.${structName} struct. -${extraStructComment}type ${structName} = ${refPackage}.${structName} +const messageValueAliasTemplate = `${description} +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use New${structName} function to create new instances. +// Important: zero-initialized instance is not valid for use. +type ${structName} = internal.${structName} // New${structName} is an alias for a function to create a new empty ${structName}. -${extraStructComment}var New${structName} = ${refPackage}.New${structName}` +var New${structName} = internal.New${structName}` const newLine = "\n" @@ -97,7 +103,7 @@ type baseStruct interface { } type aliasGenerator interface { - generateAlias(sb *strings.Builder, deprecatedInFavor string) + generateAlias(sb *strings.Builder) } type messageValueStruct struct { @@ -196,26 +202,13 @@ func (ms *messageValueStruct) generateTestValueHelpers(sb *strings.Builder) { })) } -func (ms *messageValueStruct) generateAlias(sb *strings.Builder, deprecatedInFavor string) { +func (ms *messageValueStruct) generateAlias(sb *strings.Builder) { sb.WriteString(os.Expand(messageValueAliasTemplate, func(name string) string { switch name { case "structName": return ms.structName - case "refPackage": - if deprecatedInFavor == "" { - return "internal" - } - return deprecatedInFavor - case "extraStructComment": - if deprecatedInFavor != "" { - return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + "." + ms.structName + " instead.\n" - } - return "" - case "extraNewComment": - if deprecatedInFavor != "" { - return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + ".New" + ms.structName + " instead.\n" - } - return "" + case "description": + return ms.description default: panic(name) } diff --git a/pdata/internal/cmd/pdatagen/internal/files.go b/pdata/internal/cmd/pdatagen/internal/files.go index ea9343d84f6..e07396c74f4 100644 --- a/pdata/internal/cmd/pdatagen/internal/files.go +++ b/pdata/internal/cmd/pdatagen/internal/files.go @@ -110,22 +110,18 @@ func (f *File) GenerateTestFile() string { } // GenerateFile generates the aliases for data structures for this File. -func (f *File) GenerateAliasFile(packageName string, deprecatedInFavor string) string { +func (f *File) GenerateAliasFile(packageName string) string { var sb strings.Builder generateHeader(&sb, packageName) // Add import - imp := "import \"go.opentelemetry.io/collector/pdata/internal\"" - if packageName == "pdata" { - imp = "import \"go.opentelemetry.io/collector/pdata/" + deprecatedInFavor + "\"" - } - sb.WriteString(imp + newLine + newLine) + sb.WriteString("import \"go.opentelemetry.io/collector/pdata/internal\"" + newLine + newLine) // Write all types and funcs for _, s := range f.structs { if ag, ok := s.(aliasGenerator); ok { - ag.generateAlias(&sb, deprecatedInFavor) + ag.generateAlias(&sb) } } sb.WriteString(newLine) diff --git a/pdata/internal/cmd/pdatagen/main.go b/pdata/internal/cmd/pdatagen/main.go index e5300897d2e..92e7dbb1de7 100644 --- a/pdata/internal/cmd/pdatagen/main.go +++ b/pdata/internal/cmd/pdatagen/main.go @@ -39,20 +39,15 @@ func main() { _, err = f.WriteString(fp.GenerateTestFile()) check(err) check(f.Close()) - f, err = os.Create("./model/pdata/generated_" + fp.Name + "_alias.go") - check(err) fileName := "generated_alias.go" packageName := fp.Name if fp.IsCommon() { fileName = "generated_" + fp.Name + "_alias.go" packageName = "pcommon" } - _, err = f.WriteString(fp.GenerateAliasFile("pdata", packageName)) - check(err) - check(f.Close()) f, err = os.Create(filepath.Clean("./pdata/" + packageName + "/" + fileName)) check(err) - _, err = f.WriteString(fp.GenerateAliasFile(packageName, "")) + _, err = f.WriteString(fp.GenerateAliasFile(packageName)) check(err) check(f.Close()) } diff --git a/pdata/internal/common.go b/pdata/internal/common.go index 2d16348d6f9..5c0964df2a2 100644 --- a/pdata/internal/common.go +++ b/pdata/internal/common.go @@ -66,7 +66,7 @@ func (avt ValueType) String() string { return "" } -// Value is a mutable cell containing the value of an attribute. Typically used in Map. +// Value is a mutable cell containing any value. Typically used as an element of Map or Slice. // Must use one of NewValue+ functions below to create new instances. // // Intended to be passed by value since internally it is just a pointer to actual @@ -547,7 +547,7 @@ func newAttributeKeyValueBytes(k string, v []byte) otlpcommon.KeyValue { return orig } -// Map stores a map of attribute keys to values. +// Map stores a map of string keys to elements of Value type. type Map struct { orig *[]otlpcommon.KeyValue } diff --git a/pdata/internal/logs.go b/pdata/internal/logs.go index 5e4b1580a06..709e512152f 100644 --- a/pdata/internal/logs.go +++ b/pdata/internal/logs.go @@ -49,7 +49,7 @@ type Logs struct { orig *otlpcollectorlog.ExportLogsServiceRequest } -// NewLogs creates a new Logs. +// NewLogs creates a new Logs struct. func NewLogs() Logs { return Logs{orig: &otlpcollectorlog.ExportLogsServiceRequest{}} } @@ -88,7 +88,7 @@ func (ld Logs) ResourceLogs() ResourceLogsSlice { return newResourceLogsSlice(&ld.orig.ResourceLogs) } -// SeverityNumber is the public alias of otlplogs.SeverityNumber from internal package. +// SeverityNumber represents severity number of a log record. type SeverityNumber int32 const ( diff --git a/pdata/internal/metrics.go b/pdata/internal/metrics.go index 3c4f1acc9ba..a73fd449418 100644 --- a/pdata/internal/metrics.go +++ b/pdata/internal/metrics.go @@ -49,7 +49,7 @@ type Metrics struct { orig *otlpcollectormetrics.ExportMetricsServiceRequest } -// NewMetrics creates a new Metrics. +// NewMetrics creates a new Metrics struct. func NewMetrics() Metrics { return Metrics{orig: &otlpcollectormetrics.ExportMetricsServiceRequest{}} } diff --git a/pdata/internal/spanid.go b/pdata/internal/spanid.go index 91eda5767e6..2ac539e1129 100644 --- a/pdata/internal/spanid.go +++ b/pdata/internal/spanid.go @@ -18,7 +18,7 @@ import ( "go.opentelemetry.io/collector/pdata/internal/data" ) -// SpanID is an alias of OTLP SpanID data type. +// SpanID is span identifier. type SpanID struct { orig data.SpanID } diff --git a/pdata/internal/traceid.go b/pdata/internal/traceid.go index 4736f979b1b..2d6365f2755 100644 --- a/pdata/internal/traceid.go +++ b/pdata/internal/traceid.go @@ -18,7 +18,7 @@ import ( "go.opentelemetry.io/collector/pdata/internal/data" ) -// TraceID is an alias of OTLP TraceID data type. +// TraceID is a trace identifier. type TraceID struct { orig data.TraceID } diff --git a/pdata/internal/traces.go b/pdata/internal/traces.go index 0ba7fc218e0..e9477fb6a17 100644 --- a/pdata/internal/traces.go +++ b/pdata/internal/traces.go @@ -50,7 +50,7 @@ type Traces struct { orig *otlpcollectortrace.ExportTraceServiceRequest } -// NewTraces creates a new Traces. +// NewTraces creates a new Traces struct. func NewTraces() Traces { return Traces{orig: &otlpcollectortrace.ExportTraceServiceRequest{}} } diff --git a/pdata/pcommon/alias.go b/pdata/pcommon/alias.go index 9a7259b29b0..7e3319f0fb4 100644 --- a/pdata/pcommon/alias.go +++ b/pdata/pcommon/alias.go @@ -19,7 +19,7 @@ package pcommon // import "go.opentelemetry.io/collector/pdata/pcommon" import "go.opentelemetry.io/collector/pdata/internal" -// ValueType is an alias for internal.ValueType type. +// ValueType specifies the type of Value. type ValueType = internal.ValueType const ( @@ -33,26 +33,59 @@ const ( ValueTypeBytes = internal.ValueTypeBytes ) -// Value is an alias for internal.Value struct. +// Value is a mutable cell containing any value. Typically used as an element of Map or Slice. +// Must use one of NewValue+ functions below to create new instances. +// +// Intended to be passed by value since internally it is just a pointer to actual +// value representation. For the same reason passing by value and calling setters +// will modify the original, e.g.: +// +// func f1(val Value) { val.SetIntVal(234) } +// func f2() { +// v := NewValueString("a string") +// f1(v) +// _ := v.Type() // this will return ValueTypeInt +// } +// +// Important: zero-initialized instance is not valid for use. All Value functions below must +// be called only on instances that are created via NewValue+ functions. type Value = internal.Value -// Aliases for functions to create internal.Value. var ( - NewValueEmpty = internal.NewValueEmpty + // NewValueEmpty creates a new Value with an empty value. + NewValueEmpty = internal.NewValueEmpty + + // NewValueString creates a new Value with the given string value. NewValueString = internal.NewValueString - NewValueInt = internal.NewValueInt + + // NewValueInt creates a new Value with the given int64 value. + NewValueInt = internal.NewValueInt + + // NewValueDouble creates a new Value with the given float64 value. NewValueDouble = internal.NewValueDouble - NewValueBool = internal.NewValueBool - NewValueMap = internal.NewValueMap - NewValueSlice = internal.NewValueSlice - NewValueBytes = internal.NewValueBytes + + // NewValueBool creates a new Value with the given bool value. + NewValueBool = internal.NewValueBool + + // NewValueMap creates a new Value of map type. + NewValueMap = internal.NewValueMap + + // NewValueSlice creates a new Value of array type. + NewValueSlice = internal.NewValueSlice + + // NewValueBytes creates a new Value with the given []byte value. + // The caller must ensure the []byte passed in is not modified after the call is made, sharing the data + // across multiple attributes is forbidden. + NewValueBytes = internal.NewValueBytes ) -// Map is an alias for internal.Map struct. +// Map stores a map of string keys to elements of Value type. type Map = internal.Map -// Aliases for functions to create internal.Map. var ( - NewMap = internal.NewMap + // NewMap creates a Map with 0 elements. + NewMap = internal.NewMap + + // NewMapFromRaw creates a Map with values from the given map[string]interface{}. NewMapFromRaw = internal.NewMapFromRaw ) diff --git a/pdata/pcommon/generated_common_alias.go b/pdata/pcommon/generated_common_alias.go index 7ede4c76408..fd1425dfd23 100644 --- a/pdata/pcommon/generated_common_alias.go +++ b/pdata/pcommon/generated_common_alias.go @@ -19,14 +19,27 @@ package pcommon import "go.opentelemetry.io/collector/pdata/internal" -// InstrumentationScope is an alias for internal.InstrumentationScope struct. +// InstrumentationScope is a message representing the instrumentation scope information. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewInstrumentationScope function to create new instances. +// Important: zero-initialized instance is not valid for use. type InstrumentationScope = internal.InstrumentationScope // NewInstrumentationScope is an alias for a function to create a new empty InstrumentationScope. var NewInstrumentationScope = internal.NewInstrumentationScope -// Slice is an alias for internal.Slice struct. +// Slice logically represents a slice of Value. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type Slice = internal.Slice -// NewSlice is an alias for a function to create Slice. +// NewSlice creates a Slice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewSlice = internal.NewSlice diff --git a/pdata/pcommon/generated_resource_alias.go b/pdata/pcommon/generated_resource_alias.go index c061ee8b9f0..3c10716d16e 100644 --- a/pdata/pcommon/generated_resource_alias.go +++ b/pdata/pcommon/generated_resource_alias.go @@ -19,7 +19,13 @@ package pcommon import "go.opentelemetry.io/collector/pdata/internal" -// Resource is an alias for internal.Resource struct. +// Resource is a message representing the resource information. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewResource function to create new instances. +// Important: zero-initialized instance is not valid for use. type Resource = internal.Resource // NewResource is an alias for a function to create a new empty Resource. diff --git a/pdata/pcommon/spanid_alias.go b/pdata/pcommon/spanid_alias.go index b71d21e8183..a37a7fd603a 100644 --- a/pdata/pcommon/spanid_alias.go +++ b/pdata/pcommon/spanid_alias.go @@ -16,11 +16,11 @@ package pcommon // import "go.opentelemetry.io/collector/pdata/pcommon" import "go.opentelemetry.io/collector/pdata/internal" -// SpanID is an alias for internal.SpanID struct. +// SpanID is span identifier. type SpanID = internal.SpanID -// InvalidSpanID is an alias for internal.InvalidSpanID function. +// InvalidSpanID returns an empty (all zero bytes) SpanID. var InvalidSpanID = internal.InvalidSpanID -// NewSpanID is an alias for a function to create new SpanID. +// NewSpanID returns a new SpanID from the given byte array. var NewSpanID = internal.NewSpanID diff --git a/pdata/pcommon/timestamp_alias.go b/pdata/pcommon/timestamp_alias.go index 00540f546c7..1d5e81ce89e 100644 --- a/pdata/pcommon/timestamp_alias.go +++ b/pdata/pcommon/timestamp_alias.go @@ -16,8 +16,9 @@ package pcommon // import "go.opentelemetry.io/collector/pdata/pcommon" import "go.opentelemetry.io/collector/pdata/internal" -// Timestamp is a an alias for internal.Timestamp. +// Timestamp is a time specified as UNIX Epoch time in nanoseconds since +// 1970-01-01 00:00:00 +0000 UTC. type Timestamp = internal.Timestamp -// NewTimestampFromTime is an alias for internal.NewTimestampFromTime function. +// NewTimestampFromTime constructs a new Timestamp from the provided time.Time. var NewTimestampFromTime = internal.NewTimestampFromTime diff --git a/pdata/pcommon/traceid_alias.go b/pdata/pcommon/traceid_alias.go index 43862477ad8..99ffa62d251 100644 --- a/pdata/pcommon/traceid_alias.go +++ b/pdata/pcommon/traceid_alias.go @@ -16,11 +16,11 @@ package pcommon // import "go.opentelemetry.io/collector/pdata/pcommon" import "go.opentelemetry.io/collector/pdata/internal" -// TraceID is an alias for internal.TraceID struct. +// TraceID is a trace identifier. type TraceID = internal.TraceID -// InvalidTraceID is an alias for internal.InvalidTraceID function. +// InvalidTraceID returns an empty (all zero bytes) TraceID. var InvalidTraceID = internal.InvalidTraceID -// NewTraceID is an alias for a function to create new TraceID. +// NewTraceID returns a new TraceID from the given byte array. var NewTraceID = internal.NewTraceID diff --git a/pdata/plog/alias.go b/pdata/plog/alias.go index fa253212ad7..7b989979e6f 100644 --- a/pdata/plog/alias.go +++ b/pdata/plog/alias.go @@ -18,13 +18,14 @@ package plog // import "go.opentelemetry.io/collector/pdata/plog" import "go.opentelemetry.io/collector/pdata/internal" -// Logs is an alias for internal.Logs struct. +// Logs is the top-level struct that is propagated through the logs pipeline. +// Use NewLogs to create new instance, zero-initialized instance is not valid for use. type Logs = internal.Logs -// NewLogs is an alias for a function to create new Logs. +// NewLogs creates a new Logs struct. var NewLogs = internal.NewLogs -// SeverityNumber is an alias for internal.SeverityNumber type. +// SeverityNumber represents severity number of a log record. type SeverityNumber = internal.SeverityNumber const ( diff --git a/pdata/plog/generated_alias.go b/pdata/plog/generated_alias.go index ed3a336a71c..aacb32d4343 100644 --- a/pdata/plog/generated_alias.go +++ b/pdata/plog/generated_alias.go @@ -19,37 +19,77 @@ package plog import "go.opentelemetry.io/collector/pdata/internal" -// ResourceLogsSlice is an alias for internal.ResourceLogsSlice struct. +// ResourceLogsSlice logically represents a slice of ResourceLogs. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewResourceLogsSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ResourceLogsSlice = internal.ResourceLogsSlice -// NewResourceLogsSlice is an alias for a function to create ResourceLogsSlice. +// NewResourceLogsSlice creates a ResourceLogsSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewResourceLogsSlice = internal.NewResourceLogsSlice -// ResourceLogs is an alias for internal.ResourceLogs struct. +// ResourceLogs is a collection of logs from a Resource. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewResourceLogs function to create new instances. +// Important: zero-initialized instance is not valid for use. type ResourceLogs = internal.ResourceLogs // NewResourceLogs is an alias for a function to create a new empty ResourceLogs. var NewResourceLogs = internal.NewResourceLogs -// ScopeLogsSlice is an alias for internal.ScopeLogsSlice struct. +// ScopeLogsSlice logically represents a slice of ScopeLogs. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewScopeLogsSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ScopeLogsSlice = internal.ScopeLogsSlice -// NewScopeLogsSlice is an alias for a function to create ScopeLogsSlice. +// NewScopeLogsSlice creates a ScopeLogsSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewScopeLogsSlice = internal.NewScopeLogsSlice -// ScopeLogs is an alias for internal.ScopeLogs struct. +// ScopeLogs is a collection of logs from a LibraryInstrumentation. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewScopeLogs function to create new instances. +// Important: zero-initialized instance is not valid for use. type ScopeLogs = internal.ScopeLogs // NewScopeLogs is an alias for a function to create a new empty ScopeLogs. var NewScopeLogs = internal.NewScopeLogs -// LogRecordSlice is an alias for internal.LogRecordSlice struct. +// LogRecordSlice logically represents a slice of LogRecord. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewLogRecordSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type LogRecordSlice = internal.LogRecordSlice -// NewLogRecordSlice is an alias for a function to create LogRecordSlice. +// NewLogRecordSlice creates a LogRecordSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewLogRecordSlice = internal.NewLogRecordSlice -// LogRecord is an alias for internal.LogRecord struct. +// LogRecord are experimental implementation of OpenTelemetry Log Data Model. + +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewLogRecord function to create new instances. +// Important: zero-initialized instance is not valid for use. type LogRecord = internal.LogRecord // NewLogRecord is an alias for a function to create a new empty LogRecord. diff --git a/pdata/pmetric/alias.go b/pdata/pmetric/alias.go index 411b65dc993..b2e87c62fa5 100644 --- a/pdata/pmetric/alias.go +++ b/pdata/pmetric/alias.go @@ -16,13 +16,14 @@ package pmetric // import "go.opentelemetry.io/collector/pdata/pmetric" import "go.opentelemetry.io/collector/pdata/internal" // This file contains aliases for metric data structures. -// Metrics is an alias for internal.Metrics structure. +// Metrics is the top-level struct that is propagated through the metrics pipeline. +// Use NewMetrics to create new instance, zero-initialized instance is not valid for use. type Metrics = internal.Metrics -// NewMetrics is an alias for a function to create new Metrics. +// NewMetrics creates a new Metrics struct. var NewMetrics = internal.NewMetrics -// MetricDataType is an alias for internal.MetricDataType type. +// MetricDataType specifies the type of data in a Metric. type MetricDataType = internal.MetricDataType const ( @@ -34,33 +35,45 @@ const ( MetricDataTypeSummary = internal.MetricDataTypeSummary ) -// MetricAggregationTemporality is an alias for internal.MetricAggregationTemporality type. +// MetricAggregationTemporality defines how a metric aggregator reports aggregated values. +// It describes how those values relate to the time interval over which they are aggregated. type MetricAggregationTemporality = internal.MetricAggregationTemporality const ( + // MetricAggregationTemporalityUnspecified is the default MetricAggregationTemporality, it MUST NOT be used. MetricAggregationTemporalityUnspecified = internal.MetricAggregationTemporalityUnspecified - MetricAggregationTemporalityDelta = internal.MetricAggregationTemporalityDelta - MetricAggregationTemporalityCumulative = internal.MetricAggregationTemporalityCumulative + + // MetricAggregationTemporalityDelta is a MetricAggregationTemporality for a metric aggregator which reports changes since last report time. + MetricAggregationTemporalityDelta = internal.MetricAggregationTemporalityDelta + + // MetricAggregationTemporalityCumulative is a MetricAggregationTemporality for a metric aggregator which reports changes since a fixed start time. + MetricAggregationTemporalityCumulative = internal.MetricAggregationTemporalityCumulative ) -// MetricDataPointFlags is an alias for internal.MetricDataPointFlags type. +// MetricDataPointFlags defines how a metric aggregator reports aggregated values. +// It describes how those values relate to the time interval over which they are aggregated. type MetricDataPointFlags = internal.MetricDataPointFlags const ( + // MetricDataPointFlagsNone is the default MetricDataPointFlags. MetricDataPointFlagsNone = internal.MetricDataPointFlagsNone ) -// NewMetricDataPointFlags is an alias for a function to create new MetricDataPointFlags. +// NewMetricDataPointFlags returns a new MetricDataPointFlags combining the flags passed +// in as parameters. var NewMetricDataPointFlags = internal.NewMetricDataPointFlags -// MetricDataPointFlag is an alias for internal.MetricDataPointFlag type. +// MetricDataPointFlag allow users to configure DataPointFlags. This is achieved via NewMetricDataPointFlags. +// The separation between MetricDataPointFlags and MetricDataPointFlag exists to prevent users accidentally +// comparing the value of individual flags with MetricDataPointFlags. Instead, users must use the HasFlag method. type MetricDataPointFlag = internal.MetricDataPointFlag const ( + // MetricDataPointFlagNoRecordedValue is flag for a metric aggregator which reports changes since last report time. MetricDataPointFlagNoRecordedValue = internal.MetricDataPointFlagNoRecordedValue ) -// MetricValueType is an alias for internal.MetricValueType type. +// MetricValueType specifies the type of NumberDataPoint. type MetricValueType = internal.MetricValueType const ( diff --git a/pdata/pmetric/generated_alias.go b/pdata/pmetric/generated_alias.go index 1d4876f6006..86343ebe339 100644 --- a/pdata/pmetric/generated_alias.go +++ b/pdata/pmetric/generated_alias.go @@ -19,145 +19,306 @@ package pmetric import "go.opentelemetry.io/collector/pdata/internal" -// ResourceMetricsSlice is an alias for internal.ResourceMetricsSlice struct. +// ResourceMetricsSlice logically represents a slice of ResourceMetrics. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewResourceMetricsSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ResourceMetricsSlice = internal.ResourceMetricsSlice -// NewResourceMetricsSlice is an alias for a function to create ResourceMetricsSlice. +// NewResourceMetricsSlice creates a ResourceMetricsSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewResourceMetricsSlice = internal.NewResourceMetricsSlice -// ResourceMetrics is an alias for internal.ResourceMetrics struct. +// ResourceMetrics is a collection of metrics from a Resource. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewResourceMetrics function to create new instances. +// Important: zero-initialized instance is not valid for use. type ResourceMetrics = internal.ResourceMetrics // NewResourceMetrics is an alias for a function to create a new empty ResourceMetrics. var NewResourceMetrics = internal.NewResourceMetrics -// ScopeMetricsSlice is an alias for internal.ScopeMetricsSlice struct. +// ScopeMetricsSlice logically represents a slice of ScopeMetrics. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewScopeMetricsSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ScopeMetricsSlice = internal.ScopeMetricsSlice -// NewScopeMetricsSlice is an alias for a function to create ScopeMetricsSlice. +// NewScopeMetricsSlice creates a ScopeMetricsSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewScopeMetricsSlice = internal.NewScopeMetricsSlice -// ScopeMetrics is an alias for internal.ScopeMetrics struct. +// ScopeMetrics is a collection of metrics from a LibraryInstrumentation. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewScopeMetrics function to create new instances. +// Important: zero-initialized instance is not valid for use. type ScopeMetrics = internal.ScopeMetrics // NewScopeMetrics is an alias for a function to create a new empty ScopeMetrics. var NewScopeMetrics = internal.NewScopeMetrics -// MetricSlice is an alias for internal.MetricSlice struct. +// MetricSlice logically represents a slice of Metric. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewMetricSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type MetricSlice = internal.MetricSlice -// NewMetricSlice is an alias for a function to create MetricSlice. +// NewMetricSlice creates a MetricSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewMetricSlice = internal.NewMetricSlice -// Metric is an alias for internal.Metric struct. +// Metric represents one metric as a collection of datapoints. +// See Metric definition in OTLP: https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewMetric function to create new instances. +// Important: zero-initialized instance is not valid for use. type Metric = internal.Metric // NewMetric is an alias for a function to create a new empty Metric. var NewMetric = internal.NewMetric -// Gauge is an alias for internal.Gauge struct. +// Gauge represents the type of a numeric metric that always exports the "current value" for every data point. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewGauge function to create new instances. +// Important: zero-initialized instance is not valid for use. type Gauge = internal.Gauge // NewGauge is an alias for a function to create a new empty Gauge. var NewGauge = internal.NewGauge -// Sum is an alias for internal.Sum struct. +// Sum represents the type of a numeric metric that is calculated as a sum of all reported measurements over a time interval. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewSum function to create new instances. +// Important: zero-initialized instance is not valid for use. type Sum = internal.Sum // NewSum is an alias for a function to create a new empty Sum. var NewSum = internal.NewSum -// Histogram is an alias for internal.Histogram struct. +// Histogram represents the type of a metric that is calculated by aggregating as a Histogram of all reported measurements over a time interval. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewHistogram function to create new instances. +// Important: zero-initialized instance is not valid for use. type Histogram = internal.Histogram // NewHistogram is an alias for a function to create a new empty Histogram. var NewHistogram = internal.NewHistogram -// ExponentialHistogram is an alias for internal.ExponentialHistogram struct. +// ExponentialHistogram represents the type of a metric that is calculated by aggregating +// as a ExponentialHistogram of all reported double measurements over a time interval. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewExponentialHistogram function to create new instances. +// Important: zero-initialized instance is not valid for use. type ExponentialHistogram = internal.ExponentialHistogram // NewExponentialHistogram is an alias for a function to create a new empty ExponentialHistogram. var NewExponentialHistogram = internal.NewExponentialHistogram -// Summary is an alias for internal.Summary struct. +// Summary represents the type of a metric that is calculated by aggregating as a Summary of all reported double measurements over a time interval. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewSummary function to create new instances. +// Important: zero-initialized instance is not valid for use. type Summary = internal.Summary // NewSummary is an alias for a function to create a new empty Summary. var NewSummary = internal.NewSummary -// NumberDataPointSlice is an alias for internal.NumberDataPointSlice struct. +// NumberDataPointSlice logically represents a slice of NumberDataPoint. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewNumberDataPointSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type NumberDataPointSlice = internal.NumberDataPointSlice -// NewNumberDataPointSlice is an alias for a function to create NumberDataPointSlice. +// NewNumberDataPointSlice creates a NumberDataPointSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewNumberDataPointSlice = internal.NewNumberDataPointSlice -// NumberDataPoint is an alias for internal.NumberDataPoint struct. +// NumberDataPoint is a single data point in a timeseries that describes the time-varying value of a number metric. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewNumberDataPoint function to create new instances. +// Important: zero-initialized instance is not valid for use. type NumberDataPoint = internal.NumberDataPoint // NewNumberDataPoint is an alias for a function to create a new empty NumberDataPoint. var NewNumberDataPoint = internal.NewNumberDataPoint -// HistogramDataPointSlice is an alias for internal.HistogramDataPointSlice struct. +// HistogramDataPointSlice logically represents a slice of HistogramDataPoint. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewHistogramDataPointSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type HistogramDataPointSlice = internal.HistogramDataPointSlice -// NewHistogramDataPointSlice is an alias for a function to create HistogramDataPointSlice. +// NewHistogramDataPointSlice creates a HistogramDataPointSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewHistogramDataPointSlice = internal.NewHistogramDataPointSlice -// HistogramDataPoint is an alias for internal.HistogramDataPoint struct. +// HistogramDataPoint is a single data point in a timeseries that describes the time-varying values of a Histogram of values. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewHistogramDataPoint function to create new instances. +// Important: zero-initialized instance is not valid for use. type HistogramDataPoint = internal.HistogramDataPoint // NewHistogramDataPoint is an alias for a function to create a new empty HistogramDataPoint. var NewHistogramDataPoint = internal.NewHistogramDataPoint -// ExponentialHistogramDataPointSlice is an alias for internal.ExponentialHistogramDataPointSlice struct. +// ExponentialHistogramDataPointSlice logically represents a slice of ExponentialHistogramDataPoint. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewExponentialHistogramDataPointSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ExponentialHistogramDataPointSlice = internal.ExponentialHistogramDataPointSlice -// NewExponentialHistogramDataPointSlice is an alias for a function to create ExponentialHistogramDataPointSlice. +// NewExponentialHistogramDataPointSlice creates a ExponentialHistogramDataPointSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewExponentialHistogramDataPointSlice = internal.NewExponentialHistogramDataPointSlice -// ExponentialHistogramDataPoint is an alias for internal.ExponentialHistogramDataPoint struct. +// ExponentialHistogramDataPoint is a single data point in a timeseries that describes the +// time-varying values of a ExponentialHistogram of double values. A ExponentialHistogram contains +// summary statistics for a population of values, it may optionally contain the +// distribution of those values across a set of buckets. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewExponentialHistogramDataPoint function to create new instances. +// Important: zero-initialized instance is not valid for use. type ExponentialHistogramDataPoint = internal.ExponentialHistogramDataPoint // NewExponentialHistogramDataPoint is an alias for a function to create a new empty ExponentialHistogramDataPoint. var NewExponentialHistogramDataPoint = internal.NewExponentialHistogramDataPoint -// Buckets is an alias for internal.Buckets struct. +// Buckets are a set of bucket counts, encoded in a contiguous array of counts. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewBuckets function to create new instances. +// Important: zero-initialized instance is not valid for use. type Buckets = internal.Buckets // NewBuckets is an alias for a function to create a new empty Buckets. var NewBuckets = internal.NewBuckets -// SummaryDataPointSlice is an alias for internal.SummaryDataPointSlice struct. +// SummaryDataPointSlice logically represents a slice of SummaryDataPoint. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewSummaryDataPointSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type SummaryDataPointSlice = internal.SummaryDataPointSlice -// NewSummaryDataPointSlice is an alias for a function to create SummaryDataPointSlice. +// NewSummaryDataPointSlice creates a SummaryDataPointSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewSummaryDataPointSlice = internal.NewSummaryDataPointSlice -// SummaryDataPoint is an alias for internal.SummaryDataPoint struct. +// SummaryDataPoint is a single data point in a timeseries that describes the time-varying values of a Summary of double values. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewSummaryDataPoint function to create new instances. +// Important: zero-initialized instance is not valid for use. type SummaryDataPoint = internal.SummaryDataPoint // NewSummaryDataPoint is an alias for a function to create a new empty SummaryDataPoint. var NewSummaryDataPoint = internal.NewSummaryDataPoint -// ValueAtQuantileSlice is an alias for internal.ValueAtQuantileSlice struct. +// ValueAtQuantileSlice logically represents a slice of ValueAtQuantile. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewValueAtQuantileSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ValueAtQuantileSlice = internal.ValueAtQuantileSlice -// NewValueAtQuantileSlice is an alias for a function to create ValueAtQuantileSlice. +// NewValueAtQuantileSlice creates a ValueAtQuantileSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewValueAtQuantileSlice = internal.NewValueAtQuantileSlice -// ValueAtQuantile is an alias for internal.ValueAtQuantile struct. +// ValueAtQuantile is a quantile value within a Summary data point. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewValueAtQuantile function to create new instances. +// Important: zero-initialized instance is not valid for use. type ValueAtQuantile = internal.ValueAtQuantile // NewValueAtQuantile is an alias for a function to create a new empty ValueAtQuantile. var NewValueAtQuantile = internal.NewValueAtQuantile -// ExemplarSlice is an alias for internal.ExemplarSlice struct. +// ExemplarSlice logically represents a slice of Exemplar. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewExemplarSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ExemplarSlice = internal.ExemplarSlice -// NewExemplarSlice is an alias for a function to create ExemplarSlice. +// NewExemplarSlice creates a ExemplarSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewExemplarSlice = internal.NewExemplarSlice -// Exemplar is an alias for internal.Exemplar struct. +// Exemplar is a sample input double measurement. +// +// Exemplars also hold information about the environment when the measurement was recorded, +// for example the span and trace ID of the active span when the exemplar was recorded. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewExemplar function to create new instances. +// Important: zero-initialized instance is not valid for use. type Exemplar = internal.Exemplar // NewExemplar is an alias for a function to create a new empty Exemplar. diff --git a/pdata/ptrace/alias.go b/pdata/ptrace/alias.go index 00b4f4bcbaa..331f52c5e77 100644 --- a/pdata/ptrace/alias.go +++ b/pdata/ptrace/alias.go @@ -18,32 +18,59 @@ import "go.opentelemetry.io/collector/pdata/internal" // This file contains aliases for trace data structures. -// Traces is an alias for internal.Traces struct. +// Traces is the top-level struct that is propagated through the traces pipeline. +// Use NewTraces to create new instance, zero-initialized instance is not valid for use. type Traces = internal.Traces -// NewTraces is an alias for a function to create new Traces. +// NewTraces creates a new Traces struct. var NewTraces = internal.NewTraces -// TraceState is an alias for internal.TraceState type. +// TraceState is a string representing the tracestate in w3c-trace-context format: https://www.w3.org/TR/trace-context/#tracestate-header type TraceState = internal.TraceState const ( + // TraceStateEmpty represents the empty TraceState. TraceStateEmpty = internal.TraceStateEmpty ) -// SpanKind is an alias for internal.SpanKind type. +// SpanKind is the type of span. Can be used to specify additional relationships between spans +// in addition to a parent/child relationship. type SpanKind = internal.SpanKind const ( + // SpanKindUnspecified represents that the SpanKind is unspecified, it MUST NOT be used. SpanKindUnspecified = internal.SpanKindUnspecified - SpanKindInternal = internal.SpanKindInternal - SpanKindServer = internal.SpanKindServer - SpanKindClient = internal.SpanKindClient - SpanKindProducer = internal.SpanKindProducer - SpanKindConsumer = internal.SpanKindConsumer + + // SpanKindInternal indicates that the span represents an internal operation within an application, + // as opposed to an operation happening at the boundaries. Default value. + SpanKindInternal = internal.SpanKindInternal + + // SpanKindServer indicates that the span covers server-side handling of an RPC or other + // remote network request. + SpanKindServer = internal.SpanKindServer + + // SpanKindProducer indicates that the span describes a producer sending a message to a broker. + // Unlike CLIENT and SERVER, there is often no direct critical path latency relationship + // between producer and consumer spans. + // A PRODUCER span ends when the message was accepted by the broker while the logical processing of + // the message might span a much longer time. + SpanKindClient = internal.SpanKindClient + + // SpanKindProducer indicates that the span describes a producer sending a message to a broker. + // Unlike CLIENT and SERVER, there is often no direct critical path latency relationship + // between producer and consumer spans. + // A PRODUCER span ends when the message was accepted by the broker while the logical processing of + // the message might span a much longer time. + SpanKindProducer = internal.SpanKindProducer + + // SpanKindConsumer indicates that the span describes consumer receiving a message from a broker. + // Like the PRODUCER kind, there is often no direct critical path latency relationship between + // producer and consumer spans. + SpanKindConsumer = internal.SpanKindConsumer ) -// StatusCode is an alias for internal.StatusCode type. +// StatusCode mirrors the codes defined at +// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status type StatusCode = internal.StatusCode const ( diff --git a/pdata/ptrace/generated_alias.go b/pdata/ptrace/generated_alias.go index 68313a528c6..e932ad1e0e0 100644 --- a/pdata/ptrace/generated_alias.go +++ b/pdata/ptrace/generated_alias.go @@ -19,67 +19,143 @@ package ptrace import "go.opentelemetry.io/collector/pdata/internal" -// ResourceSpansSlice is an alias for internal.ResourceSpansSlice struct. +// ResourceSpansSlice logically represents a slice of ResourceSpans. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewResourceSpansSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ResourceSpansSlice = internal.ResourceSpansSlice -// NewResourceSpansSlice is an alias for a function to create ResourceSpansSlice. +// NewResourceSpansSlice creates a ResourceSpansSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewResourceSpansSlice = internal.NewResourceSpansSlice -// ResourceSpans is an alias for internal.ResourceSpans struct. +// ResourceSpans is a collection of spans from a Resource. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewResourceSpans function to create new instances. +// Important: zero-initialized instance is not valid for use. type ResourceSpans = internal.ResourceSpans // NewResourceSpans is an alias for a function to create a new empty ResourceSpans. var NewResourceSpans = internal.NewResourceSpans -// ScopeSpansSlice is an alias for internal.ScopeSpansSlice struct. +// ScopeSpansSlice logically represents a slice of ScopeSpans. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewScopeSpansSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type ScopeSpansSlice = internal.ScopeSpansSlice -// NewScopeSpansSlice is an alias for a function to create ScopeSpansSlice. +// NewScopeSpansSlice creates a ScopeSpansSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewScopeSpansSlice = internal.NewScopeSpansSlice -// ScopeSpans is an alias for internal.ScopeSpans struct. +// ScopeSpans is a collection of spans from a LibraryInstrumentation. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewScopeSpans function to create new instances. +// Important: zero-initialized instance is not valid for use. type ScopeSpans = internal.ScopeSpans // NewScopeSpans is an alias for a function to create a new empty ScopeSpans. var NewScopeSpans = internal.NewScopeSpans -// SpanSlice is an alias for internal.SpanSlice struct. +// SpanSlice logically represents a slice of Span. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewSpanSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type SpanSlice = internal.SpanSlice -// NewSpanSlice is an alias for a function to create SpanSlice. +// NewSpanSlice creates a SpanSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewSpanSlice = internal.NewSpanSlice -// Span is an alias for internal.Span struct. +// Span represents a single operation within a trace. +// See Span definition in OTLP: https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewSpan function to create new instances. +// Important: zero-initialized instance is not valid for use. type Span = internal.Span // NewSpan is an alias for a function to create a new empty Span. var NewSpan = internal.NewSpan -// SpanEventSlice is an alias for internal.SpanEventSlice struct. +// SpanEventSlice logically represents a slice of SpanEvent. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewSpanEventSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type SpanEventSlice = internal.SpanEventSlice -// NewSpanEventSlice is an alias for a function to create SpanEventSlice. +// NewSpanEventSlice creates a SpanEventSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewSpanEventSlice = internal.NewSpanEventSlice -// SpanEvent is an alias for internal.SpanEvent struct. +// SpanEvent is a time-stamped annotation of the span, consisting of user-supplied +// text description and key-value pairs. See OTLP for event definition. +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewSpanEvent function to create new instances. +// Important: zero-initialized instance is not valid for use. type SpanEvent = internal.SpanEvent // NewSpanEvent is an alias for a function to create a new empty SpanEvent. var NewSpanEvent = internal.NewSpanEvent -// SpanLinkSlice is an alias for internal.SpanLinkSlice struct. +// SpanLinkSlice logically represents a slice of SpanLink. +// +// This is a reference type. If passed by value and callee modifies it, the +// caller will see the modification. +// +// Must use NewSpanLinkSlice function to create new instances. +// Important: zero-initialized instance is not valid for use. type SpanLinkSlice = internal.SpanLinkSlice -// NewSpanLinkSlice is an alias for a function to create SpanLinkSlice. +// NewSpanLinkSlice creates a SpanLinkSlice with 0 elements. +// Can use "EnsureCapacity" to initialize with a given capacity. var NewSpanLinkSlice = internal.NewSpanLinkSlice -// SpanLink is an alias for internal.SpanLink struct. +// SpanLink is a pointer from the current span to another span in the same trace or in a +// different trace. +// See Link definition in OTLP: https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewSpanLink function to create new instances. +// Important: zero-initialized instance is not valid for use. type SpanLink = internal.SpanLink // NewSpanLink is an alias for a function to create a new empty SpanLink. var NewSpanLink = internal.NewSpanLink -// SpanStatus is an alias for internal.SpanStatus struct. +// SpanStatus is an optional final status for this span. Semantically, when Status was not +// set, that means the span ended without errors and to assume Status.Ok (code = 0). +// +// This is a reference type, if passed by value and callee modifies it the +// caller will see the modification. +// +// Must use NewSpanStatus function to create new instances. +// Important: zero-initialized instance is not valid for use. type SpanStatus = internal.SpanStatus // NewSpanStatus is an alias for a function to create a new empty SpanStatus.