接續著前面的 Spring AOP，接著要在 Spring AOP 之上接 OpenTelemetry。實際上接 OpenTelemetry 才是我的目的，AOP 只是希望接 metric/tracing 時可以不要碰商業邏輯的程式碼而已 XD。
什麼是 OpenTelemetry
簡要來說，OpenTelemetry（簡稱 OTEL）是結合了 CNCF 發展的 OpenTracing 和 Google 發展的 OpenCensus 兩個專案後的結果 [1]，目的是為了提供 observibility telemetry。它涵蓋了三大主題：tracing、metrics、logs。tracing 能夠整合上下游的關係，提供完整的 profiling 資訊；metrics 能夠提供統計型的數據，讓我們可以快速了解系統的狀態；logs 則是文字型的資料。
不過就我目前的了解，OTEL 因為是在 2019 年才合併，到現在似乎還是沒有到非常完整，各個語言的支援有些可能還是有點缺漏。以 Java 來說，目前 tracing 和 metrics 的支援是比較好，logs 則還處於實驗中。細節可以參考 OTEL 官網中關於 Java SDK 的狀態頁 [2]。
OpenTelemetry Metrics 建置
因為我目前的目的是要建立 Metrics 的環境，把我的 Java application 的一些自訂資訊輸出到 Metrics 上，讓我們得以透過統計資訊了解系統的狀態，所以這篇主要只會紀錄關於 Metrics 的建置範例。
範例的目的
首先稍微簡介一下，這篇文章中的範例是設定成什麼背景、要解決什麼問題。承襲上一篇 Spring AOP 文章，我有一個 method 如下，這個 method 的角色是一個 event consumer，就是在收某種 queue 送過來的訊息。文章的目標是要透過 AOP 插入一個能夠統計收到的訊息的類型的 Metrics。有了這個 Metrics，就可以知道系統總共處理什麼量級的訊息，並且也可以用來做更細緻的統計，例如 Event 的設計是有分 eventType 和 owner，代表的是某個人送出的 Create/Update/Delete 指令，而 Metrics 希望能夠讓我們有能力得知例如在指定時間區間內，某個人送了多少指令、或者是總共有多少的 Create 指令等等。
@Slf4j
@Component
public class FakeEventProcessor {
public void receiveEvent(Event event) {
log.info("Receive: {}", event);
}
}
@Builder
@Getter
@Accessors(fluent = true)
@ToString
public class Event {
private String eventType;
private String owner;
}
完整的範例程式碼，可以參考 [3]。
Gradle 設定
在 Gradle 中，需要加入以下的 dependencies：
implementation(platform("io.opentelemetry:opentelemetry-bom:1.22.0"))
implementation(platform("io.opentelemetry:opentelemetry-bom-alpha:1.22.0-alpha"))
implementation("io.opentelemetry:opentelemetry-api")
implementation("io.opentelemetry:opentelemetry-sdk")
implementation("io.opentelemetry:opentelemetry-semconv")
implementation("io.opentelemetry:opentelemetry-exporter-logging")
這裡可以看到 BOM 會有兩個，其中 opentelemetry-bom-alpha 是用來設定 opentelemetry-semconv 的 BOM，而 opentelemetry-semconv 的用途，在我目前的範例程式裡，好像只有初始化 OTEL 時要給的 ResourceAttribute 會用到它…。另外因為這裡我先實驗的目標是最簡單的 Metrics，所以是採取 Logging 作為 Metrics 的 Exporter。換句話說，就是我寫入的 Metrics 會以 log 的形式被輸出。
初始化 OpenTelemetry
要使用 OTEL 的 Metrics 之前，需要先在系統裡初始化一個 OpenTelemetry 的 instance。我的範例中會是使用 @Configuration 來讓 Spring 幫忙注入。
@Configuration
public class OpenTelemetryConfiguration {
@Bean(destroyMethod = "")
public OpenTelemetry getTelemetry() {
var resource = Resource.getDefault()
.merge(Resource.create(
Attributes.of(ResourceAttributes.SERVICE_NAME, "otel-example")));
var sdkMeterProvider = SdkMeterProvider.builder()
.registerMetricReader(
PeriodicMetricReader.builder(LoggingMetricExporter.create())
.setInterval(Duration.ofSeconds(1))
.build())
.setResource(resource)
.build();
var openTelemetry = OpenTelemetrySdk.builder()
.setMeterProvider(sdkMeterProvider)
.buildAndRegisterGlobal();
return openTelemetry;
}
}
這裡首先用 Resource 做基本的環境設定，具體來說就只是設定一個 resource name 而已。接著因為我要產出 Metrics，所以需要的是 SdkMeterProvider。MeterProvider 的設定是輸出到 Logging，而且外面再包裝一層定時輸出的 MetricReader，設定為每一秒輸出一次。最後建出 OTEL 的 instance，把剛剛建立的 SdkMeterProvider 設定為它的 MeterProvider 即可。
在翻閱文件時，有個小細節是文件上有提到，如果是在為 library 建立 telemetry 的話，就建議不要 register global。雖然目前我還不太了解 register global 是什麼意思就是…。
建立 Aspect 為指定的 Method 插入 Metrics
文章最開頭有提到，我想要在插入 Metrics 統計的同時，不去修改既有的商業邏輯，所以 Metrics 的統計應該要發生在別的 class 而不應該直接寫在 FakeEventProcessor 中。因此我會另外建立一個 Aspect class，這個 class 會讓 Spring 注入上面寫到的 OpenTelemetry instance，然後在每次 FakeEventProcessor 的 receiveEvent(..) 被呼叫時，都攔截執行並把 event 的內容紀錄在 Metrics 當中。
@Slf4j
@Aspect
@Component
public class TelemetryAspect {
private OpenTelemetry telemetry;
private Meter meter;
private LongCounter eventCounter;
@Autowired
public TelemetryAspect(OpenTelemetry telemetry) {
log.trace("Initiate aspect...");
this.telemetry = telemetry;
initiateMeter();
}
private void initiateMeter() {
meter = telemetry.meterBuilder("event-consumer")
.setInstrumentationVersion("1.0.0")
.build();
eventCounter = meter.counterBuilder("eventType")
.setDescription("Metrics for the event consuming.")
.setUnit("1")
.build();
}
@Before("execution(* tw.jimwayneyeh.example.otel.FakeEventProcessor.receiveEvent(..))")
public void before(JoinPoint joinPoint) {
var event = (Event) joinPoint.getArgs()[0];
eventCounter.add(1, Attributes.of(
AttributeKey.stringKey("eventType"), event.eventType(),
AttributeKey.stringKey("owner"), event.owner()));
}
在上述的程式碼中，首先我在 Aspect 被初始化時，會去初始化一個 Meter，因為這個 Meter 是統計數字，所以就直接命名為 eventCounter。接著在 JointPoint 中，每次 receiveEvent(..) 被呼叫時，AOP 會攔截這個 method 呼叫，取得 method 呼叫中送進來的 event 物件，並且把為 eventCounter +1。其中 +1 時加的對象，是對 eventType & owner 做 +1。
最後執行的結果會長這樣：
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-0)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-1)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-1)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-1)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=delete, owner=owner-1)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=create, owner=owner-0)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-0)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=delete, owner=owner-1)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=create, owner=owner-0)
INFO t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=delete, owner=owner-0)
INFO t.j.e.otel.Run [main] Sleep...
INFO i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] Received a collection of 1 metrics for export.
INFO i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] metric: ImmutableMetricData{resource=Resource{schemaUrl=null, attributes={service.name="otel-example", telemetry.sdk.language="java", telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.22.0"}}, instrumentationScopeInfo=InstrumentationScopeInfo{name=event-consumer, version=1.0.0, schemaUrl=null, attributes={}}, name=eventType, description=Metrics for the event consuming., unit=1, type=LONG_SUM, data=ImmutableSumData{points=[ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="delete", owner="owner-1"}, value=2, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="create", owner="owner-0"}, value=2, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="delete", owner="owner-0"}, value=1, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="update", owner="owner-0"}, value=2, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="update", owner="owner-1"}, value=3, exemplars=[]}], monotonic=true, aggregationTemporality=CUMULATIVE}}
最上面 10 行是在 FakeEventProcessor 裡面寫的 log，然後因為我的 logging 設定為每秒輸出，所以故意讓主程式睡了一下，以避免主程式跑完迴圈以後就自己關掉了 XD。
i.o.e.l.LoggingMetricExporter 這段就是 Metrics 輸出的內容，稍微格式化一下：
ImmutableMetricData {
resource = Resource {
schemaUrl = null, attributes = {
service.name = "otel-example",
telemetry.sdk.language = "java",
telemetry.sdk.name = "opentelemetry",
telemetry.sdk.version = "1.22.0"
}
}, instrumentationScopeInfo = InstrumentationScopeInfo {
name = event - consumer, version = 1.0 .0, schemaUrl = null, attributes = {}
}, name = eventType, description = Metrics
for the event consuming., unit = 1, type = LONG_SUM, data = ImmutableSumData {
points = [ImmutableLongPointData {
startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
eventType = "delete",
owner = "owner-1"
}, value = 2, exemplars = []
}, ImmutableLongPointData {
startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
eventType = "create",
owner = "owner-0"
}, value = 2, exemplars = []
}, ImmutableLongPointData {
startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
eventType = "delete",
owner = "owner-0"
}, value = 1, exemplars = []
}, ImmutableLongPointData {
startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
eventType = "update",
owner = "owner-0"
}, value = 2, exemplars = []
}, ImmutableLongPointData {
startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
eventType = "update",
owner = "owner-1"
}, value = 3, exemplars = []
}], monotonic = true, aggregationTemporality = CUMULATIVE
}
}
可以看到，Metrics 紀錄到的結果是：
owner-1 delete: 1owner-0 create: 2owner-0 delete: 1owner-0 update: 2owner-1 update: 3
確實結果是符合 FakeEventProcessor 的結果～。