RSDK-5986: Resource-level logging for the C++ SDK (#383)

Co-authored-by: Ethan <[email protected]>

Author: lia-viam

.github/workflows/test.yml

@@ -14,6 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     container: ghcr.io/viamrobotics/cpp-base:bullseye-amd64
     strategy:
+      fail-fast: false
       matrix:
         include:
           - BUILD_SHARED: ON

CMakeLists.txt

@@ -345,7 +345,18 @@ if (VIAMCPPSDK_BUILD_TESTS)
   set(VIAMCPPSDK_BOOST_TEST "unit_test_framework")
 endif()
 
-find_package(Boost ${VIAMCPPSDK_BOOST_VERSION_MINIMUM} REQUIRED COMPONENTS headers log program_options ${VIAMCPPSDK_BOOST_TEST})
+if (VIAMCPPSDK_BUILD_EXAMPLES)
+  set(VIAMCPPSDK_BOOST_PROGRAM_OPTIONS "program_options")
+endif()
+
+find_package(Boost ${VIAMCPPSDK_BOOST_VERSION_MINIMUM} REQUIRED 
+  COMPONENTS 
+    headers 
+    log 
+    log_setup 
+    ${VIAMCPPSDK_BOOST_PROGRAM_OPTIONS}
+    ${VIAMCPPSDK_BOOST_TEST}
+)
 
 # Time to find `protobuf` and `gRPC[++]`. Normally this would just be
 # something like `find_package(gRPC <version> CONFIG REQUIRED)`, and

README.md

@@ -88,6 +88,15 @@ above) should resolve them. And please file a bug report! We will
 endeavor to be as responsive as possible, and resolve issues as
 quickly as possible.
 
+## A note on logging
+
+Users should only interact with logging via the macros, classes, and functions in
+[`viam/sdk/log/logging.hpp`](src/viam/sdk/log/logging.hpp). Logging is 
+implemented using Boost.Log, but this is an implementation detail subject
+to change without warning. In particular, using Boost.Log macros such as
+`BOOST_LOG_TRIVIAL` or `BOOST_LOG_SEV` is undefined behavior which will likely 
+fail to output log messages.
+
 ## License
 Copyright 2022 Viam Inc.
 

etc/docker/tests/run_test.sh

@@ -34,7 +34,7 @@ popd
 if [ ${BUILD_SHARED} = "ON" ]
 then
 	pushd pkg-config
-	PKG_CONFIG_PATH=${INSTALL_DIR}/lib/pkgconfig make all
+	PKG_CONFIG_PATH=${INSTALL_DIR}/lib/pkgconfig CXXFLAGS="-DBOOST_LOG_DYN_LINK" make all
 	run_module
 	popd
 fi

src/viam/config/viam-cpp-sdkConfig.cmake.in

@@ -2,7 +2,7 @@
 
 include(CMakeFindDependencyMacro)
 
-find_dependency(Boost @Boost_VERSION_MAJOR@.@Boost_VERSION_MINOR@ COMPONENTS headers log)
+find_dependency(Boost @Boost_VERSION_MAJOR@.@Boost_VERSION_MINOR@ COMPONENTS headers log log_setup)
 
 if (@gRPC_FOUND@)
   find_dependency(gRPC @gRPC_VERSION_MAJOR@.@gRPC_VERSION_MINOR@ CONFIG)

src/viam/examples/camera/example_camera.cpp

@@ -4,97 +4,80 @@
 
 #include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/components/camera.hpp>
+#include <viam/sdk/log/logging.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/rpc/dial.hpp>
 
