Merge pull request #171 from OpenElements/interceptors

Metrics support for Spring started

Author: hendrikebbers

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/implementation/ProtocolLayerClientImpl.java

@@ -23,15 +23,15 @@
 import com.hedera.hashgraph.sdk.Query;
 import com.hedera.hashgraph.sdk.SubscriptionHandle;
 import com.hedera.hashgraph.sdk.TokenAssociateTransaction;
-import com.hedera.hashgraph.sdk.TokenDissociateTransaction;
 import com.hedera.hashgraph.sdk.TokenBurnTransaction;
 import com.hedera.hashgraph.sdk.TokenCreateTransaction;
+import com.hedera.hashgraph.sdk.TokenDissociateTransaction;
 import com.hedera.hashgraph.sdk.TokenMintTransaction;
 import com.hedera.hashgraph.sdk.TopicCreateTransaction;
-import com.hedera.hashgraph.sdk.TopicUpdateTransaction;
 import com.hedera.hashgraph.sdk.TopicDeleteTransaction;
 import com.hedera.hashgraph.sdk.TopicMessageQuery;
 import com.hedera.hashgraph.sdk.TopicMessageSubmitTransaction;
+import com.hedera.hashgraph.sdk.TopicUpdateTransaction;
 import com.hedera.hashgraph.sdk.Transaction;
 import com.hedera.hashgraph.sdk.TransactionReceipt;
 import com.hedera.hashgraph.sdk.TransactionRecord;
@@ -41,6 +41,10 @@
 import com.openelements.hiero.base.HieroException;
 import com.openelements.hiero.base.data.Account;
 import com.openelements.hiero.base.data.ContractParam;
+import com.openelements.hiero.base.interceptors.ReceiveRecordInterceptor;
+import com.openelements.hiero.base.interceptors.ReceiveRecordInterceptor.ReceiveRecordHandler;
+import com.openelements.hiero.base.protocol.ProtocolLayerClient;
+import com.openelements.hiero.base.protocol.TransactionListener;
 import com.openelements.hiero.base.protocol.data.AccountBalanceRequest;
 import com.openelements.hiero.base.protocol.data.AccountBalanceResponse;
 import com.openelements.hiero.base.protocol.data.AccountCreateRequest;
@@ -65,34 +69,33 @@
 import com.openelements.hiero.base.protocol.data.FileInfoResponse;
 import com.openelements.hiero.base.protocol.data.FileUpdateRequest;
 import com.openelements.hiero.base.protocol.data.FileUpdateResult;
-import com.openelements.hiero.base.protocol.ProtocolLayerClient;
 import com.openelements.hiero.base.protocol.data.TokenAssociateRequest;
 import com.openelements.hiero.base.protocol.data.TokenAssociateResult;
-import com.openelements.hiero.base.protocol.data.TokenDissociateRequest;
-import com.openelements.hiero.base.protocol.data.TokenDissociateResult;
 import com.openelements.hiero.base.protocol.data.TokenBurnRequest;
 import com.openelements.hiero.base.protocol.data.TokenBurnResult;
 import com.openelements.hiero.base.protocol.data.TokenCreateRequest;
 import com.openelements.hiero.base.protocol.data.TokenCreateResult;
+import com.openelements.hiero.base.protocol.data.TokenDissociateRequest;
+import com.openelements.hiero.base.protocol.data.TokenDissociateResult;
 import com.openelements.hiero.base.protocol.data.TokenMintRequest;
 import com.openelements.hiero.base.protocol.data.TokenMintResult;
 import com.openelements.hiero.base.protocol.data.TokenTransferRequest;
 import com.openelements.hiero.base.protocol.data.TokenTransferResult;
 import com.openelements.hiero.base.protocol.data.TopicCreateRequest;
 import com.openelements.hiero.base.protocol.data.TopicCreateResult;
-import com.openelements.hiero.base.protocol.data.TopicUpdateRequest;
-import com.openelements.hiero.base.protocol.data.TopicUpdateResult;
 import com.openelements.hiero.base.protocol.data.TopicDeleteRequest;
 import com.openelements.hiero.base.protocol.data.TopicDeleteResult;
 import com.openelements.hiero.base.protocol.data.TopicMessageRequest;
 import com.openelements.hiero.base.protocol.data.TopicMessageResult;
 import com.openelements.hiero.base.protocol.data.TopicSubmitMessageRequest;
 import com.openelements.hiero.base.protocol.data.TopicSubmitMessageResult;
-import com.openelements.hiero.base.protocol.TransactionListener;
+import com.openelements.hiero.base.protocol.data.TopicUpdateRequest;
+import com.openelements.hiero.base.protocol.data.TopicUpdateResult;
 import com.openelements.hiero.base.protocol.data.TransactionType;
 import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Consumer;
 import org.jspecify.annotations.NonNull;
 import org.slf4j.Logger;
