Document integration with OCI APM

oracle · Feb 4, 2022 · 30ee652 · 30ee652
1 parent 6d1cba2
commit 30ee652
Show file tree

Hide file tree

Showing 15 changed files with 141 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -32,7 +32,6 @@ as the application framework, in case one of those is your framework of choice.
 * [Development](./doc/development.md)
 * [License](#license)
 
-
 ## Architecture
 
 The application consists of 6 back end services (rewritten from the ground up on top of

diff --git a/carts/src/main/resources/application.yaml b/carts/src/main/resources/application.yaml
@@ -14,6 +14,7 @@ spring:
       type: B3,W3C
     opentracing:
       enabled: true
+    supports-join: false
   zipkin:
     base-url: http://jaeger-agent:9411
     enabled: false

diff --git a/catalog/src/main/resources/application.yaml b/catalog/src/main/resources/application.yaml
@@ -14,6 +14,7 @@ spring:
       type: B3,W3C
     opentracing:
       enabled: true
+    supports-join: false
   zipkin:
     base-url: http://jaeger-agent:9411
     enabled: false

diff --git a/doc/complete-application-deployment.md b/doc/complete-application-deployment.md
@@ -165,7 +165,7 @@ of the Grafana documentation.
     kubectl create -f k8s/optional/jaeger.yaml --namespace sockshop
     ```
 
-3. Enable Jaeger tracing in `application.yaml` files and rebuild and redeploy services
+3. Enable Jaeger tracing in the `app.yaml` files and rebuild and redeploy services
 
     Set `spring.zipkin.enabled` to `true`, e.g.:
 
@@ -217,7 +217,7 @@ Once you are done, you should have the following URLs available:
 
 1. Cleanup the ingress for applications
 
-   To cleanup the ingress for your deployment, execute the following:
+   To clean up the ingress for your deployment, execute the following:
 
     ```bash
     export SOCKSHOP_DOMAIN=sockshop.mycompany.com

diff --git a/doc/images/oracle-apm.png b/doc/images/oracle-apm.png
diff --git a/doc/oracle-cloud-apm.md b/doc/oracle-cloud-apm.md
@@ -0,0 +1,93 @@
+# Oracle Cloud Infrastructure (OCI)
+
+In this guide we illustrate the integration of Coherence Spring Sock Shop with
+Oracle Cloud Infrastructure (OCI) Application Performance Monitoring (APM) as another option to process
+distributed traces.
+
+To set up Sock Shop with APM, please follow the guide [Complete Application Deployment](complete-application-deployment.md)
+but please ignore the section about _Jaeger_.
+
+## OCI APM Documentation
+
+You can find the official OCI APM Documentation at:
+
+- https://docs.oracle.com/en-us/iaas/application-performance-monitoring/index.html
+
+## Setup OCI APM
+
+In order to set up APM we will start from scratch. The only requirement is that you have a valid account for OCI. Here are
+the basic steps to set up APM:
+
+1. Login to OCI.
+2. Under `Observability and Management`, select `Application Performance Administration`.
+3. Click on `Create APM Domain`.
+4. Enter a name `Coherence Spring Sock Shop`.
+5. For now, we can check the checkbox `Create as Always Free Domain`.
+6. Click on the link `Coherence Spring Sock Shop` to enter the `Domain Details` screen.
+
+On the `Domain Details` screen, we are interested in 3 values:
+
+- Data Upload Endpoint
+- Private Data Key or
+- Public Data Key
+
+We will use these values to construct the _Application Performance Monitoring collector URL_. The APM collector URL has the
+following format:
+
+```
+<apm-domain-short-id>.<apm-collector-domain>/<API version>/observations/<observationType>
+?dataFormat=<dataFormat>&dataFormatVersion=<dataFormatVersion>&dataKey=<dataKey>
+```
+
+For detailed information on the _APM Collector URL Format_ see
+[the reference guide](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-open-source-tracing-systems.html#APMGN-GUID-B5EDE254-C854-436D-B844-B986A4E077AA).
+
+**Private versus Public Data Key**:
+
+You can either use the Private Data Key or the Public Data Key, depending on your environment. This was built to allow
+users to separate traffic that comes from safe locations like your backend servers vs. a non-safe locations like browsers
+or in any situation where any end user may look up the traffic and see the data key.
+
+- When using the **Private Data Key** you must also set `<observationType>` to `private-span`.
+- When using the **Public Data Key** you must also set `<observationType>` to `public-span`.
+
+In the Sock Shop use-case we will use the private key, but both configurations will work. Your URL should look like this:
+
+```
+https://[redacted].apm-agt.us-ashburn-1.oci.oraclecloud.com/20200101/observations/private-span?dataFormat=zipkin&dataFormatVersion=2&dataKey=[private key]
+```
+
+## Configure Sock Shop for APM
+
+We need to enable tracing for OCI APM in the `app.yaml` files for each service under the `/k8s/coherence/` folder. Here
+we will also set the APM collector URL that we obtained in the previous section. It is important that we split up the
+URL into the parts `base-url` and the `api-path`.
+
+We need to specify the following properties and set:
+
+- `spring.zipkin.enabled` to `true`
+- `spring.zipkin.base-url` to `https://[redacted].apm-agt.us-ashburn-1.oci.oraclecloud.com`
+- `spring.zipkin.api-path` to `/20200101/observations/private-span?dataFormat=zipkin&dataFormatVersion=2&dataKey=[private key]`
+
+Your `app.yaml` file should look like this:
+
+```yaml
+application:
+  main: com.oracle.coherence.examples.sockshop.spring.carts.CartsApp
+  args:
+    - "--port=8080"
+    - "--spring.zipkin.enabled=true"
+    - "--spring.zipkin.base-url=https://[redacted].apm-agt.us-ashburn-1.oci.oraclecloud.com"
+    - "--spring.zipkin.api-path=/20200101/observations/private-span?dataFormat=zipkin&dataFormatVersion=2&dataKey=[private key]"
+    - "--coherence.server.startup-timeout=5m"
+```
+
+Rebuild and redeploy the Sock Shop services. Now order some socks and afterwards head over to the APM dashboard at:
+
+- https://console.your-region.oraclecloud.com/apm/apm-traces
+
+There, select you `Compartment` and your `APM Domain` and then click on the run button, and you should see the traces
+that were emitted from the Sock Shop application.
+
+![Jaeger Search](./images/oracle-apm.png)
+
diff --git a/orders/pom.xml b/orders/pom.xml
@@ -46,6 +46,11 @@
             <groupId>org.springframework.cloud</groupId>
             <artifactId>spring-cloud-starter-openfeign</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.github.openfeign</groupId>
+            <artifactId>feign-httpclient</artifactId>
+        </dependency>
+
         <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-boot-starter</artifactId>
@@ -77,6 +82,10 @@
             <groupId>org.springframework.cloud</groupId>
             <artifactId>spring-cloud-sleuth-zipkin</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.apache.httpcomponents</groupId>
+            <artifactId>httpclient</artifactId>
+        </dependency>
 
         <!-- test dependencies -->
         <dependency>

diff --git a/orders/src/main/java/com/oracle/coherence/examples/sockshop/spring/orders/OrdersApp.java b/orders/src/main/java/com/oracle/coherence/examples/sockshop/spring/orders/OrdersApp.java
@@ -20,6 +20,7 @@
 import org.springframework.cloud.openfeign.EnableFeignClients;
 import org.springframework.cloud.sleuth.exporter.SpanFilter;
 import org.springframework.context.annotation.Bean;
+import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
 import org.springframework.web.client.RestTemplate;
 import org.springframework.web.servlet.config.annotation.CorsRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@@ -51,7 +52,7 @@ public static void main(String[] args) {
 
 	@Bean
 	public RestTemplate restTemplate(RestTemplateBuilder builder) {
-		// Do any additional configuration here
+		builder.requestFactory(HttpComponentsClientHttpRequestFactory.class);
 		return builder.build();
 	}
 

diff --git a/orders/src/main/resources/application.yaml b/orders/src/main/resources/application.yaml
@@ -14,6 +14,7 @@ spring:
       type: B3,W3C
     opentracing:
       enabled: true
+    supports-join: false
   zipkin:
     base-url: http://jaeger-agent:9411
     enabled: false
@@ -30,3 +31,7 @@ logging:
     org.springframework.web: info
     com.oracle.coherence.spring: info
     com.oracle.coherence.examples.sockshop.spring: info
+    org.apache.http: debug
+feign:
+  httpclient:
+    enabled: true
diff --git a/payment/pom.xml b/payment/pom.xml
@@ -77,6 +77,10 @@
             <groupId>org.springframework.cloud</groupId>
             <artifactId>spring-cloud-sleuth-zipkin</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.apache.httpcomponents</groupId>
+            <artifactId>httpclient</artifactId>
+        </dependency>
 
         <!-- test dependencies -->
         <dependency>

diff --git a/payment/src/main/java/com/oracle/coherence/examples/sockshop/spring/payment/PaymentApp.java b/payment/src/main/java/com/oracle/coherence/examples/sockshop/spring/payment/PaymentApp.java
@@ -14,6 +14,10 @@
 import io.swagger.v3.oas.annotations.servers.Server;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cloud.sleuth.zipkin2.ZipkinRestTemplateCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
+import org.springframework.web.client.RestTemplate;
 import org.springframework.web.servlet.config.annotation.CorsRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 
@@ -51,4 +55,15 @@ public void addCorsMappings(CorsRegistry registry) {
 			}
 		};
 	}
+
+	@Bean
+	public ZipkinRestTemplateCustomizer zipkinRestTemplateCustomizer() {
+		return new ZipkinRestTemplateCustomizer() {
+			@Override
+			public RestTemplate customizeTemplate(RestTemplate restTemplate) {
+				restTemplate.setRequestFactory(new HttpComponentsClientHttpRequestFactory());
+				return restTemplate;
+			}
+		};
+	}
 }
diff --git a/...a/com/oracle/coherence/examples/sockshop/spring/payment/controller/PaymentController.java b/...a/com/oracle/coherence/examples/sockshop/spring/payment/controller/PaymentController.java
@@ -12,6 +12,7 @@
 import io.micrometer.core.instrument.MeterRegistry;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -26,6 +27,7 @@
 /**
  * Implementation of the Payment Service REST API.
  */
+@Slf4j
 @RequestMapping("/payments")
 @RestController
 public class PaymentController {
@@ -60,6 +62,7 @@ public ResponseEntity<Collection<? extends Authorization>> getOrderAuthorization
     public Authorization authorize(
             @Parameter(description = "Payment request")
             @RequestBody PaymentRequest paymentRequest) {
+        log.info("Authorizing payment request for order id {}.", paymentRequest.getOrderId());
         meterRegistry.counter("payments.authorize", "controller", "payments").increment();
         String firstName = paymentRequest.getCustomer().getFirstName();
         String lastName  = paymentRequest.getCustomer().getLastName();

diff --git a/payment/src/main/resources/application.yaml b/payment/src/main/resources/application.yaml
@@ -14,6 +14,7 @@ spring:
       type: B3,W3C
     opentracing:
       enabled: true
+    supports-join: false
   zipkin:
     base-url: http://jaeger-agent:9411
     enabled: false
@@ -26,5 +27,6 @@ logging:
   level:
     root: warn
     "Coherence": info
-    org.springframework: debug
-    com.oracle.coherence.spring: debug
+    org.springframework.web: info
+    com.oracle.coherence.spring: info
+    org.apache.http: debug
diff --git a/shipping/src/main/resources/application.yaml b/shipping/src/main/resources/application.yaml
@@ -14,6 +14,7 @@ spring:
       type: B3,W3C
     opentracing:
       enabled: true
+    supports-join: false
   zipkin:
     base-url: http://jaeger-agent:9411
     enabled: false
@@ -28,4 +29,5 @@ logging:
     "Coherence": info
     org.springframework.web: info
     com.oracle.coherence.spring: info
+    org.apache.http: info # set to debug to see logging of http payloads
 
diff --git a/users/src/main/resources/application.yaml b/users/src/main/resources/application.yaml
@@ -35,4 +35,3 @@ logging:
     org.springframework.security: info
     org.springframework.web: info
     com.oracle.coherence.spring: info
-    org.apache.http: info # set to debug to see logging of http payloads