From 693c8889cb4b1667c1050891b69eb7b1b4f433f7 Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Wed, 19 Nov 2025 18:36:40 -0500 Subject: [PATCH] docs: misc docs updates --- CONTRIBUTING.md | 120 ++++++++++++++++++++++++------------------------ README.md | 39 ++++++++-------- 2 files changed, 79 insertions(+), 80 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f41b7c8..9949c292 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ for general information about the project. ## Schema modeling rules -The following rules are enforced when modeling the configuration schema. +The following rules are enforced when modeling the configuration schema. These rules must be enforced when making changes to the schema; however, changes to the rules are permitted. In other words, the [stability definition](./README.md#stability-definition) does not apply to the rules: so long as the stability definition is not violated for existing properties, the modeling rules guiding new properties may change. @@ -18,9 +18,9 @@ This is reflected in top level schema documents by setting `"$schema": "https:// ## What you see is what you get -The schema semantics should follow a "what you see is what you get" (or WYSIWYG) philosophy. Another way to frame this is that implementations should minimize the amount of magic which occurs as a result of the absence of an optional property. +The schema semantics should follow a "what you see is what you get" (or WYSIWYG) philosophy. Another way to frame this is that implementations should minimize the amount of magic that occurs as a result of the absence of an optional property. -For example, in the following snippet `.meter_provider` is not set and the semantics indicate that a noop meter provider should be used, rather than some default meter provider definitions with a periodic metric reader and OTLP exporter. WYSIWYG: there is no `.meter_provider` and you get the closest equivalent to an empty / null / unset meter provider. +For example, in the following snippet `.meter_provider` is not set and the semantics indicate that a noop meter provider should be used, rather than some default meter provider definitions with a periodic metric reader and OTLP exporter. WYSIWYG: there is no `.meter_provider` and you get the closest equivalent to an empty / null / unset meter provider. ```yaml resource: @@ -30,25 +30,25 @@ logger_provider: ... propagators: ... ``` -It's not always possible to follow this philosophy. For example, when `.attribute_limits` is not set, the SDK defaults to using `.attribute_limits.attribute_count_limit: 128` where a rigid interpretation of WYSIWYG would suggest the defaults should be no limit. In this case we have competing concerns: WYSIWYG is in tension with a safe default experience for users, and with the defaults as indicated in the specification. +It's not always possible to follow this philosophy. For example, when `.attribute_limits` is not set, the SDK defaults to using `.attribute_limits.attribute_count_limit: 128`, whereas a rigid interpretation of WYSIWYG would suggest the default should be no limit. In this case we have competing concerns: WYSIWYG is in tension with a safe default experience for users, and with the defaults as indicated in the specification. -If it seems difficult to define default semantics which satisfy WYSIWYG, consider making the property required, which prevents the need to define default semantics. +If it seems difficult to define default semantics that satisfy WYSIWYG, consider making the property required, which prevents the need to define default semantics. -NOTE: Doing extra configuration work when properties are not explicitly configured is attractive because it reduces required configuration. However, it increases the cognitive load on users, who now have to reference potentially multiple external documents to understand what to expect in the absence of a property. WYSIWYG results in configuration files which are more verbose but which are more self-documenting. A terse user experience can be achieved by leveraging a higher order templating tool like [helm](https://helm.sh/), where a simplified set of configuration parameters can be interpreted by a template engine to output the full configuration file. For example, the [OpenTelemetry Collector Helm Chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-collector) accepts a number of presets like `.presets.hostMetrics.enabled: true`, which produce much more verbose collector configuration YAML. +NOTE: Doing extra configuration work when properties are not explicitly configured is attractive because it reduces required configuration. However, it increases the cognitive load on users, who now have to reference potentially multiple external documents to understand what to expect in the absence of a property. WYSIWYG results in configuration files that are more verbose but are more self-documenting. A terse user experience can be achieved by leveraging a higher order templating tool like [helm](https://helm.sh/), where a simplified set of configuration parameters can be interpreted by a template engine to output the full configuration file. For example, the [OpenTelemetry Collector Helm Chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-collector) accepts a number of presets like `.presets.hostMetrics.enabled: true`, which produce much more verbose collector configuration YAML. ### What properties are part of schema? -Only properties which are described in [opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification) or [semantic-conventions](https://github.com/open-telemetry/semantic-conventions) are modeled in the schema. However, it's acceptable to allow additional properties specific to a particular language or implementation, and not covered by the schema. Model these by setting `"additionalProperties": true` (see [JSON schema additionalProperties](https://json-schema.org/understanding-json-schema/reference/object#additionalproperties)). Types should set `"additionalProperties": false` by default unless requested by an opentelemetry component [maintainer](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer) which supports additional options. +Only properties that are described in [opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification) or [semantic-conventions](https://github.com/open-telemetry/semantic-conventions) are modeled in the schema. However, it's acceptable to allow additional properties specific to a particular language or implementation, which are not covered by the schema. Model these by setting `"additionalProperties": true` (see [JSON schema additionalProperties](https://json-schema.org/understanding-json-schema/reference/object#additionalproperties)). Types should set `"additionalProperties": false` by default unless requested by an OpenTelemetry component [maintainer](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer) to support additional options. ### Property naming -To remove redundant information from the configuration file, prefixes for data produced by each of the providers will be removed from configuration options. For example, under the `meter_provider` configuration, metric readers are identified by the word `readers` rather than by `metric_readers`. Similarly, the prefix `span_` will be dropped for tracer provider configuration, and `logrecord` for logger provider. +To remove redundant information from the configuration file, prefixes for data produced by each of the providers will be removed from configuration options. For example, under the `meter_provider` configuration, metric readers are identified by the word `readers` rather than by `metric_readers`. Similarly, the prefix `span_` will be dropped for `tracer_provider` configuration, and `logrecord` for `logger_provider`. ### Property name case Properties defined in the schema should be lower [snake case](https://en.wikipedia.org/wiki/Snake_case). -### Properties which pattern matching +### Properties requiring pattern matching When a property requires pattern matching, use wildcard `*` (match any number of any character, including none) and `?` (match any single character) instead of regex. If a single property with wildcards is likely to be insufficient to model the configuration requirements, accept `included` and `excluded` properties, each with an array of strings with wildcard entries. The wildcard entries should be joined with a logical OR. If `included` is not specified, assume that all entries are included. Apply `excluded` after applying `included`. Examples: @@ -58,7 +58,7 @@ When a property requires pattern matching, use wildcard `*` (match any number of ### Data modeling and environment variable substitution -Properties should be modeled using the most appropriate data structures and types to represent the information. This may result in a schema which doesn't support env var substitution for the [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) where a type mismatch occurs. For example, the `OTEL_RESOURCE_ATTRIBUTES` env var is modeled as a string, consisting of a comma separated list of key-value pairs, which is not the natural way to model a mapping of key-value pairs in JSON schema. +Properties should be modeled using the most appropriate data structures and types to represent the information. This may result in a schema that doesn't support env var substitution for the [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) where a type mismatch occurs. For example, the `OTEL_RESOURCE_ATTRIBUTES` env var is modeled as a string, consisting of a comma separated list of key-value pairs, which is not the natural way to model a mapping of key-value pairs in JSON schema. In instances where there is a type mismatch between the JSON schema and equivalent standard env var, an alternative version of the property may be provided to resolve the mismatch. For example, resource attributes are configured at `.resource.attributes`, but `.resource.attributes_list` is available with a format matching that of `OTEL_RESOURCE_ATTRIBUTES`. Alternative properties are reserved for cases where there is a demonstrated need for platforms to be able to participate in configuration and there is no reasonable alternative. @@ -69,7 +69,7 @@ When a type requires a configurable list of name-value pairs (i.e. resource attr * Avoids user input as keys, which ensures conformity with the [snake_case properties](#property-name-case) rule. * Allows both the names and the values to be targets for [env var substitution]. For example: - ```yaml + ```yaml tracer_provider: processors: - batch: @@ -78,27 +78,27 @@ When a type requires a configurable list of name-value pairs (i.e. resource attr headers: - name: ${AUTHORIZATION_HEADER_NAME:-api-key} value: ${AUTHORIZATION_HEADER_VALUE} - ``` + ``` ### Required and null properties JSON schema has two related but subtly different concepts involved in indicating the requirement level of properties and values: * [`type` of `null`](https://json-schema.org/understanding-json-schema/reference/null): When a property includes a type of `null` along with other allowed types (i.e. `"type": ["string", "null"]`), it indicates that even if the property key is present, the value may be omitted. This is useful in a variety of situations: - * When modeling properties with primitive types which are candidates for [env var substitution][], since allowing `null` means that the configuration is valid even if the referenced env var is undefined. - * When modeling objects which do not require any properties. In these cases, either no properties are required, or there are no properties and the presence of the property key expresses the desired state. -* [required](https://json-schema.org/understanding-json-schema/reference/object#required): When a property is `required`, the key must be included in the object or the configuration is invalid. Properties should be required when there is no well default semantic (i.e. it's not clear what the behavior is when the property is absent). + * When modeling properties with primitive types that are candidates for [env var substitution][], since allowing `null` means that the configuration is valid even if the referenced env var is undefined. + * When modeling objects that do not require any properties. In these cases, either no properties are required, or there are no properties and the presence of the property key expresses the desired state. +* [required](https://json-schema.org/understanding-json-schema/reference/object#required): When a property is `required`, the key must be included in the object or the configuration is invalid. Properties should be required when there is no well-known default semantic (i.e. it's not clear what the behavior is when the property is absent). For example: -``` +```yaml tracer_provider: - processors: + processors: - simple: exporter: console: - limits: - attribute_value_length_limit: ${OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT} + limits: + attribute_value_length_limit: ${OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT} ``` * `tracer_provider` is not required. When omitted, a noop tracer provider is used. @@ -107,7 +107,7 @@ tracer_provider: * `exporter`'s type is `object`. Setting `exporter` to `null` or any non-object value is invalid. * `console`'s type is `["object", "null"]`. The console exporter has no properties, and we should not force the user to set an empty object (i.e `console: {}`). * `limits` is not required. When omitted, default span limits are used. -* `limits`'s type is `object`. If a user includes the `limits` property, they must set at least one property. Settings `limits` to `null` is invalid. +* `limits`'s type is `object`. If a user includes the `limits` property, they must set at least one property. Setting `limits` to `null` is invalid. * `attributes_value_length_limit` is not required. If omitted, no attribute length limits are applied. * `attributes_value_length_limit`'s type is `["integer", "null]`. If null (i.e. because the `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is unset), no attribute length limits are applied. @@ -194,7 +194,7 @@ Another example: ### Array minItems -Because properties of type `array` are not candidates for [env var substitution], it typically does not make sense to allow the array to be empty. In some cases, an empty array likely corresponds to an accidental misconfiguration which should be detected and reported as an error. In other cases, an empty array is simply meaningless and the user is better off omitting the property altogether. +Because properties of type `array` are not candidates for [env var substitution], it typically does not make sense to allow the array to be empty. In some cases, an empty array likely corresponds to an accidental misconfiguration which should be detected and reported as an error. In other cases, an empty array is meaningless and the user is better off omitting the property altogether. For these reasons, [`minItems`](https://json-schema.org/understanding-json-schema/reference/array#length) is typically set to `1`. @@ -202,7 +202,7 @@ NOTE: there are some valid cases where an empty array is semantically meaningful ### Annotations - title and description -The JSON schema [`title` and `description` annotations](https://json-schema.org/understanding-json-schema/reference/annotations) are keywords which are not involved in validation. Instead, they act as a mechanism to help schemas be self-documenting, and may be used by code generation tools. +The JSON schema [`title` and `description` annotations](https://json-schema.org/understanding-json-schema/reference/annotations) are keywords that are not involved in validation. Instead, they act as a mechanism to help schemas be self-documenting, and may be used by code generation tools. Despite these potential benefits, these keywords should be omitted: @@ -250,7 +250,7 @@ Or a property can reference a subschema residing in a schema document's [$defs]( } ``` -In order to promote stylistic consistency and allow for reuse of concepts, `object` and `enum` types should be defined in either as a top level schema document or as a subschema in a schema document's `$defs`. +In order to promote stylistic consistency and allow for reuse of concepts, `object` and `enum` types should be defined either as a top level schema document or as a subschema in a schema document's `$defs`. ### SDK extension plugins @@ -258,7 +258,7 @@ In order to promote stylistic consistency and allow for reuse of concepts, `obje The [SpanExporter](schema-docs.md#spanexporter) schema is typical: -``` +```json ... "SpanExporter": { "type": "object", @@ -270,7 +270,7 @@ The [SpanExporter](schema-docs.md#spanexporter) schema is typical: "properties": { "otlp_http": { "$ref": "common.json#/$defs/OtlpHttpExporter" }, // additional built-in exporters omitted for brevity - } + } }, ``` @@ -280,9 +280,9 @@ Which results in YAML like: tracer_provider: processors: - batch: - exporter: + exporter: otlp_http: # set the span exporter to be the built-in OTLP http exporter - endpoint: http://exmaple/v1/traces + endpoint: http://example/v1/traces --- tracer_provider: processors: @@ -293,22 +293,22 @@ tracer_provider: ``` * The `SpanExporter` type requires exactly one property to be set (`"minProperties": 1`, `"maxProperties": 1`), and requires that property to have a value of type `object` or `null` (`"additionalProperties": {"type": ["object", "null"]}`). -* The property key refers to the `name` used to [register a ComponentProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#register-componentprovider). -* The property value is passed as configuration as `properties` when [ComponentProvodier Create Plugin](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#create-plugin) is called. -* `SpanExporter` has `properties` describing the names and schemas of built-in span exporters (i.e. those defined explicitly in the specification). +* The property key refers to the `name` used to [register a ComponentProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#register-componentprovider). +* The property value is passed as configuration as `properties` when [ComponentProvider Create Plugin](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#create-plugin) is called. +* `SpanExporter` has `properties` describing the names and schemas of built-in span exporters (i.e. those defined explicitly in the specification). ## Consistency Checks This repository has various checks to ensure the schema changes are valid. Before using: -- Install the latest LTS release of **[Node](https://nodejs.org/)**. +* Install the latest LTS release of **[Node](https://nodejs.org/)**. For example, using **[nvm][]** under Linux run: ```bash nvm install --lts ``` -- Install tooling packages: +* Install tooling packages: ```bash npm install @@ -325,15 +325,15 @@ make all [meta_schema_*.yaml](schema) files track schema details that don't fit neatly into the JSON schema including: * Property descriptions and semantics -* Track which types are SDK extension plugins +* Tracking of types that are SDK extension plugins * Implementation support status -The meta schema is broken across multiple files for improved maintainability: +The meta schema is broken up across multiple files for improved maintainability: * [meta_schema_types.yaml](#meta_schema_typesyaml) * [meta_schema_language_{language}.yaml](#meta_schema_language_languageyaml) -There are a variety of build tasks which intersect with the meta schema: +There are a variety of build tasks that intersect with the meta schema: * [make fix-meta-schema](#make-fix-meta-schema) * [make generate-markdown](#make-generate-markdown) @@ -351,7 +351,7 @@ Content looks like: properties: - property: attribute_value_length_limit description: | - Configure max attribute value size. + Configure max attribute value size. Value must be non-negative. If omitted or null, there is no limit. - type: OtlpHttpEncoding @@ -365,14 +365,14 @@ Content looks like: Notes: -* `[]` the document is an array of entries for each type in the JSON schema. +* `[]` is the document is an array of entries for each type in the JSON schema. * `[].type` is the name of the JSON schema type. **Maintained automatically by build tooling.** * `[].properties` is an array of entries for each property in the JSON schema type. Omitted for enum types. - * `[].properties[].property` the name of the property. **Maintained automatically by build tooling.** - * `[].properties[].description` the property description, including semantics and default behavior. + * `[].properties[].property` is the name of the property. **Maintained automatically by build tooling.** + * `[].properties[].description` is the property description, including semantics and default behavior. * `[].enumValues` is an array of entries for each enum value in the JSON schema type. Omitted for non-enum types. - * `[].enumValues[].enumValue` the name of the enum value. **Maintained automatically by build tooling.** - * `[].enumValues[].description` the enum value description. + * `[].enumValues[].enumValue` is the name of the enum value. **Maintained automatically by build tooling.** + * `[].enumValues[].description` is the enum value description. ### `meta_schema_language_{language}.yaml` @@ -398,18 +398,18 @@ Notes: * `.typeSupportStatuses` is an array with entries for each type in the JSON schema. * `.typeSupportStatuses[].type` is the name of the JSON schema type. **Maintained automatically by build tooling.** * `.typeSupportStatuses[].status` captures the support status of the type and all properties except overrides in `.typeSupportStatuses[].propertyOverrides`. See enum options below. - * `.typeSupportStatuses[].notes` optional additional notes on the implementation. - * `.typeSupportStatuses[].propertyOverrides` an array of properties which have different support statuses than the overall type as recorded in `.typeSupportStatuses[].status. Omitted for enum types. - * `.typeSupportStatuses[].propertyOverrides[].property` the name of the property whose support status is overridden. - * `.typeSupportStatuses[].propertyOverrides[].status` the overridden support status. See enum options below. - * `.typeSupportStatuses[].enumOverrides` an array of enum values which have different support statuses than the overall type as recorded in `.typeSupportStatuses[].status. Omitted for non-enum types. - * `.typeSupportStatuses[].enumOverrides[].enumValue` the name of the enum value whose support status is overridden. - * `.typeSupportStatuses[].enumOverrides[].status` the overridden support status. See enum options below. + * `.typeSupportStatuses[].notes` contains optional additional notes on the implementation. + * `.typeSupportStatuses[].propertyOverrides` is an array of properties which have different support statuses than the overall type as recorded in `.typeSupportStatuses[].status`. Omitted for enum types. + * `.typeSupportStatuses[].propertyOverrides[].property` is the name of the property whose support status is overridden. + * `.typeSupportStatuses[].propertyOverrides[].status` is the overridden support status. See enum options below. + * `.typeSupportStatuses[].enumOverrides` is an array of enum values which have different support statuses than the overall type as recorded in `.typeSupportStatuses[].status`. Omitted for non-enum types. + * `.typeSupportStatuses[].enumOverrides[].enumValue` is the name of the enum value whose support status is overridden. + * `.typeSupportStatuses[].enumOverrides[].status` is the overridden support status. See enum options below. * Status enum options, applicable to `.typeSupportStatuses[].status`, `.typeSupportStatuses[].propertyOverrides[].status`: * `unknown`: Language maintainer has not yet recorded a status. - * `suppported`: The type / property is supported by the language implementation. + * `supported`: The type / property is supported by the language implementation. * `not_implemented`: The type / property is not parsed / recognized by the language implementation because the concept is not yet implemented but should be eventually. - * `not_applicable`: The type / property is not parsed / recognized by the language implementation because the concept is not applicable. E.g. C++ specific instrumentation for Java. + * `not_applicable`: The type / property is not parsed / recognized by the language implementation because the concept is not applicable. E.g. C++ specific instrumentation for Java. * `ignored`: The type / property is not parsed / recognized by the language implementation despite the concept being available in the language's programmatic configuration API. ### `make fix-meta-schema` @@ -431,45 +431,45 @@ Ensures that the JSON schema and the meta schema are kept in sync: When this task adds new entries to the meta schema, they are stubbed out with `TODO` placeholders. Contributors should update these with sensible values. -**NOTE:** This task is run as part of build automation. If it produces changes which are not checked into version control, the build will fail. +**NOTE:** This task is run as part of build automation. If it produces changes that are not checked into version control, the build will fail. ### `make generate-markdown` Generates markdown at [schema-docs.md](./schema-docs.md) which summarizes a variety of useful information about JSON schema and meta schema in an easy to consume format. -**NOTE:** This task is run as part of build automation. If it produces changes which are not checked into version control, the build will fail. +**NOTE:** This task is run as part of build automation. If it produces changes that are not checked into version control, the build will fail. ### `make generate-descriptions` Annotates files in [./examples](./examples) with comments derived from the JSON schema and meta schema. -The `/examples` directory contains a variety of examples which are expected to be used as starter templates and as references. The JSON schema is insufficient in describing the expected behavior of a given config file. It's missing key details describing behavior semantics (such as defaults) which are essential for both users and implementers. This task ensures that all examples are correctly and consistently commented. +The `/examples` directory contains a variety of examples that are expected to be used as starter templates and as references. The JSON schema is insufficient in describing the expected behavior of a given config file. It's missing key details describing behavior semantics (such as defaults) which are essential for both users and implementers. This task ensures that all examples are correctly and consistently commented. -**NOTE:** This task is run as part of build automation. If it produces changes which are not checked into version control, the build will fail. +**NOTE:** This task is run as part of build automation. If it produces changes that are not checked into version control, the build will fail. To run against a single file: -- Install the latest LTS release of **[Node](https://nodejs.org/)**. +* Install the latest LTS release of **[Node](https://nodejs.org/)**. For example, using **[nvm][]** under Linux run: ```bash nvm install --lts ``` -- Install tooling packages: +* Install tooling packages: ```bash npm install ``` -- Run the script: +* Run the script: ```shell npm run-script generate-descriptions -- /absolute/path/to/input/file.yaml /absolute/path/to/output/file.yaml ``` Optionally, include the `--debug` parameter. This prints out information about -each key value pair, including the computed dot notation location, the matched +each key-value pair, including the computed dot notation location, the matched rule, the previous description, the new description, etc. ```shell @@ -484,7 +484,7 @@ A composite task which runs all meta schema tasks. A PR is ready to merge when: -* It has as least 1 approval from [codeowners](.github/CODEOWNERS) (TODO: bump to 2 when we have more codeowners) +* It has at least 1 approval from [codeowners](.github/CODEOWNERS) (TODO: bump to 2 when we have more codeowners) * There is no `request changes` from the [codeowners](.github/CODEOWNERS) * If a change to the schema, at least one [example](examples/) is updated to illustrate change * All required status checks pass @@ -492,7 +492,7 @@ A PR is ready to merge when: ### Labels -* [`breaking`](https://github.com/open-telemetry/opentelemetry-configuration/pulls?q=is%3Apr+label%3Abreaking+): applied to PRs which qualify as breaking changes according to the [stability definition](README.md#stability-definition), including breaking changes to [experimental features](README.md#experimental-features) which are allowed in minor versions. +* [`breaking`](https://github.com/open-telemetry/opentelemetry-configuration/pulls?q=is%3Apr+label%3Abreaking+): applied to PRs that qualify as breaking changes according to the [stability definition](README.md#stability-definition), including breaking changes to [experimental features](README.md#experimental-features) which are allowed in minor versions. [env var substitution]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/data-model.md#environment-variable-substitution [nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating diff --git a/README.md b/README.md index 452c763b..292fd45b 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@ This repository contains the JSON schema definitions of the OpenTelemetry [decla The [examples](./examples) directory contains a variety of sample configuration files to help get started and illustrate useful patterns. The following are noteworthy: -- [sdk-migration-config.yaml](./examples/sdk-migration-config.yaml): Includes env var substitution references to all [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) which map cleanly to declarative configuration (see notes in the example for the set of env vars which are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. This is a great starting point for transitioning from env var based configuration to file based configuration. -- [sdk-config.yaml](./examples/sdk-config.yaml): Represents the typical default configuration. This is a good starting point if you are not using env var based configuration or wish to transition fully to file based configuration. Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. +* [sdk-migration-config.yaml](./examples/sdk-migration-config.yaml): Includes env var substitution references to all [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) which map cleanly to declarative configuration (see notes in the example for the set of env vars that are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. This is a great starting point for transitioning from env var based configuration to file based configuration. +* [sdk-config.yaml](./examples/sdk-config.yaml): Represents the typical default configuration. This is a good starting point if you are not using env var based configuration or wish to transition fully to file based configuration. Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. ## Code generation @@ -24,7 +24,7 @@ go-jsonschema \ ## Stability definition -**NOTICE**: The stability definitions are applicable after this repository publishes a stable release (1.0.0). Currently, this repository is experimental and makes no stability guarantees. +**NOTICE**: The stability definitions are applicable after this repository publishes a stable release (1.0.0). Currently, this repository is experimental and makes no stability guarantees. This repository strictly follows [Semantic Versioning 2.0.0](https://semver.org/). This means that all releases have a version following the format `MAJOR.MINOR.PATCH`. @@ -54,9 +54,9 @@ Stable types provide the following guarantees. All types except those excluded i * Type property names will not change. * The `type` of properties will not change, except the allowed addition of `null`. * Type [title][annotation] will not change. -* Types will be not change to make validation more strict. Changes may occur if they make validation less strict. This applies to the following keywords. Examples are given, but they are not exhaustive. +* Types will not change to make validation more strict. Changes may occur if they make validation less strict. This applies to the following keywords. Examples are given, but they are not exhaustive. * [minLength, maxLength](https://json-schema.org/understanding-json-schema/reference/string): `minLength` will not increase and `maxLength` will not decrease. - * [pattern](https://json-schema.org/understanding-json-schema/reference/string#regexp): pattern will not become stricter. + * [pattern](https://json-schema.org/understanding-json-schema/reference/string#regexp): will not become stricter. * [format](https://json-schema.org/understanding-json-schema/reference/type#built-in-formats): will not change. * [multipleOf](https://json-schema.org/understanding-json-schema/reference/numeric#multiples): will not change. * [minimum, exclusiveMinimum, maximum, exclusiveMaximum](https://json-schema.org/understanding-json-schema/reference/numeric#range): `minimum`, `exclusiveMinimum` will not increase; `maximum`, `exclusiveMaximum` will not decrease. @@ -65,7 +65,7 @@ Stable types provide the following guarantees. All types except those excluded i * [propertyNames](https://json-schema.org/understanding-json-schema/reference/object#propertyNames): will not become stricter. * [minProperties, maxProperties](https://json-schema.org/understanding-json-schema/reference/object#size): `minProperties` will not increase, `maxProperties` will not decrease. * [required](https://json-schema.org/understanding-json-schema/reference/object#required): will not add additional entries. - * [contains, minContains, maxContains](https://json-schema.org/understanding-json-schema/reference/array#contains): will not become stricter. + * [contains, minContains, maxContains](https://json-schema.org/understanding-json-schema/reference/array#contains): will not become stricter. `minContains` will not increase; `maxContains` will not decrease. * [minItems, maxItems](https://json-schema.org/understanding-json-schema/reference/array#length): `minItems` will not increase, `maxItems` will not decrease. * [uniqueItems](https://json-schema.org/understanding-json-schema/reference/array#uniqueItems): will not go from `false` to `true`. * [enum](https://json-schema.org/understanding-json-schema/reference/enum): will not remove entries. @@ -75,7 +75,7 @@ Stable types provide the following guarantees. All types except those excluded i The following additive changes are allowed: -* Adding of new properties to existing types. +* Adding new properties to existing types. * Adding new types. * Changes that make property validation less strict. See above for examples. * Removing a property from `required`. @@ -88,17 +88,17 @@ Stability guarantees do not apply to [experimental features](#experimental-featu #### Experimental features -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). +Sometimes we need to experiment with new types and properties, e.g. when evaluating 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 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. +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. +Maintainers are not obligated to implement support for experimental properties and types. When they do, they are not obligated to maintain any stability guarantees. -End users should be cautious of adopting experimental properties and types, since in doing so they are subject to breaking changes in `MINOR` versions. +End users should be cautious of adopting experimental properties and types, since in doing so they are subject to breaking changes in `MINOR` versions. #### Extension points -The schema contains types which are designed for extension, as indicated by the presence of `"additionalProperties": true`. For example, [component provider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#register-componentprovider) provides mechanisms for referencing custom SDK extension components like exporters, processors, samplers, etc. The stability guarantees surrounding properties not explicitly defined in this repository is out of scope. Users should consult documentation for the components interpreting these additional properties and decide if their stability guarantees are sufficient for adoption. +The schema contains types that are designed for extension, as indicated by the presence of `"additionalProperties": true`. For example, [component provider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#register-componentprovider) provides mechanisms for referencing custom SDK extension components like exporters, processors, samplers, etc. The stability guarantees surrounding properties not explicitly defined in this repository are out of scope. Users should consult documentation for the components interpreting these additional properties and decide if their stability guarantees are sufficient for adoption. ### File format @@ -108,7 +108,7 @@ Given the [guarantees and allowed changes](#guarantees-and-allowed-changes), imp * The `file_format` `MAJOR` version aligns with the implementation `MAJOR` version, AND: * The `file_format` `MINOR` version is less than or equal to the implementation `MINOR` version: This is ideal, with versions maximally aligned. Despite this, an implementation might not support every property and type of its target version. - * The `file_format` `MINOR` version is greater than the implementation `MINOR` version: The implementation should detect and emit a warning since there may be configuration features the user specifies which the implementation does not understand. However, this is acceptable in many cases, and not terribly different from the ideal path where an implementation also might not support every configuration feature. + * The `file_format` `MINOR` version is greater than the implementation `MINOR` version: The implementation should detect and emit a warning since there may be configuration features the user specifies that the implementation does not understand. However, this is acceptable in many cases, and not terribly different from the ideal path where an implementation also might not support every configuration feature. * The `file_format` `MAJOR` version does not align with the implementation `MAJOR` version. The implementation should produce an error, since there may be breaking changes in the properties and semantics on how they are interpreted. Implementations may choose to temporarily support multiple major version to accommodate transitioning users. ## Contributing @@ -117,20 +117,19 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) ### Maintainers -- [Alex Boten](https://github.com/codeboten), Honeycomb -- [Jack Berg](https://github.com/jack-berg), Grafana Labs -- [Tristan Sloughter](https://github.com/tsloughter), MyDecisiveAI -- [Tyler Yahn](https://github.com/MrAlias), Splunk +* [Alex Boten](https://github.com/codeboten), Honeycomb +* [Jack Berg](https://github.com/jack-berg), Grafana Labs +* [Tristan Sloughter](https://github.com/tsloughter), MyDecisiveAI +* [Tyler Yahn](https://github.com/MrAlias), Splunk For more information about the maintainer role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer). ### Approvers -- [Brett McBride](https://github.com/brettmc), Deakin University -- [Marc Alff](https://github.com/marcalff), Oracle +* [Brett McBride](https://github.com/brettmc), Deakin University +* [Marc Alff](https://github.com/marcalff), Oracle For more information about the approver role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#approver). [annotation]: https://json-schema.org/understanding-json-schema/reference/annotations [env var substitution]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/data-model.md#environment-variable-substitution -