formatting

Author: zeitlinger

spring-declarative-configuration/README.md

@@ -1,35 +1,42 @@
 # Spring Boot Declarative Configuration Example
 
-This example demonstrates how to use [declarative configuration](https://opentelemetry.io/docs/specs/otel/configuration/#declarative-configuration)
-with the OpenTelemetry Spring Boot Starter to configure tracing, metrics, and logging for a Spring Boot application.
+This example demonstrates how to
+use [declarative configuration](https://opentelemetry.io/docs/specs/otel/configuration/#declarative-configuration)
+with the OpenTelemetry Spring Boot Starter to configure tracing, metrics, and logging for a Spring
+Boot application.
 
-Instead of using the OpenTelemetry Java Agent and an `otel-agent-config.yaml` file, this module uses the
+Instead of using the OpenTelemetry Java Agent, this module uses the
 [OpenTelemetry Spring Boot Starter](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-boot-autoconfigure)
 and configures declarative behavior via standard Spring Boot configuration in `application.yaml`.
 
-> **Requirement:** Declarative configuration via the Spring Boot Starter requires version **2.22.0 or newer** of the
+> **Requirement:** Declarative configuration via the Spring Boot Starter requires version **2.22.0
+or newer** of the
 > OpenTelemetry Spring Boot Starter.
 
 The main configuration file for this example is:
 
 - [`src/main/resources/application.yaml`](./src/main/resources/application.yaml)
 
 For the underlying declarative configuration schema and additional examples, see the
-[opentelemetry-configuration](https://github.com/open-telemetry/opentelemetry-configuration) repository.
-Remember that when you copy examples from that repository into a Spring Boot app, you must nest them under the
+[opentelemetry-configuration](https://github.com/open-telemetry/opentelemetry-configuration)
+repository.
+Remember that when you copy examples from that repository into a Spring Boot app, you must nest them
+under the
 `otel:` root node (two-space indentation for all keys shown below).
 
 This Spring Boot application includes two endpoints:
 
-- `/actuator/health` – A health check endpoint (from Spring Boot Actuator) that is configured to be **excluded** from tracing
+- `/actuator/health` – A health check endpoint (from Spring Boot Actuator) that is configured to be
+  **excluded** from tracing
 - `/api/example` – A simple API endpoint that **will be traced** normally
 
 ## End-to-End Instructions
 
 ### Prerequisites
 
 - Java 17 or higher
-- OpenTelemetry Spring Boot Starter **2.22.0+** on the classpath of this application (already configured in this
+- OpenTelemetry Spring Boot Starter **2.22.0+** on the classpath of this application (already
+  configured in this
   example’s build files)
 
 ### Step 1: Build the Application
@@ -44,8 +51,10 @@ This builds the Spring Boot fat JAR for the example application.
 
 ### Step 2: Run the Spring Boot Application
 
-Run the application as a normal Spring Boot JAR – no `-javaagent` flag and no separate `otel-agent-config.yaml` file
-are needed. Declarative configuration is picked up from `application.yaml` by the Spring Boot Starter.
+Run the application as a normal Spring Boot JAR – no `-javaagent` flag and no separate
+`otel-agent-config.yaml` file
+are needed. Declarative configuration is picked up from `application.yaml` by the Spring Boot
+Starter.
 
 ```bash
 java -jar build/libs/spring-declarative-configuration.jar
@@ -81,31 +90,36 @@ Check the application logs to see that:
 - Health check requests (`/actuator/health`) **do not** generate spans (dropped by sampler rules)
 - Requests to `/api/example` **do** generate spans and are exported to console and/or OTLP
 
-If you have an OTLP-compatible backend (e.g., the OpenTelemetry Collector, Jaeger, Tempo, etc.) listening on
+If you have an OTLP-compatible backend (e.g., the OpenTelemetry Collector, Jaeger, Tempo, etc.)
+listening on
 `http://localhost:4318`, you can inspect the exported telemetry there as well.
 
 ## Declarative Configuration with Spring Boot
 
-The declarative configuration used by this example lives in [`application.yaml`](./src/main/resources/application.yaml)
+The declarative configuration used by this example lives in [
+`application.yaml`](./src/main/resources/application.yaml)
 under the `otel:` root key.
 
 ```yaml
 otel:
-  # ... see src/main/resources/application.yaml for the full configuration
+# ... see src/main/resources/application.yaml for the full configuration
 ```
 
 This layout follows the declarative configuration schema defined in the
-[opentelemetry-configuration](https://github.com/open-telemetry/opentelemetry-configuration) repository, but adapted
+[opentelemetry-configuration](https://github.com/open-telemetry/opentelemetry-configuration)
+repository, but adapted
 for Spring Boot:
 
 - All OpenTelemetry configuration keys live under the `otel:` root
-- Configuration blocks from the reference repo (such as `tracer_provider`, `meter_provider`, `logger_provider`, etc.)
+- Configuration blocks from the reference repo (such as `tracer_provider`, `meter_provider`,
+  `logger_provider`, etc.)
   are indented by **two spaces** beneath `otel:`
 - The configuration is loaded via the OpenTelemetry Spring Boot Starter instead of the Java Agent
 
 ### Opting In with `file_format`
 
-Declarative configuration is **opt-in**. In this Spring Boot example, you enable declarative configuration by setting
+Declarative configuration is **opt-in**. In this Spring Boot example, you enable declarative
+configuration by setting
 `file_format` under `otel:` in `application.yaml`:
 
 ```yaml
@@ -120,7 +134,8 @@ If `file_format` is missing, declarative configuration is not applied.
 
 ### Example: Exporters and Sampler Rules (Spring Style)
 
-Below is a simplified view of the configuration used in this module. All keys are indented under `otel:` as required by
+Below is a simplified view of the configuration used in this module. All keys are indented under
+`otel:` as required by
 Spring Boot declarative configuration. Refer to the actual
 [`application.yaml`](./src/main/resources/application.yaml) for the complete version.
 
@@ -175,7 +190,8 @@ otel:
               endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:http://localhost:4318}/v1/logs
 ```
 
-This configuration is conceptually equivalent to the Java Agent example’s `rule_based_routing` sampler (from
+This configuration is conceptually equivalent to the Java Agent example’s `rule_based_routing`
+sampler (from
 `javaagent-declarative-configuration/otel-agent-config.yaml`):
 
 - It uses the `rule_based_routing` sampler contribution
@@ -187,18 +203,22 @@ This configuration is conceptually equivalent to the Java Agent example’s `rul
 
 ### Spring Boot Starter Version
 
-- Declarative configuration is supported by the OpenTelemetry Spring Boot Starter starting with version **2.22.0**
-- Ensure your dependencies use at least this version; otherwise, `file_format` and other declarative config features
+- Declarative configuration is supported by the OpenTelemetry Spring Boot Starter starting with
+  version **2.22.0**
+- Ensure your dependencies use at least this version; otherwise, `file_format` and other declarative
+  config features
   may be ignored
 
 ### Property Metadata and IDE Auto-Completion
 
-Most IDEs derive auto-completion for Spring properties from Spring Boot configuration metadata. At the time of this
+Most IDEs derive auto-completion for Spring properties from Spring Boot configuration metadata. At
+the time of this
 example, that metadata is primarily based on the **non-declarative** configuration schema.
 
 As a result:
 
-- Auto-suggested properties in IDEs may be incomplete or incorrect for declarative configuration under `otel:`
+- Auto-suggested properties in IDEs may be incomplete or incorrect for declarative configuration
+  under `otel:`
 - Some declarative configuration keys may not appear in auto-completion at all
 
 When in doubt:
@@ -209,7 +229,8 @@ When in doubt:
 
 ### Placeholder Default Values: `:` vs `:-`
 
-Spring Boot’s property placeholder syntax differs slightly from generic examples you might see in OpenTelemetry docs.
+Spring Boot’s property placeholder syntax differs slightly from generic examples you might see in
+OpenTelemetry docs.
 
 - Generic examples sometimes use `${VAR_NAME:-default}` for default values
 - **Spring Boot uses `:` instead of `:-`**
@@ -232,45 +253,54 @@ When copying configuration from non-Spring examples, always convert `:-` to `:`
 
 ## Declarative vs Programmatic Configuration
 
-Declarative configuration, as used in this example, allows you to express routing and sampling rules entirely in
+Declarative configuration, as used in this example, allows you to express routing and sampling rules
+entirely in
 configuration files. This is ideal for:
 
 - Operational teams that need to adjust sampling or filtering without changing code
-- Environments where configuration is managed externally (Kubernetes ConfigMaps, Spring Cloud Config, etc.)
+- Environments where configuration is managed externally (Kubernetes ConfigMaps, Spring Cloud
+  Config, etc.)
 
-For more advanced or dynamic scenarios, you can still use **programmatic** configuration. The `spring-native` module in
+For more advanced or dynamic scenarios, you can still use **programmatic** configuration. The
+`spring-native` module in
 this repository contains an example of this:
 
 - See `configureSampler` in
-  [`OpenTelemetryConfig`](../spring-native/src/main/java/io/opentelemetry/example/graal/OpenTelemetryConfig.java)
-- It uses `RuleBasedRoutingSampler` programmatically to drop spans for actuator endpoints (`/actuator*`), replicating
+  [
+  `OpenTelemetryConfig`](../spring-native/src/main/java/io/opentelemetry/example/graal/OpenTelemetryConfig.java)
+- It uses `RuleBasedRoutingSampler` programmatically to drop spans for actuator endpoints (
+  `/actuator*`), replicating
   the behavior we achieve declaratively via YAML in this module
 
-In many cases, you can start with declarative configuration (as in this module) and only fall back to programmatic
+In many cases, you can start with declarative configuration (as in this module) and only fall back
+to programmatic
 customization for highly dynamic or application-specific logic.
 
 ## Troubleshooting and Tips
 
 If the behavior is not what you expect, here are a few things to check:
 
 - **Health checks are still traced**
-  - Verify the `rules` section under `otel.tracer_provider.sampler.rule_based_routing` in `application.yaml`
-  - Ensure the `pattern` matches your actual actuator paths (e.g., `/actuator.*`)
-  - Confirm that `span_kind` is set to `SERVER` (or another correct span kind for your traffic)
+    - Verify the `rules` section under `otel.tracer_provider.sampler.rule_based_routing` in
+      `application.yaml`
+    - Ensure the `pattern` matches your actual actuator paths (e.g., `/actuator.*`)
+    - Confirm that `span_kind` is set to `SERVER` (or another correct span kind for your traffic)
 
 - **No spans are exported**
-  - Confirm that `otel.file_format` is set correctly (for example, `"1.0-rc.2"`)
-  - Check that at least one exporter is configured (e.g., `otlp_http` or `console`)
-  - Look for startup warnings or errors related to OpenTelemetry configuration
+    - Confirm that `otel.file_format` is set correctly (for example, `"1.0-rc.2"`)
+    - Check that at least one exporter is configured (e.g., `otlp_http` or `console`)
+    - Look for startup warnings or errors related to OpenTelemetry configuration
 
 - **Properties seem to be ignored**
-  - Make sure you are modifying the correct `application.yaml` for the active Spring profile
-  - Verify that all configuration keys are indented correctly under the `otel:` root
-  - Double-check that any placeholders use `:` for defaults (e.g., `${OTEL_EXPORTER_OTLP_ENDPOINT:http://localhost:4318}`)
+    - Make sure you are modifying the correct `application.yaml` for the active Spring profile
+    - Verify that all configuration keys are indented correctly under the `otel:` root
+    - Double-check that any placeholders use `:` for defaults (e.g.,
+      `${OTEL_EXPORTER_OTLP_ENDPOINT:http://localhost:4318}`)
 
 If issues persist, compare your configuration to:
 
 - This module’s [`application.yaml`](./src/main/resources/application.yaml)
-- The Java Agent example in [`javaagent-declarative-configuration`](../javaagent-declarative-configuration)
+- The Java Agent example in [
+  `javaagent-declarative-configuration`](../javaagent-declarative-configuration)
 - The reference schemas and examples in
   [opentelemetry-configuration](https://github.com/open-telemetry/opentelemetry-configuration)