Add peer service mapping to example (#1159)

Author: jaydeluca

javaagent-declarative-configuration/README.md

@@ -4,10 +4,11 @@ This example demonstrates how to use [declarative configuration](https://opentel
 
 The configuration file is located at [otel-agent-config.yaml](./otel-agent-config.yaml).
 
-This Spring Boot application includes two endpoints:
+This Spring Boot application includes three endpoints:
 
 - `/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
+- `/api/remote` - An endpoint that makes an outgoing HTTP (client) call, used to demonstrate peer service mapping
 
 ## End-to-End Instructions
 
@@ -37,7 +38,7 @@ curl -L -o opentelemetry-javaagent.jar https://github.com/open-telemetry/opentel
 
 # Run with the OpenTelemetry Java Agent and contrib extension
 java -javaagent:opentelemetry-javaagent.jar \
-     -Dotel.experimental.config.file=$(pwd)/otel-agent-config.yaml \
+     -Dotel.config.file=$(pwd)/otel-agent-config.yaml \
      -jar build/libs/javaagent-declarative-configuration.jar
 ```
 
@@ -51,6 +52,9 @@ curl http://localhost:8080/actuator/health
 
 # This endpoint WILL be traced normally
 curl http://localhost:8080/api/example
+
+# This endpoint makes an outgoing client call; its client span is tagged with peer.service
+curl http://localhost:8080/api/remote
 ```
 
 ### Step 4: Verify Tracing Behavior
@@ -83,3 +87,25 @@ This configuration:
 - Excludes health check endpoints (`/actuator.*`) from tracing using the `DROP` action
 - Samples all other requests using the `always_on` fallback sampler
 - Only applies to `SERVER` span kinds
+
+### Peer service mapping
+
+The `otel-agent-config.yaml` file also demonstrates peer service mapping, which maps the peer address (host name or IP)
+of an outgoing client call to a logical service name:
+
+```yaml
+instrumentation/development:
+  java:
+    common:
+      service_peer_mapping:
+        - peer: localhost
+          service_name: example-backend
+```
+
+This configuration:
+
+- Replaces the `otel.instrumentation.common.peer-service-mapping` system property
+- Adds a `peer.service` attribute to client spans whose peer address (`server.address`) matches a configured `peer`.
+  The port is optional — omitting it matches any port.
+- In this example, the `/api/remote` endpoint calls back into the application over `localhost`, so its client span is
+  tagged with `peer.service=example-backend`

javaagent-declarative-configuration/oats/docker-compose.yml

@@ -7,6 +7,7 @@ services:
     environment:
       OTEL_SERVICE_NAME: "declarative-config-example-app"
       OTEL_EXPORTER_OTLP_ENDPOINT: http://lgtm:4318
+      OTEL_CONFIG_FILE: /usr/src/app/otel-agent-config.yaml
     ports:
       - "8080:8080"
     healthcheck:

javaagent-declarative-configuration/oats/oats.yaml

@@ -10,6 +10,8 @@ input:
   - path: /api/example
   # This endpoint should NOT be traced (excluded by declarative config)
   - path: /actuator/health
+  # This endpoint makes an outgoing client call, exercising the peer service mapping
+  - path: /api/remote
 
 expected:
   traces:
@@ -22,3 +24,8 @@ expected:
     - traceql: '{ span.http.route = "/actuator/health" }'
       count:
         max: 0
+    # Verify the outgoing client span is tagged with peer.service via the
+    # instrumentation.general.peer.service_mapping declarative config
+    - traceql: '{ span.peer.service = "example-backend" }'
+      count:
+        min: 1

javaagent-declarative-configuration/otel-agent-config.yaml

@@ -10,7 +10,7 @@ resource:
   # Read resource attributes from the OTEL_RESOURCE_ATTRIBUTES environment variable.
   # This aligns well with the OpenTelemetry Operator and other deployment methods.
   attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
-  detection/development: # /development properties may not be supported in all SDKs
+  detection/development:
     detectors:
       - service: # will add "service.instance.id" and "service.name" from the OTEL_SERVICE_NAME env var
       - host:
@@ -22,6 +22,34 @@ propagator:
     - tracecontext:
     - baggage:
 
+instrumentation/development:
+  java:
+    common:
+      # Map peer addresses (host names or IP addresses) of outgoing client calls
+      # to a logical service name. Matching client spans get a "peer.service"
+      # attribute set to the configured service_name (port is optional; omitting
+      # it matches any port). Previously configured via the
+      # otel.instrumentation.common.peer-service-mapping property.
+      service_peer_mapping:
+        - peer: localhost
+          service_name: example-backend
+  general:
+    http:
+      client:
+        request_captured_headers: # was otel.instrumentation.http.client.capture-request-headers
+          - Content-Type
+          - Accept
+        response_captured_headers: # was otel.instrumentation.http.client.capture-response-headers
+          - Content-Type
+          - Content-Encoding
+      server:
+        request_captured_headers: # was otel.instrumentation.http.server.capture-request-headers
+          - Content-Type
+          - Accept
+        response_captured_headers: # was otel.instrumentation.http.server.capture-response-headers
+          - Content-Type
+          - Content-Encoding
+
 # Read backend endpoint from the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.
 # This aligns well with the OpenTelemetry Operator and other deployment methods.
 

javaagent-declarative-configuration/src/main/java/io/opentelemetry/examples/fileconfig/ApiController.java

@@ -5,17 +5,35 @@
 
 package io.opentelemetry.examples.fileconfig;
 
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.client.RestClient;
 
 @RestController
 @RequestMapping("/api")
 public class ApiController {
 
+  private final RestClient restClient = RestClient.create();
+  private final String remoteTargetUrl;
+
+  public ApiController(
+      @Value("${remote.target.url:http://localhost:8080/api/example}") String remoteTargetUrl) {
+    this.remoteTargetUrl = remoteTargetUrl;
+  }
+
   @GetMapping("/example")
   public ResponseEntity<String> example() {
     return ResponseEntity.ok("Hello from OpenTelemetry example API!");
   }
+
+  // Makes an outgoing HTTP (CLIENT) call so the peer service mapping in
+  // otel-agent-config.yaml can tag the client span with a "peer.service" attribute.
+  @GetMapping("/remote")
+  public ResponseEntity<String> remote() {
+    String body = restClient.get().uri(remoteTargetUrl).retrieve().body(String.class);
+    return ResponseEntity.ok("Remote call returned: " + body);
+  }
 }