fixes

Author: ahmedmuhsin

articles/azure-functions/opentelemetry-howto.md

@@ -129,69 +129,84 @@ The way that you instrument your application to use OpenTelemetry depends on you
 ::: zone-end
 ::: zone pivot="programming-language-java"
 
-### 1  Add the required libraries
+### Step 1 – Add the required libraries
 
-1. **Core bridge (always)**  – enables OpenTelemetry inside the Java worker
+**Core bridge** (always) – enables OpenTelemetry inside the Java worker
 
-   **Maven**
+<details open>
+<summary>Maven</summary>
 
-   ```xml
-   <dependency>
-     <groupId>com.microsoft.azure.functions</groupId>
-     <artifactId>azure-functions-java-opentelemetry</artifactId>
-     <version>1.0.0</version>
-   </dependency>
-   ```
+```xml
+<dependency>
+  <groupId>com.microsoft.azure.functions</groupId>
+  <artifactId>azure-functions-java-opentelemetry</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+</details>
+
+<details>
+<summary>Gradle (Kotlin DSL)</summary>
+
+```kotlin
+implementation("com.microsoft.azure.functions:azure-functions-java-opentelemetry:1.0.0")
+```
+
+</details>
 
-   **Gradle (Kotlin DSL)**
+**Application Insights exporter** (optional) – add only if you plan to send data to AI
 
-   ```kotlin
-   implementation("com.microsoft.azure.functions:azure-functions-java-opentelemetry:1.0.0")
-   ```
+<details>
+<summary>Maven</summary>
 
-2. **Application Insights exporter (optional)**  – only if you want to send data to AI
+```xml
+<dependency>
+  <groupId>com.azure</groupId>
+  <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
+  <version>1.2.0</version>
+</dependency>
+```
 
-   **Maven**
+</details>
 
-   ```xml
-   <dependency>
-     <groupId>com.azure</groupId>
-     <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
-     <version>1.2.0</version>
-   </dependency>
-   ```
+<details>
+<summary>Gradle (Kotlin DSL)</summary>
 
-   **Gradle (Kotlin DSL)**
+```kotlin
+implementation("com.azure:azure-monitor-opentelemetry-autoconfigure:1.2.0")
+```
 
-   ```kotlin
-   implementation("com.azure:azure-monitor-opentelemetry-autoconfigure:1.2.0")
-   ```
+</details>
 
-   > The bridge locates `AzureMonitorAutoConfigure` by reflection; if this dependency is absent, it just skips the AI exporter.
+> The bridge looks for `AzureMonitorAutoConfigure` by reflection; if this dependency isn’t present, it simply skips the AI exporter.
 
 ---
 
-### 2  Add application settings
+### Step 2 – Add application settings
+
+Set this flag **in every Java Functions app that uses the bridge**, even if you export only to OTLP:
 
 ```text
 JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true
 ```
 
-Setting this flag **enables a worker capability that tells the Functions host to stop forwarding its own logs and let the Java worker stream OpenTelemetry records instead, preventing duplicate log entries.**
+This capability tells the Functions host to let the Java worker stream OpenTelemetry logs directly, preventing duplicate host-level entries.
 
-Other settings:
+Additional settings:
 
-| Purpose                         | Name                                    | Example                                            |
-| ------------------------------- | --------------------------------------- | -------------------------------------------------- |
-| Application Insights connection | `APPLICATIONINSIGHTS_CONNECTION_STRING` | `InstrumentationKey=…;IngestionEndpoint=https://…` |
-| OTLP export                     | `OTEL_EXPORTER_OTLP_ENDPOINT`           | `https://otlp.example.com:4318`                    |
-|                                 | `OTEL_EXPORTER_OTLP_HEADERS` (optional) | `api-key=abcd1234`                                 |
+* **Application Insights**
+  `APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...;IngestionEndpoint=https://...`
 
-If both AI *and* OTLP variables are present, telemetry is sent to **both** back-ends.
+* **OTLP export**
+  `OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.example.com:4318`
+  `OTEL_EXPORTER_OTLP_HEADERS=api-key=abcd1234` (optional)
+
+If both AI *and* OTLP variables are present, telemetry flows to **both** back-ends.
 
 ---
 
-### 3  (Optional) create custom spans
+### Step 3 – (Optional) create custom spans
 
 ```java
 import com.microsoft.azure.functions.opentelemetry.FunctionsOpenTelemetry;
@@ -200,34 +215,36 @@ import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.context.Scope;
 
 Span span = FunctionsOpenTelemetry.startSpan(
-        "com.contoso.PaymentFunction",  // tracer
-        "validateCharge",               // span
+        "com.contoso.PaymentFunction",  // tracer name
+        "validateCharge",               // span name
         null,                           // parent = current context
         SpanKind.INTERNAL);
 
 try (Scope ignored = span.makeCurrent()) {
-    // your business logic here
+    // business logic here
 } finally {
     span.end();
 }
 ```
 
-Custom spans inherit the same resource attributes and exporters configured by the bridge.
+Custom spans inherit all resource attributes and exporters configured by the bridge.
 
 ---
 
-### 4  Local development & testing tips
+### Step 4 – Local development and testing tips
 
-* When not running in Azure, the resource detector defaults `service.name` to `java-function-app`.
-* Silence telemetry during unit tests with JVM flags:
+* Outside Azure, the resource detector defaults `service.name` to `java-function-app`.
+* **Java Virtual Machine (JVM)** flags to silence telemetry during unit tests:
 
   ```text
   -Dotel.traces.exporter=none
   -Dotel.metrics.exporter=none
   -Dotel.logs.exporter=none
   ```
-* No manual registration is required—`OpenTelemetryInvocationMiddleware` is auto-discovered by the Java worker.
+* You don’t need to register anything manually—the Java worker **autodiscovers** `OpenTelemetryInvocationMiddleware`.
+
 ::: zone-end
+
 ::: zone pivot="programming-language-javascript,programming-language-typescript"
 1. Install these npm packages in your project: