Merge branch 'main' into main

.chloggen/codeboten_gensemconv-1.21.0.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: semconv
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Generated Semantic conventions 1.21.
+
+# One or more tracking issues or pull requests related to the change
+issues: [9056]
+
+# (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: []

VERSIONING.md

@@ -5,7 +5,55 @@ is designed so that the following goal can be achieved:
 
 **Users are provided a codebase of value that is stable and secure.**
 
-## Policy
+## Public API expectations
+
+The following public API expectations apply to all modules in opentelemetry-collector and opentelemetry-collector-contrib.
+As a general rule, stability guarantees of modules versioned as `v1` or higher are aligned with [Go 1 compatibility promise](https://go.dev/doc/go1compat).
+
+### General Go API considerations
+
+OpenTelemetry authors reserve the right to introduce API changes breaking compatibility between minor versions in the following scenarios:
+* **Struct literals.** It may be necessary to add new fields to exported structs in the API. Code that uses unkeyed
+  struct literals (such as pkg.T{3, "x"}) to create values of these types would fail to compile after such a change.
+  However, code that uses keyed literals (pkg.T{A: 3, B: "x"}) will continue to compile. We therefore recommend 
+  using OpenTelemetry collector structs with the keyed literals only.
+* **Methods.** As with struct fields, it may be necessary to add methods to types. Under some circumstances,
+  such as when the type is embedded in a struct along with another type, the addition of the new method may 
+  break the struct by creating a conflict with an existing method of the other embedded type. We cannot protect 
+  against this rare case and do not guarantee compatibility in such scenarios.
+* **Dot imports.** If a program imports a package using `import .`, additional names defined in the imported package
+  in future releases may conflict with other names defined in the program. We do not recommend the use of
+  `import .` with OpenTelemetry Collector modules.
+
+Unless otherwise specified in the documentation, the following may change in any way between minor versions:
+* **String representation**. The `String` method of any struct is intended to be human-readable and may change its output
+  in any way.
+* **Go version compatibility**. Removing support for an unsupported Go version is not considered a breaking change.
+* **OS version compatibility**. Removing support for an unsupported OS version is not considered a breaking change. Upgrading or downgrading OS version support per the [platform support](docs/platform-support.md) document is not considered a breaking change.
+* **Dependency updates**. Updating dependencies is not considered a breaking change except when their types are part of the
+public API or the update may change the behavior of applications in an incompatible way.
+
+### Configuration structures
+
+Configuration structures are part of the public API and backwards
+compatibility should be maintained through any changes made to configuration structures.
+
+Unless otherwise specified in the documentation, the following may change in any way between minor versions:
+* **Adding new fields to configuration structures**. Because configuration structures are typically instantiated through 
+unmarshalling a serialized representation of the structure, and not through structure literals, additive changes to 
+the set of exported fields in a configuration structure are not considered to break backward compatibility.
+* **Relaxing validation rules**. An invalid configuration struct as defined by its `Validate` method return value
+may become valid after a change to the validation rules.
+
+The following are explicitly considered to be breaking changes:
+* **Modifying struct tags related to serialization**. Struct tags used to configure serialization mechanisms (`yaml:`, 
+`mapstructure:`, etc) are part of the structure definition and must maintain compatibility to the same extent as the 
+structure.
+* **Making validation rules more strict**. A valid configuration struct as defined by its `Validate` method return value
+must continue to be valid after a change to the validation rules, except when the configuration struct would cause an error
+on its intended usage (e.g. when calling a method or when passed to any method or function in any module under opentelemetry-collector).
+
+## Versioning and module schema
 
 * Versioning of this project will be idiomatic of a Go project using [Go
   modules](https://golang.org/ref/mod#versions).
@@ -32,24 +80,14 @@ is designed so that the following goal can be achieved:
     * A single module should exist, rooted at the top level of this repository,
       that contains all packages provided for use outside this repository.
     * Additional modules may be created in this repository to provide for
-      isolation of build-time tools or other commands. Such modules should be
+      isolation of build-time tools, other commands or independent libraries. Such modules should be
       versioned in sync with the `go.opentelemetry.io/collector` module.
     * Experimental modules still under active development will be versioned with a major
       version of `v0` to imply the stability guarantee defined by
       [semver](https://semver.org/spec/v2.0.0.html#spec-item-4).
 
       > Major version zero (0.y.z) is for initial development. Anything MAY
       > change at any time. The public API SHOULD NOT be considered stable.
-
-    * Configuration structures should be considered part of the public API and backward
-      compatibility maintained through any changes made to configuration structures.
-         * Because configuration structures are typically instantiated through unmarshalling
-           a serialized representation of the structure, and not through structure literals,
-           additive changes to the set of exported fields in a configuration structure are
-           not considered to break backward compatibility.
-         * Struct tags used to configure serialization mechanisms (`yaml:`, `mapstructure:`, etc)
-           are to be considered part of the structure definition and must maintain compatibility
-           to the same extent as the structure.
 * Versioning of the associated [contrib
   repository](https://github.com/open-telemetry/opentelemetry-collector-contrib) of
   this project will be idiomatic of a Go project using [Go
@@ -72,14 +110,8 @@ is designed so that the following goal can be achieved:
           whenever you are using the module name).
         * If a module is version `v0` or `v1`, do not include the major version
           in either the module path or the import path.
-    * Configuration structures should be considered part of the public API and backward
-      compatibility maintained through any changes made to configuration structures.
-        * Because configuration structures are typically instantiated through unmarshalling
-          a serialized representation of the structure, and not through structure literals,
-          additive changes to the set of exported fields in a configuration structure are
-          not considered to break backward compatibility.
-    * Modules will be used to encapsulate receivers, processor, exporters,
-      extensions, and any other independent sets of related components.
+    * Modules will be used to encapsulate receivers, processors, exporters,
+      extensions, connectors and any other independent sets of related components.
         * Experimental modules still under active development will be versioned with a major
           version of `v0` to imply the stability guarantee defined by
           [semver](https://semver.org/spec/v2.0.0.html#spec-item-4).
@@ -102,17 +134,3 @@ is designed so that the following goal can be achieved:
     * Contrib modules will be kept up to date with this project's releases.
 * GitHub releases will be made for all releases.
 * Go modules will be made available at Go package mirrors.
-* Stability guaranties of modules versioned as `v1` or higher are aligned with [Go 1 compatibility 
-  promise](https://go.dev/doc/go1compat). OpenTelemetry authors reserve the right to introduce API changes breaking 
-  compatibility between minor versions in the following scenarios:
-    * **Struct literals.** It may be necessary to add new fields to exported structs in the API. Code that uses unkeyed
-      struct literals (such as pkg.T{3, "x"}) to create values of these types would fail to compile after such a change.
-      However, code that uses keyed literals (pkg.T{A: 3, B: "x"}) will continue to compile. We therefore recommend 
-      using OpenTelemetry collector structs with the keyed literals only.
-    * **Methods.** As with struct fields, it may be necessary to add methods to types. Under some circumstances,
-      such as when the type is embedded in a struct along with another type, the addition of the new method may 
-      break the struct by creating a conflict with an existing method of the other embedded type. We cannot protect 
-      against this rare case and do not guarantee compatibility in such scenarios.
-    * **Dot imports.** If a program imports a package using `import .`, additional names defined in the imported package
-      in future releases may conflict with other names defined in the program. We do not recommend the use of
-      `import .` with OpenTelemetry Collector modules.

semconv/template.j2

@@ -36,6 +36,9 @@ Examples: {{ attr.examples | pprint | trim("[]")  }}
 Note: {{ attr.note | render_markdown(paragraph="{0}", code="{0}", link="{1}", emphasis="{0}", strong="{0}") }}
 {%- endif %}
 {%- endmacro -%}
+{%- macro sentence_case(text) -%}
+    {{ text[0]|upper}}{{text[1:] }}
+{%- endmacro -%}
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
@@ -45,7 +48,7 @@ package semconv
 
 {% for semconv in semconvs -%}
 {%- if semconvs[semconv].attributes | rejectattr("ref") | selectattr("is_local") | sort(attribute=fqn) | length > 0 -%}
-// {{ semconvs[semconv].brief }}
+// {{ sentence_case(semconvs[semconv].brief | replace("This document defines ", "")) | wordwrap(76, break_long_words=false, break_on_hyphens=false, wrapstring="\n// ") }}
 const (
 {% for attr in semconvs[semconv].attributes if attr.is_local and not attr.ref -%}
     // {{ godoc(attr) | wordwrap | indent(3) | replace("   ", "\t// ") | replace("// //", "//") }}

semconv/v1.21.0/doc.go

@@ -0,0 +1,9 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Package semconv implements OpenTelemetry semantic conventions.
+//
+// OpenTelemetry semantic conventions are agreed standardized naming
+// patterns for OpenTelemetry things. This package represents the v1.21.0
+// version of the OpenTelemetry semantic conventions.
+package semconv // import "go.opentelemetry.io/collector/semconv/v1.21.0"