[Logging][Obj-C] Add external log writer interface.

c-treyz · c-treyz · commit 8e20b59be67d · 2020-11-16T19:10:32.000-07:00
* Adds NLWeaveLogWriter protocol for external clients to register a log
writer to pass Weave logs to a custom logging component.
* Adds NLWeaveLogging, with +[NLWeaveLogging setSharedLogWriter:], to
manage processing Weave logs.
* Updates WDM_LOG macros and nl::Weave::Logging::Log function to pass
logs to the new NLWeaveLogging manager.
diff --git a/src/device-manager/cocoa/NLLogging.h b/src/device-manager/cocoa/NLLogging.h
@@ -22,15 +22,53 @@
  *
  */
 
+#import <Foundation/Foundation.h>
+#import "NLWeaveLogging.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
 #if DEBUG
-#define WDM_LOG_DEBUG NSLog
-#define WDM_LOG_ERROR NSLog
 
-#define WDM_LOG_METHOD_SIG() ({ NSLog(@"[<%@: %p> %@]", NSStringFromClass([self class]), self, NSStringFromSelector(_cmd)); })
-#else
-// do nothing
+/** Name of the logging module for the Objective-C platform-specific component. */
+static NSString * const kNLWeaveDeviceManagerCocoaModuleName = @"DM-Cocoa";
+
+/** Macros for logging Weave messages of various log levels from platform-specific code. */
+#define WDM_LOG_DEBUG(fmt, ...) _WDM_LOG(NLLogLevelDetail, fmt, ##__VA_ARGS__)
+#define WDM_LOG_INFO(fmt, ...) _WDM_LOG(NLLogLevelProgress, fmt, ##__VA_ARGS__)
+#define WDM_LOG_ERROR(fmt, ...) _WDM_LOG(NLLogLevelError, fmt, ##__VA_ARGS__)
+
+/** Macro for logging a method signature (must be called from an Objective-C method). */
+#define WDM_LOG_METHOD_SIG() WDM_LOG_INFO(@"<%@: %p>", NSStringFromClass([self class]), self)
+
+/**
+ * @def _WDM_LOG(logLevel, fmt, ...)
+ *
+ * @brief
+ *   Helper macro for formatting Weave logs and delegating log handling to @c NLWeaveLogging.
+ *
+ *  @param logLevel An @c NLLogLevel specifying the level of the log message.
+ *  @param fmt The log message format.
+ *  @param ... A variable number of arguments to be added to the log message format.
+ */
+#define _WDM_LOG(logLevel, fmt, ...)                                                                                               \
+    do {                                                                                                                           \
+        NSString * formattedMessage = ([NSString                                                                                   \
+            stringWithFormat:@"%s:%d %@", __PRETTY_FUNCTION__, __LINE__, [NSString stringWithFormat:fmt, ##__VA_ARGS__]]);         \
+                                                                                                                                   \
+        [NLWeaveLogging handleWeaveLogFromModule:NLLogModuleCocoa                                                                  \
+                                      moduleName:kNLWeaveDeviceManagerCocoaModuleName                                              \
+                                           level:logLevel                                                                          \
+                                formattedMessage:formattedMessage];                                                                \
+    } while (0);
+
+#else // DEBUG
+
+// Do nothing – strip logs from release builds.
 #define WDM_LOG_DEBUG(...)
+#define WDM_LOG_INFO(...)
 #define WDM_LOG_ERROR(...)
 #define WDM_LOG_METHOD_SIG() ({})
 
-#endif
+#endif // DEBUG
+
+NS_ASSUME_NONNULL_END
diff --git a/src/device-manager/cocoa/NLWeaveLogWriter.h b/src/device-manager/cocoa/NLWeaveLogWriter.h
@@ -0,0 +1,51 @@
+/*
+ *
+ *    Copyright (c) 2020 Google LLC
+ *    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 the @c NLWeaveLogWriter protocol for an external Weave log writer.
+ *
+ */
+
+#import <Foundation/Foundation.h>
+#import "NLWeaveLogging.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Defines an interface for an external log writer to register to receive Weave logs.
+ *
+ * External clients can implement this protocol to receive Weave log messages for custom handling –
+ * the shared @c NLWeaveLogWriter can be set using +[NLWeaveLogging setSharedLogWriter:].
+ */
+@protocol NLWeaveLogWriter <NSObject>
+
+/**
+ * Method called with individual Weave log messages as they are logged.
+ *
+ * @param logModule The Weave module in which the log was created.
+ * @param logLevel The logging level of the log.
+ * @param logMessage The formatted log message.
+ */
+- (void)writeLogFromModule:(NLLogModule)logModule
+                     level:(NLLogLevel)logLevel
+                   message:(NSString *)logMessage NS_SWIFT_NAME(writeLog(from:level:message:));
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/src/device-manager/cocoa/NLWeaveLogging.h b/src/device-manager/cocoa/NLWeaveLogging.h
@@ -0,0 +1,128 @@
+/*
+ *
+ *    Copyright (c) 2020 Google LLC
+ *    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 implements a platform-specific Weave log interface.
+ *
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol NLWeaveLogWriter;
+
+/**
+ * Weave logging modules – for indicating which component created a log.
+ *
+ * @note
+ *   Must align with the order of nl::Weave::Logging::LogModule values.
+ */
+typedef NS_ENUM(NSInteger, NLLogModule) {
+    NLLogModuleNotSpecified = 0,
+
+    NLLogModuleInet,
+    NLLogModuleBle,
+    NLLogModuleMessageLayer,
+    NLLogModuleSecurityManager,
+    NLLogModuleExchangeManager,
+    NLLogModuleTLV,
+    NLLogModuleASN1,
+    NLLogModuleCrypto,
+    NLLogModuleDeviceManager,
+    NLLogModuleAlarm,
+    NLLogModuleBDX,
+    NLLogModuleDataManagement,
+    NLLogModuleDeviceControl,
+    NLLogModuleDeviceDescription,
+    NLLogModuleEcho,
+    NLLogModuleFabricProvisioning,
+    NLLogModuleNetworkProvisioning,
+    NLLogModuleServiceDirectory,
+    NLLogModuleServiceProvisioning,
+    NLLogModuleSoftwareUpdate,
+    NLLogModuleTokenPairing,
+    NLLogModuleHeatLink,
+    NLLogModuleTimeService,
+    NLLogModuleWeaveTunnel,
+    NLLogModuleHeartbeat,
+    NLLogModuleWeaveSystemLayer,
+    NLLogModuleDropcamLegacyPairing,
+    NLLogModuleEventLogging,
+    NLLogModuleSupport,
+
+    // Module for logs originating from the Objective-C @c NLLogging macros.
+    //
+    // Must NOT overlap with the values mapped from nl::Weave::Logging::LogModule.
+    NLLogModuleCocoa = 100,
+};
+
+/**
+ * Logging levels – for indicating the relative importance of a log message.
+ *
+ * @note
+ *   Must align with the order of nl::Weave::Logging::LogCategory values.
+ */
+typedef NS_ENUM(NSInteger, NLLogLevel) {
+    NLLogLevelNone = 0,
+    NLLogLevelError,
+    NLLogLevelProgress,
+    NLLogLevelDetail,
+    NLLogLevelRetain,
+};
+
+/**
+ * Platform-specific component for managing Weave log messages.
+ *
+ * Exposes an interface for external clients to configure the shared @c NLWeaveLogWriter – the log
+ * writer will receive Weave logs from both the shared C++ source code and the platform-specific
+ * Objective-C source code. This allows clients to connect Weave logs to their own logging system.
+ */
+@interface NLWeaveLogging : NSObject
+
+#pragma Logging Configuration
+
+/**
+ * Sets the shared @c NLWeaveLogWriter to start receiving Weave logs.
+ *
+ * @note
+ *   This should be called prior to any Weave operations to ensure the log writer has been
+ *   configured before any logs are written. The log writer will only receive messages logged after
+ *   it has been set as the shared writer.
+ */
++ (void)setSharedLogWriter:(nullable id<NLWeaveLogWriter>)logWriter;
+
+#pragma Log Methods
+
+/**
+ * Internal handler method for logging a message to the console and notifying the shared log writer.
+ *
+ * @param logModule The logging module to which the log belongs.
+ * @param logModuleName The name of the logging module.
+ * @param logLevel The level of the log message.
+ * @param formattedLogMessage The formatted log message.
+ */
++ (void)handleWeaveLogFromModule:(NLLogModule)logModule
+                      moduleName:(NSString *)logModuleName
+                           level:(NLLogLevel)logLevel
+                formattedMessage:(NSString *)formattedLogMessage;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/src/device-manager/cocoa/NLWeaveLogging.mm b/src/device-manager/cocoa/NLWeaveLogging.mm
