Observability support (#3)

* observability support

* metrics, tracing keep going, add unit tests

Author: DanielLiu1123

README.md

@@ -29,6 +29,8 @@ _**Make the integration of gRPC with Spring Boot feel seamless and native.**_
 
 - **JSON transcoder, one set of code supports both gRPC and HTTP/JSON.**
 - **Protobuf validation, implemented by [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate).**
+- Metric, Spring Boot Actuator integration with gRPC service.
+- Tracing, Spring Boot Actuator integration with gRPC server and client.
 - Testing support.
 
 ## Quick Start

docs/zh-cn/extension/metrcis.md

@@ -0,0 +1,71 @@
+## Overview
+
+Metrics 扩展了 Spring Boot Actuator，为 gRPC 服务端和客户端提供了指标采集功能。
+
+> Metrics extension works with Spring Boot 3.1.0+
+
+## Quick Start
+
+1. 引入依赖
+
+    ```groovy
+    implementation("com.freemanan:grpc-starter-metrics")
+    // Actuator 使用 Micrometer 作为指标采集门面，这里使用 Prometheus
+    // Micrometer 支持的指标采集器可以参考 https://micrometer.io/docs/
+    implementation("io.micrometer:micrometer-registry-prometheus")
+    ```
+
+2. 配置 Prometheus 端点
+
+    ```yaml
+    management:
+      endpoints:
+        web:
+          exposure:
+            include: prometheus
+    ```
+
+3. Visit endpoint
+
+    ```shell
+    curl http://localhost:8080/actuator/prometheus
+    ```
+
+See [examples/metrics](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/metrics) for more details.
+
+## Annotation Driven
+
+Micrometer 提供了一些开箱即用的注解，可以用于对方法的指标采集，Metrics 扩展提供了对这些注解的支持。
+
+```java
+@Controller
+public class SimpleServiceImpl extends SimpleServiceGrpc.SimpleServiceImplBase {
+
+    @Override
+    @Timed("simple.unaryRpc")
+    @Counted("simple.unaryRpc")
+    public void unaryRpc(SimpleRequest request, StreamObserver<SimpleResponse> responseObserver) {
+        SimpleResponse response = SimpleResponse.newBuilder()
+                .setResponseMessage("Hello " + request.getRequestMessage())
+                .build();
+        responseObserver.onNext(response);
+        responseObserver.onCompleted();
+    }
+}
+```
+
+> 使用注解方式添加指标需要添加 `spring-boot-starter-aop` 依赖！
+
+## Related Configurations
+
+```yaml
+grpc:
+  metrics:
+    enabled: true    # enable metrics
+    client:
+      enabled: true  # enable metrics for client
+      order: 0       # order of metrics client interceptor
+    server:
+      enabled: true  # enable metrics for server
+      order: 0       # order of metrics server interceptor
+```

docs/zh-cn/extension/tracing.md

@@ -0,0 +1,55 @@
+## Overview
+
+Tracing 扩展了 Spring Boot Actuator，为 gRPC 服务端和客户端提供了链路追踪功能。
+
+> Tracing extension works with Spring Boot 3.1.0+
+
+## Quick Start
+
+1. Start Zipkin
+
+   ```shell
+   docker run -t -p 9411:9411 openzipkin/zipkin
+   ```
+
+2. 引入依赖
+
+   ```groovy
+   implementation("com.freemanan:grpc-starter-tracing")
+   // Micrometer 支持的 Tracing system 可以参考 https://micrometer.io/docs/tracing
+   implementation("io.micrometer:micrometer-tracing-bridge-brave")
+   ```
+
+3. 配置 Zipkin 上报地址
+
+   ```yaml
+   management:
+     zipkin:
+       tracing:
+         endpoint: http://localhost:9411/api/v2/spans
+     tracing:
+       sampling:
+         probability: 1.0
+   ```
+
+4. Visit Zipkin UI
+
+    ```shell
+    curl http://localhost:9411
+    ```
+
+See [examples/tracing](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/tracing) for more details.
+
+## Related Configurations
+
+```yaml
+grpc:
+  tracing:
+    enabled: true    # enable tracing
+    client:
+      enabled: true  # enable tracing for client
+      order: 0       # order of tracing client interceptor
+    server:
+      enabled: true  # enable tracing for server
+      order: 0       # order of tracing server interceptor
+```

examples/metrics/README.md

@@ -0,0 +1,3 @@
+1. Start application
+
+2. Visit http://localhost:8080/actuator/prometheus

examples/metrics/build.gradle

@@ -0,0 +1,15 @@
+plugins {
+    id 'org.springframework.boot'
+}
+
+dependencies {
+    implementation(project(":examples:grpc-sample-api"))
+    implementation(project(":grpc-starters:grpc-boot-starter"))
+    implementation(project(":grpc-extensions:grpc-metrics"))
+
+    implementation("org.springframework.boot:spring-boot-starter-web")
+    implementation("org.springframework.boot:spring-boot-starter-aop")
+    implementation("io.micrometer:micrometer-registry-prometheus")
+
+    testImplementation(project(":grpc-starters:grpc-starter-test"))
+}

examples/metrics/src/main/java/com/freemanan/example/App.java

@@ -0,0 +1,44 @@
+package com.freemanan.example;
+
+import com.freemanan.starter.grpc.client.EnableGrpcClients;
+import io.grpc.testing.protobuf.SimpleRequest;
+import io.grpc.testing.protobuf.SimpleResponse;
+import io.grpc.testing.protobuf.SimpleServiceGrpc;
+import io.micrometer.core.instrument.Counter;
+import io.micrometer.core.instrument.MeterRegistry;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.ApplicationArguments;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * @author Freeman
+ */
+@SpringBootApplication
+@EnableGrpcClients("io.grpc")
+public class App implements ApplicationRunner {
+    private final Counter counter;
+
+    public App(MeterRegistry mr) {
+        this.counter = Counter.builder("app_run")
+                .description("app run")
+                .tags("app", "metrics-test")
+                .register(mr);
+    }
+
+    @Autowired
+    SimpleServiceGrpc.SimpleServiceBlockingStub stub;
+
+    public static void main(String[] args) {
+        SpringApplication.run(App.class, args);
+    }
+
+    @Override
+    public void run(ApplicationArguments args) throws Exception {
+        counter.increment();
+        SimpleResponse resp = stub.unaryRpc(
+                SimpleRequest.newBuilder().setRequestMessage("Hello").build());
+        System.out.println(resp);
+    }
+}

examples/metrics/src/main/java/com/freemanan/example/controller/SimpleServiceImpl.java

@@ -0,0 +1,27 @@
+package com.freemanan.example.controller;
+
+import io.grpc.stub.StreamObserver;
+import io.grpc.testing.protobuf.SimpleRequest;
+import io.grpc.testing.protobuf.SimpleResponse;
+import io.grpc.testing.protobuf.SimpleServiceGrpc;
+import io.micrometer.core.annotation.Counted;
+import io.micrometer.core.annotation.Timed;
+import org.springframework.stereotype.Controller;
+
+/**
+ * @author Freeman
+ */
+@Controller
+public class SimpleServiceImpl extends SimpleServiceGrpc.SimpleServiceImplBase {
+
+    @Override
+    @Timed("simple.unaryRpc")
+    @Counted("simple.unaryRpc")
+    public void unaryRpc(SimpleRequest request, StreamObserver<SimpleResponse> responseObserver) {
+        SimpleResponse response = SimpleResponse.newBuilder()
+                .setResponseMessage("Hello " + request.getRequestMessage())
+                .build();
+        responseObserver.onNext(response);
+        responseObserver.onCompleted();
+    }
+}

examples/metrics/src/main/resources/application.yaml

@@ -0,0 +1,20 @@
+spring:
+  application:
+    name: metrics-example
+
+grpc:
+  server:
+    reflection:
+      enabled: true
+  client:
+    authority: localhost:${grpc.server.port:9090}
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: '*'
+  metrics:
+    tags:
+      app: ${spring.application.name:UNKNOWN}
+debug: true

examples/metrics/src/test/java/com/freemanan/example/AppTest.java

@@ -0,0 +1,3 @@
+package com.freemanan.example;
+
+class AppTest {}

examples/tracing/README.md

@@ -0,0 +1,10 @@
+1. Start Zipkin server
+
+    ```shell
+    docker run -it -p 9411:9411 openzipkin/zipkin
+    ```
+
+2. Start the example
+
+3. Visit http://localhost:9411/zipkin/ to view the traces
+