-int main() {
-    using std::cerr;
-    using std::cout;
-    using std::endl;
+int main() try {
     namespace vs = ::viam::sdk;
-    try {
-        // Every Viam C++ SDK program must have one and only one Instance object which is created
-        // before
-        // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
-        vs::Instance inst;
-
-        // If you want to connect to a remote robot, this should be the url of the robot
-        // Ex: xxx.xxx.viam.cloud
-        std::string robot_address("localhost:8080");
-        // If you want to connect to a remote robot, you need some authentication secret
-        // You can find this on app.viam.com
-        vs::Credentials credentials("", "");
-
-        vs::DialOptions dial_options;
-
-        // If you have credentials, use this to pass them to the robot
-        // dial_options.credentials = credentials;
-
-        // This is for an example. Care should be taken before exercising this option in production.
-        dial_options.set_allow_insecure_downgrade(
-            (credentials.type().empty() && credentials.payload().empty()));
-
-        // Set the refresh interval of the robot (in seconds) (0 = auto refresh) and the dial
-        // options
-        vs::Options options = vs::Options(1, dial_options);
-
-        std::shared_ptr<vs::RobotClient> robot;
-        try {
-            robot = vs::RobotClient::at_address(robot_address, options);
-            cout << "Successfully connected to the robot" << endl;
-        } catch (const std::exception& e) {
-            cerr << "Failed to connect to the robot. Exiting." << endl;
-            throw;
-        }
-
-        std::vector<vs::Name> resource_names = robot->resource_names();
-
-        cout << "Resources of the robot:" << endl;
-        for (const auto& resource : resource_names) {
-            cout << " - " << resource.name() << " (" << resource.api().resource_subtype() << ")"
-                 << endl;
-        }
-
-        std::string camera_name("camera1");
-
-        cout << "Getting camera: " << camera_name << endl;
-        std::shared_ptr<vs::Camera> camera;
-        try {
-            camera = robot->resource_by_name<vs::Camera>(camera_name);
-        } catch (const std::exception& e) {
-            cerr << "Failed to find " << camera_name << ". Exiting." << endl;
-            throw;
-        }
-        vs::Camera::properties props = camera->get_properties();
-        vs::Camera::intrinsic_parameters intrinsics = props.intrinsic_parameters;
-        cout << "Image dimensions: " << intrinsics.width_px << " x " << intrinsics.height_px
-             << endl;
-
-        std::string output_file("img.png");
-        std::string image_mime_type("image/png");
-
-        cout << "Getting image from camera " << endl;
-        vs::Camera::raw_image img = camera->get_image(image_mime_type);
-        cout << "Got image of mime type: " << img.mime_type << endl;
-
-        cout << "Getting and saving image to " << output_file << endl;
-        std::ofstream fout;
-        fout.open(output_file, std::ios::binary | std::ios::out);
-        if (fout.fail()) {
-            throw std::runtime_error("Failed to open output file " + output_file);
-        }
-        fout.write(reinterpret_cast<char*>(img.bytes.data()), img.bytes.size());
-        fout.close();
-        if (fout.fail()) {
-            throw std::runtime_error("Failed to write and close output file " + output_file);
-        }
-    } catch (const std::exception& ex) {
-        cerr << "Program failed. Exception: " << std::string(ex.what()) << endl;
-        return EXIT_FAILURE;
-    } catch (...) {
-        cerr << "Program failed without exception message." << endl;
-        return EXIT_FAILURE;
+    // Every Viam C++ SDK program must have one and only one Instance object which is created
+    // before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    vs::Instance inst;
+
+    // If you want to connect to a remote robot, this should be the url of the robot
+    // Ex: xxx.xxx.viam.cloud
+    std::string robot_address("localhost:8080");
+    // If you want to connect to a remote robot, you need some authentication secret
+    // You can find this on app.viam.com
+    vs::Credentials credentials("", "");
+
+    vs::DialOptions dial_options;
+
+    // If you have credentials, use this to pass them to the robot
+    // dial_options.credentials = credentials;
+
+    // This is for an example. Care should be taken before exercising this option in production.
+    dial_options.set_allow_insecure_downgrade(
+        (credentials.type().empty() && credentials.payload().empty()));
+
+    // Set the refresh interval of the robot (in seconds) (0 = auto refresh) and the dial
+    // options
+    vs::Options options = vs::Options(1, dial_options);
+
+    std::shared_ptr<vs::RobotClient> robot = vs::RobotClient::at_address(robot_address, options);
+    VIAM_SDK_LOG(info) << "Successfully connected to the robot";
+
+    std::vector<vs::Name> resource_names = robot->resource_names();
+
+    VIAM_SDK_LOG(info) << "Resources of the robot:";
+    for (const auto& resource : resource_names) {
+        VIAM_SDK_LOG(info) << " - " << resource.name() << " (" << resource.api().resource_subtype()
+                           << ")";
     }
 
+    std::string camera_name("camera1");
+
+    VIAM_SDK_LOG(info) << "Getting camera: " << camera_name;
+    std::shared_ptr<vs::Camera> camera = robot->resource_by_name<vs::Camera>(camera_name);
+
+    vs::Camera::properties props = camera->get_properties();
+    vs::Camera::intrinsic_parameters intrinsics = props.intrinsic_parameters;
+    VIAM_SDK_LOG(info) << "Image dimensions: " << intrinsics.width_px << " x "
+                       << intrinsics.height_px;
+
+    std::string output_file("img.png");
+    std::string image_mime_type("image/png");
+
+    VIAM_SDK_LOG(info) << "Getting image from camera ";
+
+    vs::Camera::raw_image img = camera->get_image(image_mime_type);
+
+    VIAM_SDK_LOG(info) << "Got image of mime type: " << img.mime_type;
+
+    VIAM_SDK_LOG(info) << "Getting and saving image to " << output_file;
+
+    std::ofstream fout;
+
+    // Operations on the ofstream will throw on failure.
+    fout.exceptions(std::ofstream::failbit);
+    fout.open(output_file, std::ios::binary | std::ios::out);
+
+    fout.write(reinterpret_cast<char*>(img.bytes.data()), img.bytes.size());
+    fout.close();
+
     return EXIT_SUCCESS;
+} catch (const std::exception& ex) {
+    std::cerr << "Program failed. Exception: " << std::string(ex.what()) << "\n";
+    return EXIT_FAILURE;
 }

src/viam/examples/dial/example_dial.cpp

@@ -10,6 +10,7 @@
 
 #include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/components/generic.hpp>
+#include <viam/sdk/log/logging.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/rpc/dial.hpp>
 
@@ -35,15 +36,15 @@ int main() {
 
     // ensure we can query resources
     std::vector<Name> resource_names = robot->resource_names();
-    std::cout << "Resources" << std::endl;
+    VIAM_SDK_LOG(info) << "Resources:";
     for (const Name& resource : resource_names) {
-        std::cout << "\t" << resource << "\n";
+        VIAM_SDK_LOG(info) << resource;
     }
 
     // ensure we can create clients to the robot
     auto gc = robot->resource_by_name<GenericComponent>("generic1");
     if (gc) {
-        std::cout << "got generic component client named " << gc->name() << std::endl;
+        VIAM_SDK_LOG(info) << "got generic component client named " << gc->name();
     }
 
     return EXIT_SUCCESS;

src/viam/examples/dial_api_key/example_dial_api_key.cpp

@@ -49,9 +49,9 @@ int main(int argc, char* argv[]) {
 
     // ensure we can query resources
     std::vector<Name> resource_names = robot->resource_names();
-    std::cout << "Resources" << std::endl;
+    VIAM_SDK_LOG(info) << "Resources:";
     for (const Name& resource : resource_names) {
-        std::cout << "\t" << resource << "\n";
+        VIAM_SDK_LOG(info) << resource;
     }
 
     return EXIT_SUCCESS;