Improved file_format documentation (#137)

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+* Improved file_format documentation. [#137](https://github.com/open-telemetry/opentelemetry-configuration/pull/137)
+
 ## [v0.3.0] - 2024-05-08
 
 * Add metric producers to meter_provider configuration. [#90](https://github.com/open-telemetry/opentelemetry-configuration/pull/90)

examples/kitchen-sink.yaml

@@ -6,6 +6,8 @@
 # Configuration values are set to their defaults when default values are defined.
 
 # The file format version.
+# The yaml format is documented at
+# https://github.com/open-telemetry/opentelemetry-configuration/tree/main/schema
 file_format: "0.3"
 
 # Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled.
@@ -323,7 +325,7 @@ tracer_provider:
 # Configure resource for all signals.
 resource:
   # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
-  # Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
+  # Entries must contain .name and .value, and may optionally include .type, which defaults to "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
   attributes:
     - name: service.name
       value: unknown_service

examples/sdk-config.yaml

@@ -6,6 +6,8 @@
 # vars defined in https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/.
 
 # The file format version.
+# The yaml format is documented at
+# https://github.com/open-telemetry/opentelemetry-configuration/tree/main/schema
 file_format: "0.3"
 
 # Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled.
@@ -14,7 +16,7 @@ disabled: false
 # Configure resource for all signals.
 resource:
   # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
-  # Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
+  # Entries must contain .name and .value, and may optionally include .type, which defaults to "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
   attributes:
     - name: service.name
       value: unknown_service

examples/sdk-migration-config.yaml

@@ -34,7 +34,9 @@
 # - OTEL_EXPORTER_OTLP_COMPRESSION
 # - OTEL_EXPORTER_OTLP_TIMEOUT
 
-# The file format version The file format version.
+# The file format version.
+# The yaml format is documented at
+# https://github.com/open-telemetry/opentelemetry-configuration/tree/main/schema
 file_format: "0.3"
 
 # Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled.
@@ -43,7 +45,7 @@ disabled: ${OTEL_SDK_DISABLED:-false}
 # Configure resource for all signals.
 resource:
   # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
-  # Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
+  # Entries must contain .name and .value, and may optionally include .type, which defaults to "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
   attributes:
     - name: service.name
       value: ${OTEL_SERVICE_NAME:-unknown_service}

schema/type_descriptions.yaml

@@ -13,7 +13,12 @@
 # START OpenTelemetryConfiguration
 - type: OpenTelemetryConfiguration
   property_descriptions:
-    file_format: The file format version.
+    file_format: >
+      The file format version.
+
+      The yaml format is documented at
+
+      https://github.com/open-telemetry/opentelemetry-configuration/tree/main/schema
     disabled: Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled.
     resource: Configure resource for all signals.
     propagator: Configure text map context propagators.
@@ -30,7 +35,7 @@
     attributes: >
       Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
       
-      Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
+      Entries must contain .name and .value, and may optionally include .type, which defaults to "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
     attributes_list: >
       Configure resource attributes. Entries have lower priority than entries from .resource.attributes.