extend: Add OpenTelemetry example in YAML (#2528)

- Added `apis.yaml` with OpenTelemetry plugin configuration for distributed tracing in Membrane.
- Improved `OpenTelemetryInterceptor` logging with actionable advice for missing `jul-to-slf4j` JAR.
- Updated tests in `MethodSetterTest` to enhance coverage for scalar coercion.
- Refactored `MethodSetter` to improve scalar type coercion logic and exception clarity.
- Simplified OpenTelemetry example in README; replaced XML example with YAML, added base instructions, and updated trace output.

Author: predic8

annot/src/main/java/com/predic8/membrane/annot/yaml/MethodSetter.java

@@ -14,23 +14,21 @@
 
 package com.predic8.membrane.annot.yaml;
 
-import com.fasterxml.jackson.databind.JsonNode;
-import com.predic8.membrane.annot.MCChildElement;
+import com.fasterxml.jackson.databind.*;
+import com.predic8.membrane.annot.*;
 import org.jetbrains.annotations.*;
 
-import javax.lang.model.util.Types;
+import javax.lang.model.util.*;
 import java.lang.reflect.*;
-import java.util.Collection;
-import java.util.List;
-import java.util.Map;
+import java.util.*;
 
-import static com.predic8.membrane.annot.yaml.GenericYamlParser.createAndPopulateNode;
-import static com.predic8.membrane.annot.yaml.GenericYamlParser.parseListIncludingStartEvent;
+import static com.predic8.membrane.annot.yaml.GenericYamlParser.*;
 import static com.predic8.membrane.annot.yaml.McYamlIntrospector.*;
-import static java.lang.Boolean.parseBoolean;
-import static java.lang.Integer.parseInt;
-import static java.lang.Long.parseLong;
-import static java.util.Locale.ROOT;
+import static java.lang.Boolean.*;
+import static java.lang.Double.*;
+import static java.lang.Integer.*;
+import static java.lang.Long.*;
+import static java.util.Locale.*;
 
 public class MethodSetter {
 
@@ -85,27 +83,53 @@ public <T> void setSetter(T instance, ParsingContext ctx, JsonNode node, String
     private Object resolveSetterValue(ParsingContext ctx, JsonNode node, String key) throws WrongEnumConstantException, ParsingException {
         Class<?> wanted = getParameterType();
 
+        // Collections / repeated elements
         List<Object> list = getObjectList(ctx, node, key, wanted);
         if (list != null) return list;
 
+        // Structured objects
+        if (McYamlIntrospector.isStructured(setter)) {
+            if (beanClass != null) return createAndPopulateNode(ctx.updateContext(key), beanClass, node);
+            return createAndPopulateNode(ctx.updateContext(key), wanted, node);
+        }
+
+        return coerceScalarOrReference(ctx, node, key, wanted);
+    }
+
+    /**
+     * Attempts to coerce a given JSON node into the desired scalar, enum, reference, or map type,
+     * as specified by the provided target class.
+     *
+     * @param ctx The parsing context, providing access to type resolution and bean lookup mechanisms.
+     * @param node The JSON node to be coerced into the desired type.
+     * @param key The key corresponding to the JSON node, often used for error messages or map assignments.
+     * @param wanted The target class specifying the type into which the node should be converted.
+     * @return The coerced object, matching the desired type, derived from the input node.
+     * @throws WrongEnumConstantException If the node value does not match any of the constants in the enum type.
+     * @throws ParsingException If the provided type is unsupported for coercion or other unexpected issues arise.
+     */
+    Object coerceScalarOrReference(ParsingContext ctx, JsonNode node, String key, Class<?> wanted) throws WrongEnumConstantException {
+        // Scalars, enums, bean refs, "other attributes"
         if (wanted.isEnum()) return parseEnum(wanted, node);
         if (wanted.equals(String.class)) return node.asText();
 
-        if (wanted == Integer.TYPE || wanted == Integer.class) return parseInt(node.asText());
-        if (wanted == Long.TYPE || wanted == Long.class) return parseLong(node.asText());
-        if (wanted == Boolean.TYPE || wanted == Boolean.class) return parseBoolean(node.asText());
-        if (wanted.equals(Map.class) && McYamlIntrospector.hasOtherAttributes(setter)) return Map.of(key, node.asText());
+        if (wanted == int.class || wanted == Integer.class)
+            return node.isInt() ? node.intValue() : parseInt(node.asText());
+        if (wanted == long.class || wanted == Long.class)
+            return node.isLong() || node.isInt() ? node.longValue() : parseLong(node.asText());
+        if (wanted == double.class || wanted == Double.class)
+            return node.isNumber() ? node.doubleValue() : parseDouble(node.asText());
+        if (wanted == boolean.class || wanted == Boolean.class)
+            return node.isBoolean() ? node.booleanValue() : parseBoolean(node.asText());
+        if (wanted.equals(Map.class) && McYamlIntrospector.hasOtherAttributes(setter))
+            return Map.of(key, node.asText());
 
         if (node.isTextual() && isBeanReference(wanted)) {
             return resolveReference(ctx, node, key, wanted);
         }
 
-        if (McYamlIntrospector.isStructured(setter)) {
-            if (beanClass != null) return createAndPopulateNode(ctx.updateContext(key), beanClass, node);
-            return createAndPopulateNode(ctx.updateContext(key), wanted, node);
-        }
         if (McYamlIntrospector.isReferenceAttribute(setter)) return ctx.registry().resolve(node.asText());
-        throw new RuntimeException("Not implemented setter type " + wanted);
+        throw new ParsingException("Unsupported setter type: %s for key '%s' with node type %s".formatted(wanted.getName(), key, node.getNodeType()), node);
     }
 
     private @Nullable List<Object> getObjectList(ParsingContext ctx, JsonNode node, String key, Class<?> wanted) {
@@ -118,7 +142,7 @@ private Object resolveSetterValue(ParsingContext ctx, JsonNode node, String key)
                     if (o == null) continue;
                     if (!elemType.isAssignableFrom(o.getClass())) {
                         throw new ParsingException("Value of type '%s' is not allowed in list '%s'. Expected '%s'."
-                                        .formatted(McYamlIntrospector.getElementName(o.getClass()), key, elemType.getSimpleName()), node);
+                                .formatted(McYamlIntrospector.getElementName(o.getClass()), key, elemType.getSimpleName()), node);
                     }
                 }
             }

annot/src/test/java/com/predic8/membrane/annot/yaml/MethodSetterTest.java

@@ -14,15 +14,20 @@
 
 package com.predic8.membrane.annot.yaml;
 
-import com.predic8.membrane.annot.MCChildElement;
-import com.predic8.membrane.annot.util.GrammarMock;
-import org.junit.jupiter.api.Test;
+import com.fasterxml.jackson.core.*;
+import com.fasterxml.jackson.databind.*;
+import com.predic8.membrane.annot.*;
+import com.predic8.membrane.annot.util.*;
+import org.junit.jupiter.api.*;
 
-import static com.predic8.membrane.annot.yaml.MethodSetter.getMethodSetter;
+import static com.predic8.membrane.annot.yaml.MethodSetter.*;
 import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertEquals;
 
 class MethodSetterTest {
 
+    private static final ObjectMapper om = new ObjectMapper();
+
     @SuppressWarnings("unused")
     static class A {
         public void setA1(B b) {}
@@ -44,25 +49,37 @@ public static class B {}
     public static class C {}
 
     @Test
-    public void dontUseMethodsWithoutChildElementAnnotation() {
+    void dontUseMethodsWithoutChildElementAnnotation() {
         MethodSetter ms = getMethodSetter(new ParsingContext("foo", null,
                         new GrammarMock().withGlobalElement("b", B.class)),
                 A.class, "b");
         assertEquals("setA3", ms.getSetter().getName());
     }
 
     @Test
-    public void multiplePotentialSettersFound() {
+    void multiplePotentialSettersFound() {
         assertThrowsExactly(RuntimeException.class, () -> getMethodSetter(new ParsingContext("foo", null,
                         new GrammarMock().withGlobalElement("b", B.class)),
                 A2.class, "b"));
     }
 
     @Test
-    public void noPotentialSetterFound() {
+    void noPotentialSetterFound() {
         assertThrowsExactly(RuntimeException.class, () -> getMethodSetter(new ParsingContext("foo", null,
                         new GrammarMock().withGlobalElement("c", C.class)),
                 A2.class, "c"));
     }
 
+    @Test
+    void foo() throws Exception {
+        var ms  = new MethodSetter(null, null);
+        assertEquals(true, ms.coerceScalarOrReference(null, om.readTree("true"), null, boolean.class));
+        assertEquals(true, ms.coerceScalarOrReference(null, om.readTree("true"), null, Boolean.class));
+        assertEquals(1, ms.coerceScalarOrReference(null, om.readTree("1"), null, int.class));
+        assertEquals(1.0, ms.coerceScalarOrReference(null, om.readTree("1"), null, double.class));
+        var l = ms.coerceScalarOrReference(null, om.readTree("1"), null, long.class);
+        assertInstanceOf(Long.class, l);
+        assertEquals(1L, l);
+        assertEquals(true, ms.coerceScalarOrReference(null, om.readTree("true"), null, boolean.class));
+    }
 }

core/src/main/java/com/predic8/membrane/core/interceptor/opentelemetry/OpenTelemetryInterceptor.java

@@ -81,7 +81,7 @@ public void init() {
                 SLF4JBridgeHandler.install();
             }
         } catch (Throwable t) {
-            log.warn("jul-to-slf4j not available; OpenTelemetry logs may go to stderr.", t);
+            log.warn("jul-to-slf4j is not available; OpenTelemetry logs may go to stderr. Add the jul-to-slf4j JAR to the lib folder if you want to avoid this.");
         }
 
         otel = OpenTelemetryConfigurator.openTelemetry("Membrane", exporter, getSampleRate());

distribution/examples/monitoring-tracing/opentelemetry/README.md

@@ -1,98 +1,59 @@
 # Tracing with OpenTelemetry
 
-Membrane offers support for tracing according to the [OpenTelemetry](https://opentelemetry.io/) specification.
+Membrane supports distributed tracing based on the [OpenTelemetry](https://opentelemetry.io/) specification.
 
-The usage of APIs can be observed with the OpenTelemetry plugin. Membrane collects data about the processes flowing
-through it and sends it to an OTLP endpoint, in this case, a jaeger backend.
+With the OpenTelemetry plugin, API traffic can be observed end to end. Membrane collects tracing data for requests flowing through the gateway and exports it to an OTLP endpoint. In this example, Jaeger is used as the backend.
 
-To instrument an API add the `opentelemetry` plugin to it.
+To instrument an API, add the `openTelemetry` plugin to the API configuration.
 
 ## Run the Example
 
 1. Start Jaeger with:
 ```dockerfile
-docker run -d --name jaeger -e COLLECTOR_OTLP_ENABLED=true -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/all-in-one:latest
+docker run -it --name jaeger -e COLLECTOR_OTLP_ENABLED=true -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/all-in-one:latest
 ```
 
-2. Run `membrane.cmd` or `./membrane.sh` to start Membrane.
+2. Start Membrane: `membrane.cmd` or `./membrane.sh`
 
 3. Call the first endpoint in the telemetry chain:
 
-   `curl http://localhost:2000`.
+   ```bash
+   curl http://localhost:2000
+   ```
 
-4. You should see `Hello from a faked backend!` in your terminal.
-5. Open `localhost:16686` in the browser to access the Jaeger UI.
+4. You should see `Greetings from the backend!` in your terminal.
+5. Open the Jaeger UI in your browser: `http://localhost:16686`
 6. Select Membrane as the service and click on `Find Traces`.
-A span created by Membrane should be visible in [Jaeger UI](http://localhost:16686).
-![sample](resources/otel_sample.png)
-7. Examine the printed header fields on the console. You will see headers called `traceparent`, these denote which spans were involved in the request.
-
-**HOW IT IS DONE**
-
-Take a look at the `proxies.xml`.
-
-```xml
-<router>
-
-   <transport>
-      <ruleMatching />
-      <logContext />
-      <exchangeStore />
-      <dispatching />
-      <reverseProxying />
-      <openTelemetry sampleRate="1.0"> <!--globally registers OpenTelemetry for every api-->
-         <otlpExporter host="localhost" port="4317" transport="grpc"/>
-      </openTelemetry>
-      <userFeature />
-      <internalRouting />
-      <httpClient />
-   </transport>
-
-   <api port="2000">
-      <target url="http://localhost:2001" />
-   </api>
-
-   <api port="2001" name="AccessControl">
-      <target url="http://localhost:2002" />
-   </api>
-
-   <api port="2002" name="Validation">
-      <target url="http://localhost:3000" />
-   </api>
-
-   <api port="3000" name="Replace with your Backend">
-      <request>
-         <!-- Print the request headers.
-              traceparents will be added to them
-              showing which spans were involved
-              in the exchange.                   -->
-         <groovy>
-            println "Request headers:"
-            header.allHeaderFields.each {
-            print it
-            }
-            CONTINUE
-         </groovy>
-      </request>
-      <response>
-         <template>Hello from a faked backend!</template>
-      </response>
-      <return/>
-   </api>
-</router>
+A span created by Membrane should be visible in the [Jaeger UI](http://localhost:16686).
+![sample](resources/otel_example.png)
+7. Check the headers printed to the console. You will see headers such as `traceparent`, which indicate the trace and span context involved in the request.
+
+**How it is done**
+
+Take a look at the `apis.yml`.
+
+The openTelemetry plugin can be used in several ways:
+
+a.) Globally, in a shared interceptor chain that applies to all APIs (as shown in apis.yaml)
+b.) Per API, by defining it directly inside the API flow
+c.) With reuseable interceptor chains. See: [Reusable Plugin Chains](../../extending-membrane/reusable-plugin-chains)
+
+Example configuration for a single API:
+
+```yaml
+api:
+  port: 2000
+  flow:
+    - openTelemetry:
+        sampleRate: 1.0
+        otlpExporter:
+          host: localhost
+          port: 4317
+          transport: grpc
+  target:
+    url: http://localhost:2001
 ```
-The `openTelemetry` plugin can be utilized in two ways: either in a global context for all APIs using the `<transport>` tag, as demonstrated above, or it can be specifically defined for individual APIs by placing it within the `<api>` tag.
-```xml
-<api port="2000">
-   <openTelemetry sampleRate="1.0">
-      <otlpExporter host="localhost" port="4317" transport="grpc"/>
-   </openTelemetry>
-   <target host="localhost" port="3000"/>
-</api>
-```
-
-**Note:**
 
-The OTLP Exporter is configured by default to use gRPC. You can omit the `transport` field in the configuration when using gRPC.
+**Note on Transport:**
 
-To use HTTP, set the `transport` field to `http` and set the `port` to `4318`.
+The OTLP exporter is configured by default to use gRPC. To use HTTP, set the `transport` field to `http` and set the `port` to `4318`.

distribution/examples/monitoring-tracing/opentelemetry/apis.yaml

@@ -0,0 +1,41 @@
+# yaml-language-server: $schema=https://www.membrane-api.io/v7.0.5.json
+
+global:
+  - openTelemetry:
+      sampleRate: 1.0
+      otlpExporter:
+        host: localhost
+---
+
+api:
+  name: Entry
+  port: 2000
+  target:
+    url: http://localhost:2001
+---
+
+api:
+  name: Access Control
+  port: 2001
+  target:
+    url: http://localhost:2002
+---
+
+api:
+  name: Validation
+  port: 2002
+  target:
+    url: http://localhost:3000
+---
+
+api:
+  name: Backend
+  port: 3000
+  flow:
+    - request:
+        - log:
+            message: "Header: ${header}"
+    - static:
+        src: Greetings from the backend!
+    - return:
+        status: 200