Merge branch 'theletterf-3929-add-collector-config-path' of github.com:open-telemetry/opentelemetry.io into theletterf-3929-add-collector-config-path

Author: theletterf

content/en/docs/languages/cpp/instrumentation.md

@@ -9,7 +9,7 @@ cSpell:ignore: decltype labelkv nostd nullptr
 
 <!-- markdownlint-disable no-duplicate-heading -->
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## Setup
 

content/en/docs/languages/erlang/instrumentation.md

@@ -5,7 +5,7 @@ weight: 30
 description: Instrumentation for OpenTelemetry Erlang/Elixir
 ---
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## Setup
 

content/en/docs/languages/go/instrumentation.md

@@ -8,7 +8,7 @@ description: Manual instrumentation for OpenTelemetry Go
 cSpell:ignore: fatalf otlptrace sdktrace sighup
 ---
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## Setup
 

content/en/docs/languages/java/instrumentation.md

@@ -13,7 +13,7 @@ cSpell:ignore: Autowired customizer logback loggable multivalued rolldice spring
 
 <!-- markdownlint-disable no-duplicate-heading -->
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 {{% alert title="Note" color="info" %}}
 
@@ -190,22 +190,47 @@ You should get a list of 12 numbers in your browser window, for example:
 For both library and app instrumentation, the first step is to install the
 dependencies for the OpenTelemetry API.
 
+Throughout this documentation you will add dependencies. For a full list of
+artifact coordinates, see [releases]. For semantic convention releases, see
+[semantic-conventions-java].
+
+[releases]: https://github.com/open-telemetry/opentelemetry-java#releases
+[semantic-conventions-java]:
+  https://github.com/open-telemetry/semantic-conventions-java/releases
+
+### Dependency management
+
+A Bill of Material
+([BOM](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms))
+ensures that versions of dependencies (including transitive ones) are aligned.
+Importing the `opentelemetry-bom` BOM is important to ensure version alignment
+across all OpenTelemetry dependencies.
+
 {{< tabpane text=true >}} {{% tab Gradle %}}
 
