Adding MRP analytics delegate (project-chip#37439)

This is a starting point for MRP events to be sent to some sort
of delegate interested.

The design is intentionally done in this way to reduce code size
within the SDK and is meant for applications such as a controller
to registers a delegate for MRP events allowing for it to construct
analytics.

---------

Co-authored-by: Restyled.io <commits@restyled.io>
Co-authored-by: Boris Zbarsky <bzbarsky@apple.com>

Author: 3 people

src/lib/core/BUILD.gn

@@ -71,6 +71,7 @@ buildconfig_header("chip_buildconfig") {
     "CHIP_CONFIG_TLV_VALIDATE_CHAR_STRING_ON_READ=${chip_tlv_validate_char_string_on_read}",
     "CHIP_CONFIG_COMMAND_SENDER_BUILTIN_SUPPORT_FOR_BATCHED_COMMANDS=${chip_enable_sending_batch_commands}",
     "CHIP_CONFIG_TEST_GOOGLETEST=${chip_build_tests_googletest}",
+    "CHIP_CONFIG_MRP_ANALYTICS_ENABLED=${chip_enable_mrp_analytics}",
   ]
 
   visibility = [ ":chip_config_header" ]

src/lib/core/CHIPConfig.h

@@ -1867,6 +1867,20 @@ extern const char CHIP_NON_PRODUCTION_MARKER[];
 #define CHIP_CONFIG_TEST_GOOGLETEST 0
 #endif // CHIP_CONFIG_TEST_GOOGLETEST
 
+/**
+ *  @def CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+ *
+ *  @brief
+ *    Enables code for collecting and sending analytic related events for MRP
+ *
+ * The purpose of this macro is to prevent compiling code related to MRP analytics
+ * for devices that are not interested interested to save on flash.
+ */
+
+#ifndef CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+#define CHIP_CONFIG_MRP_ANALYTICS_ENABLED 0
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+
 /**
  * @}
  */

src/lib/core/core.gni

@@ -126,6 +126,10 @@ declare_args() {
   chip_enable_sending_batch_commands =
       current_os == "linux" || current_os == "mac" || current_os == "ios" ||
       current_os == "android"
+
+  chip_enable_mrp_analytics =
+      current_os == "linux" || current_os == "android" || current_os == "mac" ||
+      current_os == "ios"
 }
 
 if (chip_target_style == "") {

src/messaging/BUILD.gn

@@ -63,6 +63,7 @@ static_library("messaging") {
     "ExchangeMgr.cpp",
     "ExchangeMgr.h",
     "Flags.h",
+    "ReliableMessageAnalyticsDelegate.h",
     "ReliableMessageContext.cpp",
     "ReliableMessageContext.h",
     "ReliableMessageMgr.cpp",

src/messaging/ReliableMessageAnalyticsDelegate.h

@@ -0,0 +1,74 @@
+/*
+ *    Copyright (c) 2025 Project CHIP Authors
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+/**
+ *    @file
+ *      This file defines an interface for objects interested in MRP events for analytics
+ */
+
+#pragma once
+
+#include <lib/core/DataModelTypes.h>
+#include <lib/core/NodeId.h>
+
+namespace chip {
+namespace Messaging {
+
+class ReliableMessageAnalyticsDelegate
+{
+public:
+    virtual ~ReliableMessageAnalyticsDelegate() = default;
+
+    enum class SessionType
+    {
+        kEstablishedCase,
+        // Initially, we are starting with only one session type, but we are considering the future when we expand to allow
+        // other session types, such as establishing a CASE session.
+    };
+
+    enum class EventType
+    {
+        // Event associated with first time this specific message is sent.
+        kInitialSend,
+        // Event associated with re-transmitting a message that was previously sent but not acknowledged.
+        kRetransmission,
+        // Event associated with receiving an acknowledgement of a previously sent message.
+        kAcknowledged,
+        // Event associated with transmission of a message that failed to be acknowledged.
+        kFailed,
+    };
+
+    struct TransmitEvent
+    {
+        // When the session has a peer node ID, this will be a value other than kUndefinedNodeId.
+        NodeId nodeId = kUndefinedNodeId;
+        // When the session has a fabric index, this will be a value other than kUndefinedFabricIndex.
+        FabricIndex fabricIndex = kUndefinedFabricIndex;
+        // Session type of session the message involved is being sent on.
+        SessionType sessionType = SessionType::kEstablishedCase;
+        // The transmit event type.
+        EventType eventType = EventType::kInitialSend;
+        // The outgoing message counter associated with the event. If there is no outgoing message counter
+        // this value will be 0.
+        uint32_t messageCounter = 0;
+    };
+
+    virtual void OnTransmitEvent(const TransmitEvent & event) = 0;
+};
+
+} // namespace Messaging
+} // namespace chip

src/messaging/ReliableMessageMgr.cpp

@@ -101,6 +101,35 @@ void ReliableMessageMgr::TicklessDebugDumpRetransTable(const char * log)
 #endif
 }
 
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+void ReliableMessageMgr::NotifyMessageSendAnalytics(const RetransTableEntry & entry, const SessionHandle & sessionHandle,
+                                                    const ReliableMessageAnalyticsDelegate::EventType & eventType)
+{
+    // For now we only support sending analytics for messages being sent over an established CASE session.
+    if (!mAnalyticsDelegate || !sessionHandle->IsSecureSession())
+    {
+        return;
+    }
+
+    auto secureSession = sessionHandle->AsSecureSession();
+    if (!secureSession->IsCASESession())
+    {
+        return;
+    }
+
+    uint32_t messageCounter                               = entry.retainedBuf.GetMessageCounter();
+    auto fabricIndex                                      = sessionHandle->GetFabricIndex();
+    auto destination                                      = secureSession->GetPeerNodeId();
+    ReliableMessageAnalyticsDelegate::TransmitEvent event = { .nodeId      = destination,
+                                                              .fabricIndex = fabricIndex,
+                                                              .sessionType =
+                                                                  ReliableMessageAnalyticsDelegate::SessionType::kEstablishedCase,
+                                                              .eventType      = eventType,
+                                                              .messageCounter = messageCounter };
+    mAnalyticsDelegate->OnTransmitEvent(event);
+}
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+
 void ReliableMessageMgr::ExecuteActions()
 {
     System::Clock::Timestamp now = System::SystemClock().GetMonotonicTimestamp();
@@ -155,6 +184,10 @@ void ReliableMessageMgr::ExecuteActions()
                          Transport::GetSessionTypeString(session), fabricIndex, ChipLogValueX64(destination),
                          CHIP_CONFIG_RMP_DEFAULT_MAX_RETRANS);
 
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+            NotifyMessageSendAnalytics(*entry, session, ReliableMessageAnalyticsDelegate::EventType::kFailed);
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+
             // If the exchange is expecting a response, it will handle sending
             // this notification once it detects that it has not gotten a
             // response.  Otherwise, we need to do it.
@@ -286,6 +319,9 @@ System::Clock::Timeout ReliableMessageMgr::GetBackoff(System::Clock::Timeout bas
 void ReliableMessageMgr::StartRetransmision(RetransTableEntry * entry)
 {
     CalculateNextRetransTime(*entry);
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+    NotifyMessageSendAnalytics(*entry, entry->ec->GetSessionHandle(), ReliableMessageAnalyticsDelegate::EventType::kInitialSend);
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
     StartTimer();
 }
 
@@ -295,6 +331,11 @@ bool ReliableMessageMgr::CheckAndRemRetransTable(ReliableMessageContext * rc, ui
     mRetransTable.ForEachActiveObject([&](auto * entry) {
         if (entry->ec->GetReliableMessageContext() == rc && entry->retainedBuf.GetMessageCounter() == ackMessageCounter)
         {
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+            auto session = entry->ec->GetSessionHandle();
+            NotifyMessageSendAnalytics(*entry, session, ReliableMessageAnalyticsDelegate::EventType::kAcknowledged);
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+
             // Clear the entry from the retransmision table.
             ClearRetransTable(*entry);
 
@@ -334,6 +375,10 @@ CHIP_ERROR ReliableMessageMgr::SendFromRetransTable(RetransTableEntry * entry)
 #if CHIP_CONFIG_ENABLE_ICD_SERVER
         app::ICDNotifier::GetInstance().NotifyNetworkActivityNotification();
 #endif // CHIP_CONFIG_ENABLE_ICD_SERVER
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+        NotifyMessageSendAnalytics(*entry, entry->ec->GetSessionHandle(),
+                                   ReliableMessageAnalyticsDelegate::EventType::kRetransmission);
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
 #if CHIP_CONFIG_RESOLVE_PEER_ON_FIRST_TRANSMIT_FAILURE
         const ExchangeManager * exchangeMgr = entry->ec->GetExchangeMgr();
         // TODO: investigate why in ReliableMessageMgr::CheckResendApplicationMessageWithPeerExchange unit test released exchange
@@ -440,6 +485,13 @@ void ReliableMessageMgr::RegisterSessionUpdateDelegate(SessionUpdateDelegate * s
     mSessionUpdateDelegate = sessionUpdateDelegate;
 }
 
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+void ReliableMessageMgr::RegisterAnalyticsDelegate(ReliableMessageAnalyticsDelegate * analyticsDelegate)
+{
+    mAnalyticsDelegate = analyticsDelegate;
+}
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+
 CHIP_ERROR ReliableMessageMgr::MapSendError(CHIP_ERROR error, uint16_t exchangeId, bool isInitiator)
 {
     if (

src/messaging/ReliableMessageMgr.h

@@ -31,6 +31,7 @@
 #include <lib/support/BitFlags.h>
 #include <lib/support/Pool.h>
 #include <messaging/ExchangeContext.h>
+#include <messaging/ReliableMessageAnalyticsDelegate.h>
 #include <messaging/ReliableMessageProtocolConfig.h>
 #include <system/SystemLayer.h>
 #include <system/SystemPacketBuffer.h>
@@ -185,6 +186,15 @@ class ReliableMessageMgr
      */
     void RegisterSessionUpdateDelegate(SessionUpdateDelegate * sessionUpdateDelegate);
 
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+    /**
+     *  Registers a delegate interested in analytic information
+     *
+     *  @param[in] analyticsDelegate - Pointer to delegate for reporting analytic
+     */
+    void RegisterAnalyticsDelegate(ReliableMessageAnalyticsDelegate * analyticsDelegate);
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+
     /**
      * Map a send error code to the error code we should actually use for
      * success checks.  This maps some error codes to CHIP_NO_ERROR as
@@ -245,10 +255,18 @@ class ReliableMessageMgr
 
     void TicklessDebugDumpRetransTable(const char * log);
 
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+    void NotifyMessageSendAnalytics(const RetransTableEntry & entry, const SessionHandle & sessionHandle,
+                                    const ReliableMessageAnalyticsDelegate::EventType & eventType);
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+
     // ReliableMessageProtocol Global tables for timer context
     ObjectPool<RetransTableEntry, CHIP_CONFIG_RMP_RETRANS_TABLE_SIZE> mRetransTable;
 
     SessionUpdateDelegate * mSessionUpdateDelegate = nullptr;
+#if CHIP_CONFIG_MRP_ANALYTICS_ENABLED
+    ReliableMessageAnalyticsDelegate * mAnalyticsDelegate = nullptr;
+#endif // CHIP_CONFIG_MRP_ANALYTICS_ENABLED
 
     static System::Clock::Timeout sAdditionalMRPBackoffTime;
 };