diff --git a/README.md b/README.md index ec951576..938f6bf3 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ Stability guarantees do not apply to [experimental features](#experimental-featu Sometimes we need to experiment with new types and properties. For example, to evaluate the configuration experience for experimental features in [opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification). -Experimental properties are denoted by a `*/(development|alpha|beta)` suffix (e.g.`foo/development`). The suffix indicates the property value and all types nested within it are exempt from stability guarantees, and are subject to breaking changes in minor versions. Experimental types have a [title](https://json-schema.org/understanding-json-schema/reference/annotations) prefixed with `Experimental*` (e.g. `ExperimentalFoo`). +Experimental properties are denoted by a `*/(development|alpha|beta)` suffix (e.g.`foo/development`). The suffix indicates the property value and all types nested within it are exempt from stability guarantees, and are subject to breaking changes in minor versions. Experimental type key values in `$defs` should be prefixed with `Experimental*` (e.g. `ExperimentalFoo`). Note that because we [omit the title annotation](./CONTRIBUTING.md#annotations---title-and-description), the `$defs` key value effectively acts as the type title for code generation tools. Maintainers are not obligated to implement support for experimental properties and types. When they do, they are no obligated to maintain any stability guarantees. diff --git a/examples/kitchen-sink.yaml b/examples/kitchen-sink.yaml index 9b458ece..fd74a1ed 100644 --- a/examples/kitchen-sink.yaml +++ b/examples/kitchen-sink.yaml @@ -700,7 +700,8 @@ resource: # If omitted or null, no schema URL is used. schema_url: https://opentelemetry.io/schemas/1.16.0 # Configure instrumentation. -instrumentation: +# This type is in development and subject to breaking changes in minor versions. +instrumentation/development: # Configure general SemConv options that may apply to multiple languages and instrumentations. # Instrumenation may merge general config options with the language specific configuration at .instrumentation.. general: diff --git a/schema/instrumentation.json b/schema/instrumentation.json index 4ad37156..b698ddd4 100644 --- a/schema/instrumentation.json +++ b/schema/instrumentation.json @@ -5,61 +5,61 @@ "additionalProperties": false, "properties": { "general": { - "$ref": "#/$defs/GeneralInstrumentation" + "$ref": "#/$defs/ExperimentalGeneralInstrumentation" }, "cpp": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "dotnet": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "erlang": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "go": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "java": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "js": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "php": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "python": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "ruby": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "rust": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" }, "swift": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" } }, "patternProperties": { ".*": { - "$ref": "#/$defs/LanguageSpecificInstrumentation" + "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation" } }, "$defs": { - "GeneralInstrumentation": { + "ExperimentalGeneralInstrumentation": { "type": "object", "additionalProperties": false, "properties": { "peer": { - "$ref": "#/$defs/PeerInstrumentation" + "$ref": "#/$defs/ExperimentalPeerInstrumentation" }, "http": { - "$ref": "#/$defs/HttpInstrumentation" + "$ref": "#/$defs/ExperimentalHttpInstrumentation" } } }, - "PeerInstrumentation": { + "ExperimentalPeerInstrumentation": { "type": "object", "additionalProperties": false, "properties": { @@ -84,7 +84,7 @@ } } }, - "HttpInstrumentation": { + "ExperimentalHttpInstrumentation": { "type": "object", "additionalProperties": false, "properties": { @@ -126,7 +126,7 @@ } } }, - "LanguageSpecificInstrumentation": { + "ExperimentalLanguageSpecificInstrumentation": { "type": "object", "additionalProperties": true, "patternProperties": { diff --git a/schema/opentelemetry_configuration.json b/schema/opentelemetry_configuration.json index 5da06794..1cd0dea9 100644 --- a/schema/opentelemetry_configuration.json +++ b/schema/opentelemetry_configuration.json @@ -32,8 +32,8 @@ "resource": { "$ref": "#/$defs/Resource" }, - "instrumentation": { - "$ref": "#/$defs/Instrumentation" + "instrumentation/development": { + "$ref": "#/$defs/ExperimentalInstrumentation" } }, "required": [ @@ -67,7 +67,7 @@ "Resource": { "$ref": "resource.json" }, - "Instrumentation": { + "ExperimentalInstrumentation": { "$ref": "instrumentation.json" } } diff --git a/schema/type_descriptions.yaml b/schema/type_descriptions.yaml index 0bf03a8d..4b0893da 100644 --- a/schema/type_descriptions.yaml +++ b/schema/type_descriptions.yaml @@ -48,7 +48,10 @@ Configure meter provider. If omitted, a noop meter provider is used. - instrumentation: Configure instrumentation. + instrumentation/development: > + Configure instrumentation. + + This type is in development and subject to breaking changes in minor versions. path_patterns: - . @@ -704,7 +707,7 @@ rust: Configure Rust language-specific instrumentation libraries. swift: Configure Swift language-specific instrumentation libraries. path_patterns: - - .instrumentation + - .instrumentation/development - type: GeneralInstrumentation property_descriptions: @@ -717,7 +720,7 @@ See http semantic conventions: https://opentelemetry.io/docs/specs/semconv/http/ path_patterns: - - .instrumentation.general + - .instrumentation/development.general - type: GeneralInstrumentationPeer property_descriptions: @@ -728,33 +731,33 @@ See peer.service semantic conventions: https://opentelemetry.io/docs/specs/semconv/general/attributes/#general-remote-service-attributes path_patterns: - - .instrumentation.general.peer + - .instrumentation/development.general.peer - type: GeneralInstrumentationHttp property_descriptions: client: Configure instrumentations following the http client semantic conventions. server: Configure instrumentations following the http server semantic conventions. path_patterns: - - .instrumentation.general.http + - .instrumentation/development.general.http - type: GeneralInstrumentationHttpClient property_descriptions: request_captured_headers: Configure headers to capture for outbound http requests. response_captured_headers: Configure headers to capture for outbound http responses. path_patterns: - - .instrumentation.general.http.client + - .instrumentation/development.general.http.client - type: GeneralInstrumentationHttpServer property_descriptions: request_captured_headers: Configure headers to capture for inbound http requests. response_captured_headers: Configure headers to capture for outbound http responses. path_patterns: - - .instrumentation.general.http.server + - .instrumentation/development.general.http.server - type: LanguageSpecificInstrumentation property_descriptions: example: Configure the instrumentation corresponding to key "example". path_patterns: - - .instrumentation.* + - .instrumentation/development.* # END Instrumentation