-```kotlin { hl_lines=3 }
+```kotlin { hl_lines=["1-5",9] }
+dependencyManagement {
+  imports {
+    mavenBom("io.opentelemetry:opentelemetry-bom:{{% param vers.otel %}}")
+  }
+}
+
 dependencies {
     implementation("org.springframework.boot:spring-boot-starter-web");
-    implementation("io.opentelemetry:opentelemetry-api:{{% param vers.otel %}}");
+    implementation("io.opentelemetry:opentelemetry-api");
 }
 ```
 
-Throughout this documentation you will add dependencies. For a full list of
-artifact coordinates, see [releases]. For semantic convention releases, see
-[semantic-conventions-java].
+If you are not using Spring and its `io.spring.dependency-management` dependency
+management plugin, install the OpenTelemetry BOM and API using Gradle
+dependencies only.
 
-[releases]: https://github.com/open-telemetry/opentelemetry-java#releases
-[semantic-conventions-java]:
-  https://github.com/open-telemetry/semantic-conventions-java/releases
+```kotlin
+dependencies {
+    implementation(platform("io.opentelemetry:opentelemetry-bom:{{% param vers.otel %}}"));
+    implementation("io.opentelemetry:opentelemetry-api");
+}
+```
 
 {{% /tab %}} {{% tab Maven %}}
 
@@ -238,50 +263,32 @@ artifact coordinates, see [releases]. For semantic convention releases, see
 {{% alert title="Note" color="info" %}} If you’re instrumenting a library,
 **skip this step**. {{% /alert %}}
 
-If you instrument a Java app, install the dependencies for the OpenTelemetry
-SDK.
+The OpenTelemetry API provides a set of interfaces for collecting telemetry, but
+the data is dropped without an implementation. The OpenTelemetry SDK is the
+implementation of the OpenTelemetry API provided by OpenTelemetry. To use it if
+you instrument a Java app, begin by installing dependencies:
 
 {{< tabpane text=true >}} {{% tab Gradle %}}
 
-```kotlin { hl_lines="4-8" }
+```kotlin { hl_lines="4-6" }
 dependencies {
     implementation("org.springframework.boot:spring-boot-starter-web");
-    implementation("io.opentelemetry:opentelemetry-api:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-sdk:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-sdk-metrics:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-exporter-logging:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-semconv:{{% param vers.otel %}}-alpha");
+    implementation("io.opentelemetry:opentelemetry-api");
+    implementation("io.opentelemetry:opentelemetry-sdk");
+    implementation("io.opentelemetry:opentelemetry-exporter-logging");
+    implementation("io.opentelemetry.semconv:opentelemetry-semconv:{{% param vers.semconv %}}-alpha");
 }
 ```
 
 {{% /tab %}} {{% tab Maven %}}
 
 ```xml
 <project>
-    <dependencyManagement>
-        <dependencies>
-            <dependency>
-                <groupId>io.opentelemetry</groupId>
-                <artifactId>opentelemetry-bom</artifactId>
-                <version>{{% param vers.otel %}}</version>
-                <type>pom</type>
-                <scope>import</scope>
-            </dependency>
-        </dependencies>
-    </dependencyManagement>
     <dependencies>
-        <dependency>
-            <groupId>io.opentelemetry</groupId>
-            <artifactId>opentelemetry-api</artifactId>
-        </dependency>
         <dependency>
             <groupId>io.opentelemetry</groupId>
             <artifactId>opentelemetry-sdk</artifactId>
         </dependency>
-        <dependency>
-            <groupId>io.opentelemetry</groupId>
-            <artifactId>opentelemetry-sdk-metrics</artifactId>
-        </dependency>
         <dependency>
             <groupId>io.opentelemetry</groupId>
             <artifactId>opentelemetry-exporter-logging</artifactId>
@@ -312,16 +319,14 @@ To use autoconfiguration add the following dependency to your application:
 
 {{< tabpane text=true >}} {{% tab Gradle %}}
 
-```kotlin { hl_lines="9-10" }
+```kotlin { hl_lines="7" }
 dependencies {
     implementation("org.springframework.boot:spring-boot-starter-web");
-    implementation("io.opentelemetry:opentelemetry-api:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-sdk:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-sdk-metrics:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-exporter-logging:{{% param vers.otel %}}");
-    implementation("io.opentelemetry.semconv:opentelemetry-semconv:{{% param vers.semconv %}}-alpha")
-    implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:{{% param vers.otel %}}");
-    implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:{{% param vers.otel %}}");
+    implementation("io.opentelemetry:opentelemetry-api");
+    implementation("io.opentelemetry:opentelemetry-sdk");
+    implementation("io.opentelemetry:opentelemetry-exporter-logging");
+    implementation("io.opentelemetry.semconv:opentelemetry-semconv:{{% param vers.semconv %}}-alpha");
+    implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure");
 }
 ```
 

content/en/docs/languages/js/instrumentation.md

@@ -8,7 +8,7 @@ cSpell:ignore: dicelib Millis rolldice
 description: Instrumentation for OpenTelemetry JavaScript
 ---
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 {{% alert title="Note" color="info" %}}
 

content/en/docs/languages/net/instrumentation.md

@@ -5,7 +5,7 @@ aliases: [manual]
 description: Instrumentation for OpenTelemetry .NET
 ---
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## A note on terminology
 

content/en/docs/languages/php/instrumentation.md

@@ -8,7 +8,7 @@ cSpell:ignore: guzzlehttp myapp
 
 <!-- markdownlint-disable no-duplicate-heading -->
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## Example app preparation {#example-app}
 

content/en/docs/languages/python/instrumentation.md

@@ -8,7 +8,7 @@ cSpell:ignore: millis ottrace textmap
 
 <!-- markdownlint-disable no-duplicate-heading -->
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## Setup
 

content/en/docs/languages/ruby/instrumentation.md

@@ -10,7 +10,7 @@ description: Instrumentation for OpenTelemetry Ruby
 cSpell:ignore: SIGHUP
 ---
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## Setup
 

content/en/docs/languages/swift/instrumentation.md

@@ -5,7 +5,7 @@ aliases: [manual]
 description: Instrumentation for OpenTelemetry Swift
 ---
 
-{{% docs/languages/manual-intro %}}
+{{% docs/languages/instrumentation-intro %}}
 
 ## Setup
 

layouts/shortcodes/docs/languages/manual-intro.md layouts/shortcodes/docs/languages/instrumentation-intro.md

@@ -93,7 +93,7 @@
     "postcss-cli": "^11.0.0",
     "prettier": "^3.0.3",
     "require-dir": "^1.2.0",
-    "textlint": "^13.3.3",
+    "textlint": "^14.0.1",
     "textlint-filter-rule-allowlist": "^4.0.0",
     "textlint-filter-rule-comments": "^1.2.2",
     "textlint-rule-terminology": "^4.0.1",