@@ -108,11 +111,20 @@ public class ProtocolLayerClientImpl implements ProtocolLayerClient {
 
     private final HieroContext hieroContext;
 
+    private final AtomicReference<ReceiveRecordInterceptor> recordInterceptor = new AtomicReference<>(
+            ReceiveRecordInterceptor.DEFAULT_INTERCEPTOR);
+
     public ProtocolLayerClientImpl(@NonNull final HieroContext hieroContext) {
         this.hieroContext = Objects.requireNonNull(hieroContext, "hieroContext must not be null");
         listeners = new CopyOnWriteArrayList<>();
     }
 
+    public void setRecordInterceptor(
+            @NonNull final ReceiveRecordInterceptor recordInterceptor) {
+        Objects.requireNonNull(recordInterceptor, "recordInterceptor must not be null");
+        this.recordInterceptor.set(recordInterceptor);
+    }
+
     @Override
     public AccountBalanceResponse executeAccountBalanceQuery(@NonNull final AccountBalanceRequest request)
             throws HieroException {
@@ -618,7 +630,10 @@ private <T extends Transaction<T>> TransactionRecord executeTransactionAndWaitOn
         try {
             log.debug("Waiting for record of transaction '{}' of type {}", receipt.transactionId,
                     transaction.getClass().getSimpleName());
-            return receipt.transactionId.getRecord(hieroContext.getClient());
+
+            final ReceiveRecordHandler data = new ReceiveRecordHandler(transaction, receipt,
+                    r -> r.transactionId.getRecord(hieroContext.getClient()));
+            return recordInterceptor.get().getRecordFor(data);
         } catch (final Exception e) {
             throw new HieroException("Failed to receive record of transaction '" + receipt.transactionId + "' of type "
                     + transaction.getClass(), e);

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/interceptors/ReceiveRecordInterceptor.java

@@ -0,0 +1,76 @@
+package com.openelements.hiero.base.interceptors;
+
+import com.hedera.hashgraph.sdk.Transaction;
+import com.hedera.hashgraph.sdk.TransactionReceipt;
+import com.hedera.hashgraph.sdk.TransactionRecord;
+import java.util.Objects;
+import org.jspecify.annotations.NonNull;
+
+/**
+ * First simple interceptor for receiving a record. This interceptor is used to intercept the call for receiving a
+ * record for a transaction. Frameworks like Spring can use this interceptor to add functionalities like metrics,
+ * tracing, or logging to the calls.
+ */
+@FunctionalInterface
+public interface ReceiveRecordInterceptor {
+
+    /**
+     * Default interceptor that does nothing.
+     */
+    ReceiveRecordInterceptor DEFAULT_INTERCEPTOR = data -> data.handle();
+
+    /**
+     * Intercept the call for receiving a record for a transaction.
+     *
+     * @param handler the handler that will be used to receive the record
+     * @return the record for the transaction
+     * @throws Exception if the interceptor fails
+     */
+    @NonNull
+    TransactionRecord getRecordFor(@NonNull ReceiveRecordHandler handler) throws Exception;
+
+    /**
+     * Handler for receiving a record for a transaction.
+     *
+     * @param transaction the transaction for which the record is received
+     * @param receipt     the receipt for the transaction
+     * @param function    the function that will be used to receive the record
+     */
+    record ReceiveRecordHandler(@NonNull Transaction transaction, @NonNull TransactionReceipt receipt,
+                                @NonNull ReceiveRecordFunction function) {
+
+        public ReceiveRecordHandler {
+            Objects.requireNonNull(transaction, "transaction must not be null");
+            Objects.requireNonNull(receipt, "receipt must not be null");
+            Objects.requireNonNull(function, "handler must not be null");
+        }
+
+        /**
+         * Handle the call for receiving a record for a transaction.
+         *
+         * @return the record for the transaction
+         * @throws Exception if the interceptor fails
+         */
+        @NonNull
+        public TransactionRecord handle() throws Exception {
+            return function.handle(receipt);
+        }
+    }
+
+    /**
+     * Function that will be used to receive the record for a transaction.
+     */
+    @FunctionalInterface
+    interface ReceiveRecordFunction {
+
+        /**
+         * Handle the call for receiving a record for a transaction.
+         *
+         * @param receipt the receipt for the transaction
+         * @return the record for the transaction
+         * @throws Exception if the interceptor fails
+         */
+        @NonNull
+        TransactionRecord handle(@NonNull TransactionReceipt receipt) throws Exception;
+    }
+}

hiero-enterprise-base/src/main/java/module-info.java

@@ -9,6 +9,7 @@
     exports com.openelements.hiero.base.implementation.data to com.openelements.hiero.base.test;
     exports com.openelements.hiero.base.config.implementation;
     exports com.openelements.hiero.base.protocol.data;
+    exports com.openelements.hiero.base.interceptors to com.openelements.hiero.base.test;
 
     uses com.openelements.hiero.base.config.NetworkSettingsProvider;
     provides com.openelements.hiero.base.config.NetworkSettingsProvider with com.openelements.hiero.base.config.hedera.HederaNetworkSettingsProvider;

hiero-enterprise-spring-sample/pom.xml

@@ -22,10 +22,18 @@
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-actuator</artifactId>
+    </dependency>
     <dependency>
       <groupId>${project.groupId}</groupId>
       <artifactId>hiero-enterprise-spring</artifactId>
     </dependency>
+    <dependency>
+      <groupId>io.micrometer</groupId>
+      <artifactId>micrometer-registry-prometheus</artifactId>
+    </dependency>
     <dependency>
       <groupId>io.grpc</groupId>
       <artifactId>grpc-okhttp</artifactId>

hiero-enterprise-spring-sample/src/main/java/com/openelements/hiero/spring/sample/Application.java

@@ -1,13 +1,18 @@
 package com.openelements.hiero.spring.sample;
 
 import com.openelements.hiero.spring.EnableHiero;
+import io.micrometer.core.instrument.MeterRegistry;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
 @SpringBootApplication
 @EnableHiero
 public class Application {
 
+    @Autowired
+    MeterRegistry registry;
+
     public static void main(String[] args) {
         SpringApplication.run(Application.class, args);
     }

hiero-enterprise-spring-sample/src/main/resources/application.properties

@@ -1,8 +1,9 @@
 spring.config.import=optional:file:.env[.properties]
-
 spring.hiero.accountId=${HEDERA_ACCOUNT_ID:0.0.123}
 spring.hiero.privateKey=${HEDERA_PRIVATE_KEY}
-spring.hiero.network.name=${HEDERA_NETWORK:testnet}
-
+spring.hiero.network.name=${HEDERA_NETWORK:hedera-testnet}
 logging.level.com.openelements=DEBUG
 logging.pattern.console=%d{HH:mm:ss.SSS} %logger{36} - %msg%n
+server.port=${SERVER_PORT:8080}
+# Needs to be done to activate the actuator endpoints (for metrics)
+management.endpoints.web.exposure.include=*

hiero-enterprise-spring/pom.xml

@@ -43,6 +43,11 @@
       <artifactId>spring-boot-configuration-processor</artifactId>
       <optional>true</optional>
     </dependency>
+    <dependency>
+      <groupId>io.micrometer</groupId>
+      <artifactId>micrometer-core</artifactId>
+      <optional>true</optional>
+    </dependency>
     <dependency>
       <groupId>${project.groupId}</groupId>
       <artifactId>hiero-enterprise-test</artifactId>

hiero-enterprise-spring/src/main/java/com/openelements/hiero/spring/implementation/HieroAutoConfiguration.java

@@ -14,36 +14,41 @@
 import com.openelements.hiero.base.implementation.FungibleTokenClientImpl;
 import com.openelements.hiero.base.implementation.NetworkRepositoryImpl;
 import com.openelements.hiero.base.implementation.NftClientImpl;
-import com.openelements.hiero.base.implementation.TopicClientImpl;
 import com.openelements.hiero.base.implementation.NftRepositoryImpl;
-import com.openelements.hiero.base.implementation.TopicRepositoryImpl;
 import com.openelements.hiero.base.implementation.ProtocolLayerClientImpl;
 import com.openelements.hiero.base.implementation.SmartContractClientImpl;
 import com.openelements.hiero.base.implementation.TokenRepositoryImpl;
+import com.openelements.hiero.base.implementation.TopicClientImpl;
+import com.openelements.hiero.base.implementation.TopicRepositoryImpl;
 import com.openelements.hiero.base.implementation.TransactionRepositoryImpl;
+import com.openelements.hiero.base.interceptors.ReceiveRecordInterceptor;
 import com.openelements.hiero.base.mirrornode.AccountRepository;
 import com.openelements.hiero.base.mirrornode.MirrorNodeClient;
 import com.openelements.hiero.base.mirrornode.NetworkRepository;
 import com.openelements.hiero.base.mirrornode.NftRepository;
 import com.openelements.hiero.base.mirrornode.TokenRepository;
-import com.openelements.hiero.base.mirrornode.TransactionRepository;
 import com.openelements.hiero.base.mirrornode.TopicRepository;
+import com.openelements.hiero.base.mirrornode.TransactionRepository;
 import com.openelements.hiero.base.protocol.ProtocolLayerClient;
 import com.openelements.hiero.base.verification.ContractVerificationClient;
 import java.net.URI;
 import java.net.URL;
 import java.util.List;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Import;
 import org.springframework.web.client.RestClient;
 import org.springframework.web.context.annotation.ApplicationScope;
 
 @AutoConfiguration
 @EnableConfigurationProperties({HieroProperties.class, HieroNetworkProperties.class})
+@Import({MicrometerSupportConfig.class})
 public class HieroAutoConfiguration {
 
     private static final Logger log = LoggerFactory.getLogger(HieroAutoConfiguration.class);
@@ -61,8 +66,13 @@ HieroContext hieroContext(final HieroConfig hieroConfig) {
     }
 
     @Bean
-    ProtocolLayerClient protocolLevelClient(final HieroContext hieroContext) {
-        return new ProtocolLayerClientImpl(hieroContext);
+    ProtocolLayerClient protocolLevelClient(final HieroContext hieroContext,
+            @Autowired(required = false) final ReceiveRecordInterceptor interceptor) {
+        ProtocolLayerClientImpl protocolLayerClient = new ProtocolLayerClientImpl(hieroContext);
+        if (interceptor != null) {
+            protocolLayerClient.setRecordInterceptor(interceptor);
+        }
+        return protocolLayerClient;
     }
 
     @Bean

hiero-enterprise-spring/src/main/java/com/openelements/hiero/spring/implementation/MicrometerSupportConfig.java

@@ -0,0 +1,64 @@
+package com.openelements.hiero.spring.implementation;
+
+import com.hedera.hashgraph.sdk.ContractExecuteTransaction;
+import com.hedera.hashgraph.sdk.TransactionRecord;
+import com.openelements.hiero.base.interceptors.ReceiveRecordInterceptor;
+import io.micrometer.core.instrument.Counter;
+import io.micrometer.core.instrument.MeterRegistry;
+import io.micrometer.core.instrument.Tag;
+import io.micrometer.core.instrument.Timer;
+import java.util.HashSet;
+import java.util.Set;
+import org.jspecify.annotations.NonNull;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * Micrometer support for Hiero. This configuration class is used to create a {@link ReceiveRecordInterceptor} that will
+ * measure metrics for Hiero transactions. The config is only loaded if the {@code spring.hiero.metrics.enabled}
+ * property is set to {@code true} or not set at all. Next to that, the {@code MetricsAutoConfiguration} configuration
+ * must be on the classpath.
+ */
+@AutoConfiguration
+@ConditionalOnProperty(name = "spring.hiero.metrics.enabled", havingValue = "true", matchIfMissing = true)
+@ConditionalOnClass(name = "org.springframework.boot.actuate.autoconfigure.metrics.MetricsAutoConfiguration")
+public class MicrometerSupportConfig {
+
+    public static final String TRANSACTION_TYPE_TAG = "hiero.transaction.record.type";
+    public static final String CONTRACT_ID_TAG = "hiero.transaction.record.contractId";
+    public static final String TIMER_NAME = "hiero.transaction.record.time";
+    public static final String COUNTER_NAME = "hiero.transaction.record";
+
+    /**
+     * Creates a {@link ReceiveRecordInterceptor} that will measure metrics for Hiero transactions.
+     *
+     * @param meterRegistry the {@link MeterRegistry} to use for metrics
+     * @return the {@link ReceiveRecordInterceptor} to use for metrics
+     */
+    @Bean
+    @NonNull
+    public ReceiveRecordInterceptor interceptRecordReceive(@NonNull final MeterRegistry meterRegistry) {
+        return handler -> {
+            final String transactionType = handler.transaction().getClass().getSimpleName();
+            final Set<Tag> tags = new HashSet<>();
+            tags.add(Tag.of(TRANSACTION_TYPE_TAG, transactionType));
+            if (handler.transaction() instanceof ContractExecuteTransaction contractExecuteTransaction) {
+                tags.add(Tag.of(CONTRACT_ID_TAG,
+                        contractExecuteTransaction.getContractId().toString()));
+            }
+            final Timer timer = meterRegistry.timer(TIMER_NAME, tags);
+            final Counter counter = meterRegistry.counter(COUNTER_NAME, tags);
+            return timer.record(() -> {
+                try {
+                    final TransactionRecord transactionRecord = handler.handle();
+                    counter.increment();
+                    return transactionRecord;
+                } catch (Exception e) {
+                    throw new RuntimeException("Error in handling record interceptor", e);
+                }
+            });
+        };
+    }
+}