From d3d4bb8418a90647aac504fd800a30ae038e88c3 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 19 Sep 2025 12:27:23 +0200 Subject: [PATCH 01/13] docs --- docs/config.md | 2 + docs/file-based-configuration.md | 65 ++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 docs/file-based-configuration.md diff --git a/docs/config.md b/docs/config.md index 26b76aab57..9655fd4ebe 100644 --- a/docs/config.md +++ b/docs/config.md @@ -45,6 +45,8 @@ with environment variables taking precedence over `App.config` or `Web.config` f `SiteName\VirtualPath` ex: `MySite\MyApp` - If that is not the case it will use the name of the application [entry Assembly](https://learn.microsoft.com/en-us/dotnet/api/system.reflection.assembly.getentryassembly?view=net-7.0). +4. [File-based Configuration (Experimental)](file-based-configuration.md) + By default we recommend using environment variables for configuration. However, if given setting supports it, then: diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md new file mode 100644 index 0000000000..7685c82d1e --- /dev/null +++ b/docs/file-based-configuration.md @@ -0,0 +1,65 @@ +# File-based Configuration + +> **Status:** [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) +> For more information about the OpenTelemetry configuration specification, see: +> **[File-based configuration documentation](https://opentelemetry.io/docs/specs/otel/configuration/sdk/)** + +You can configure OpenTelemetry using a YAML file. This method is disabled +by default and must be explicitly enabled. + +To enable file-based configuration, set the following environment variable: + +```bash +OTEL_EXPERIMENTAL_FILE_BASED_CONFIGURATION_ENABLED=true +``` + +By default, the value is false. + +You can also specify the configuration file path (default: config.yaml): + +```bash +OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/config.yaml +``` + +In your config file you can use environment variables in the format `${ENVIRONMENT_VARIABLE}` +instead of a fixed value. + +You can also use `${ENVIRONMENT_VARIABLE:-value}`, where `value` is the fallback +if the environment variable is empty or not set. + +## Configuration Examples + +### Resource Configuration + +You can configure resource attributes directly in YAML or via the +`OTEL_RESOURCE_ATTRIBUTES` environment variable. + +``` yaml +resource: +# Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. +# Entries must contain .name and .value, and may optionally include .type. If an entry's .type omitted or null, string is used. +# The .value's type 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 + type: string + # Alternatively, configure via a comma-separated list (same format as OTEL_RESOURCE_ATTRIBUTES). + attributes_list: ${OTEL_RESOURCE_ATTRIBUTES} +``` + +### Resource Detectors Configuration + +For more details and updates, see: [Resource Detectors list and documentation](https://opentelemetry.io/docs/zero-code/dotnet/configuration/#resource-detectors) + +``` yaml +resource: + detection/development: + detectors: + azureappservice: # Detects Azure App Service resource information + container: # Detects container resource info (container.* attributes) [Core only] + host: # Detects host resource info (host.* attributes) + operatingsystem: # Detects OS-level attributes (os.*) + process: # Detects process-level attributes (process.*) + processruntime: # Detects process runtime attributes (process.runtime.*) + service: # Detects service.name and service.instance.id +``` From 81f95c7df459bb06d35cadcdaf780c8fed0815d1 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Wed, 24 Sep 2025 10:05:48 +0200 Subject: [PATCH 02/13] Remove reference to file-based configuration from documentation --- docs/config.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/config.md b/docs/config.md index 9655fd4ebe..26b76aab57 100644 --- a/docs/config.md +++ b/docs/config.md @@ -45,8 +45,6 @@ with environment variables taking precedence over `App.config` or `Web.config` f `SiteName\VirtualPath` ex: `MySite\MyApp` - If that is not the case it will use the name of the application [entry Assembly](https://learn.microsoft.com/en-us/dotnet/api/system.reflection.assembly.getentryassembly?view=net-7.0). -4. [File-based Configuration (Experimental)](file-based-configuration.md) - By default we recommend using environment variables for configuration. However, if given setting supports it, then: From 2ea3f70501e886a8cddc7b55311c8e472fe97f44 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Wed, 24 Sep 2025 10:16:07 +0200 Subject: [PATCH 03/13] remove `type` from resource configuration --- docs/file-based-configuration.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 7685c82d1e..bdae763153 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -36,13 +36,11 @@ You can configure resource attributes directly in YAML or via the ``` yaml resource: -# Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. -# Entries must contain .name and .value, and may optionally include .type. If an entry's .type omitted or null, string is used. -# The .value's type must match the .type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array. + # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. + # Entries must contain .name and .value attributes: - name: service.name value: unknown_service - type: string # Alternatively, configure via a comma-separated list (same format as OTEL_RESOURCE_ATTRIBUTES). attributes_list: ${OTEL_RESOURCE_ATTRIBUTES} ``` From ff3f42ac82ccc66f8d809641d939d6bf1d8a5adb Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Thu, 25 Sep 2025 13:07:39 +0200 Subject: [PATCH 04/13] update link to Resource Detectors documentation --- docs/file-based-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index bdae763153..675385e9ef 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -47,7 +47,7 @@ resource: ### Resource Detectors Configuration -For more details and updates, see: [Resource Detectors list and documentation](https://opentelemetry.io/docs/zero-code/dotnet/configuration/#resource-detectors) +For more details and updates, see: [Resource Detectors list and documentation](config.md/#resource-detectors) ``` yaml resource: From 86c66f378803a2150bfa74313f1487886fd666cd Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Thu, 25 Sep 2025 13:12:49 +0200 Subject: [PATCH 05/13] Add instructions for disabling detectors --- docs/file-based-configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 675385e9ef..dbc9dec577 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -48,6 +48,7 @@ resource: ### Resource Detectors Configuration For more details and updates, see: [Resource Detectors list and documentation](config.md/#resource-detectors) +To disable a resource detector, comment out or remove its corresponding entry. ``` yaml resource: From afcd67d6b838a46f3aa2b03f2c737a2e2f6427b3 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 26 Sep 2025 10:35:44 +0200 Subject: [PATCH 06/13] Update docs/file-based-configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- docs/file-based-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index dbc9dec577..98aaa9951b 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -2,7 +2,7 @@ > **Status:** [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) > For more information about the OpenTelemetry configuration specification, see: -> **[File-based configuration documentation](https://opentelemetry.io/docs/specs/otel/configuration/sdk/)** +> **[Configuration SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.49.0/specification/configuration/sdk.md)** You can configure OpenTelemetry using a YAML file. This method is disabled by default and must be explicitly enabled. From fd584eaa82ca66b20c2384524865f3088d0766f9 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 26 Sep 2025 10:35:53 +0200 Subject: [PATCH 07/13] Update docs/file-based-configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- docs/file-based-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 98aaa9951b..5d815ff6ee 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -1,7 +1,7 @@ # File-based Configuration > **Status:** [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) -> For more information about the OpenTelemetry configuration specification, see: +> For more information, see: > **[Configuration SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.49.0/specification/configuration/sdk.md)** You can configure OpenTelemetry using a YAML file. This method is disabled From e837dd4c01c006d2ab6f03e7b58ea3d58f7ae720 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 26 Sep 2025 10:36:34 +0200 Subject: [PATCH 08/13] Update docs/file-based-configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- docs/file-based-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 5d815ff6ee..84834799cf 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -15,7 +15,7 @@ OTEL_EXPERIMENTAL_FILE_BASED_CONFIGURATION_ENABLED=true By default, the value is false. -You can also specify the configuration file path (default: config.yaml): +You can also specify the configuration file path (default: `config.yaml`): ```bash OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/config.yaml From b95b753dffc23b8b1c8097439186618d90959061 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 26 Sep 2025 11:04:23 +0200 Subject: [PATCH 09/13] Add reference to YAML File Format Specification --- docs/file-based-configuration.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 84834799cf..755933060f 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -27,6 +27,9 @@ instead of a fixed value. You can also use `${ENVIRONMENT_VARIABLE:-value}`, where `value` is the fallback if the environment variable is empty or not set. +For more details about environment variables format, see: +[OpenTelemetry YAML File Format Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.49.0/specification/configuration/data-model.md#yaml-file-format). + ## Configuration Examples ### Resource Configuration From c09f25244aa18168549e55638b851f06ec936dce Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 26 Sep 2025 11:07:27 +0200 Subject: [PATCH 10/13] Refactor Resource Detectors section in file-based configuration documentation --- docs/file-based-configuration.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 755933060f..2e5ee284c3 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -37,6 +37,10 @@ For more details about environment variables format, see: You can configure resource attributes directly in YAML or via the `OTEL_RESOURCE_ATTRIBUTES` environment variable. +For more details and updates about Resource Detectors Configuration, see: +[Resource Detectors list and documentation](config.md/#resource-detectors) +To disable a resource detector, comment out or remove its corresponding entry. + ``` yaml resource: # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. @@ -46,15 +50,7 @@ resource: value: unknown_service # Alternatively, configure via a comma-separated list (same format as OTEL_RESOURCE_ATTRIBUTES). attributes_list: ${OTEL_RESOURCE_ATTRIBUTES} -``` - -### Resource Detectors Configuration - -For more details and updates, see: [Resource Detectors list and documentation](config.md/#resource-detectors) -To disable a resource detector, comment out or remove its corresponding entry. - -``` yaml -resource: + # Resource Detectors Configuration detection/development: detectors: azureappservice: # Detects Azure App Service resource information @@ -64,4 +60,4 @@ resource: process: # Detects process-level attributes (process.*) processruntime: # Detects process runtime attributes (process.runtime.*) service: # Detects service.name and service.instance.id -``` +``` From fcde65c1608f2422ed3a3d162390e9361ad73ab9 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 26 Sep 2025 11:14:49 +0200 Subject: [PATCH 11/13] Update docs/file-based-configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- docs/file-based-configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 2e5ee284c3..c2c5ac1436 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -4,8 +4,7 @@ > For more information, see: > **[Configuration SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.49.0/specification/configuration/sdk.md)** -You can configure OpenTelemetry using a YAML file. This method is disabled -by default and must be explicitly enabled. +You can configure OpenTelemetry using a YAML file. To enable file-based configuration, set the following environment variable: From 4989a78c4acb4399ab0c2d428413df24018b6d96 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Fri, 26 Sep 2025 11:15:58 +0200 Subject: [PATCH 12/13] update dosc --- docs/file-based-configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 2e5ee284c3..d918b9e7d7 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -27,8 +27,7 @@ instead of a fixed value. You can also use `${ENVIRONMENT_VARIABLE:-value}`, where `value` is the fallback if the environment variable is empty or not set. -For more details about environment variables format, see: -[OpenTelemetry YAML File Format Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.49.0/specification/configuration/data-model.md#yaml-file-format). +For more details, see: [OpenTelemetry YAML File Format Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.49.0/specification/configuration/data-model.md#yaml-file-format). ## Configuration Examples From 57d8ecf1d54476c902880c0d94239a696bce9525 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 29 Sep 2025 10:13:28 +0200 Subject: [PATCH 13/13] Enhance with default service.name and detector behavior --- docs/file-based-configuration.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/file-based-configuration.md b/docs/file-based-configuration.md index 7ddbb59343..9ef632ca60 100644 --- a/docs/file-based-configuration.md +++ b/docs/file-based-configuration.md @@ -43,6 +43,10 @@ To disable a resource detector, comment out or remove its corresponding entry. resource: # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. # Entries must contain .name and .value + # By default service.name is generated automatically if not explicitly configured. + # If the application is hosted on IIS in .NET Framework this will be SiteName\VirtualPath (e.g., MySite\MyApp). + # Otherwise, it will use the name of the application entry Assembly. + # You can override this value manually below. attributes: - name: service.name value: unknown_service @@ -50,6 +54,7 @@ resource: attributes_list: ${OTEL_RESOURCE_ATTRIBUTES} # Resource Detectors Configuration detection/development: + # If no detectors are specified, none will be added automatically. detectors: azureappservice: # Detects Azure App Service resource information container: # Detects container resource info (container.* attributes) [Core only] @@ -57,5 +62,4 @@ resource: operatingsystem: # Detects OS-level attributes (os.*) process: # Detects process-level attributes (process.*) processruntime: # Detects process runtime attributes (process.runtime.*) - service: # Detects service.name and service.instance.id ```