RSDK-6170 - add debug log support (#299)

Author: stuqdog

src/viam/examples/dial_api_key/example_dial_api_key.cpp

@@ -22,7 +22,6 @@
 #include <viam/sdk/robot/service.hpp>
 #include <viam/sdk/rpc/dial.hpp>
 
-using viam::robot::v1::Status;
 using namespace viam::sdk;
 
 namespace po = boost::program_options;

src/viam/sdk/common/client_helper.hpp

@@ -4,6 +4,7 @@
 #include <grpcpp/support/sync_stream.h>
 
 #include <viam/sdk/common/exception.hpp>
+#include <viam/sdk/common/private/utils.hpp>
 #include <viam/sdk/common/proto_value.hpp>
 #include <viam/sdk/common/utils.hpp>
 
@@ -53,6 +54,11 @@ class ClientHelper {
 
     template <typename RequestSetupCallable>
     ClientHelper& with(const ProtoStruct& extra, RequestSetupCallable&& rsc) {
+        auto key = extra.find(impl::debug_map_key);
+        if (key != extra.end()) {
+            ProtoValue value = key->second;
+            debug_key_ = *value.get<std::string>();
+        }
         *request_.mutable_extra() = map_to_struct(extra);
         return with(std::forward<RequestSetupCallable>(rsc));
     }
@@ -67,6 +73,9 @@ class ClientHelper {
         *request_.mutable_name() = client_->name();
         ClientContext ctx;
 
+        if (debug_key_ != "") {
+            ctx.set_debug_key(debug_key_);
+        }
         const auto result = (stub_->*pfn_)(ctx, request_, &response_);
         if (result.ok()) {
             return std::forward<ResponseHandlerCallable>(rhc)(
@@ -112,6 +121,7 @@ class ClientHelper {
    private:
     ClientType* client_;
     StubType* stub_;
+    std::string debug_key_;
     MethodType pfn_;
     RequestType request_;
     ResponseType response_;

src/viam/sdk/common/private/utils.hpp

@@ -0,0 +1,11 @@
+#pragma once
+
+namespace viam {
+namespace sdk {
+namespace impl {
+
+const char debug_map_key[] = "com.viam.debug_key_internal";
+
+}  // namespace impl
+}  // namespace sdk
+}  // namespace viam

src/viam/sdk/common/utils.cpp

@@ -1,5 +1,6 @@
 #include <viam/sdk/common/utils.hpp>
 
+#include <random>
 #include <unordered_map>
 #include <vector>
 
@@ -12,6 +13,7 @@
 
 #include <viam/api/common/v1/common.pb.h>
 
+#include <viam/sdk/common/private/utils.hpp>
 #include <viam/sdk/common/private/version_metadata.hpp>
 #include <viam/sdk/components/component.hpp>
 #include <viam/sdk/registry/registry.hpp>
@@ -106,6 +108,55 @@ void ClientContext::set_client_ctx_authority_() {
     wrapped_context_.set_authority("viam-placeholder");
 }
 
+std::string random_debug_key() {
+    static const char alphanum[] = "abcdefghijklmnopqrstuvwxyz";
+    static std::default_random_engine generator(
+        std::chrono::system_clock::now().time_since_epoch().count());
+    std::uniform_int_distribution<int> distribution(0, sizeof(alphanum) - 1);
+
+    std::string key;
+    key.reserve(6);
+
+    for (int i = 0; i < 6; ++i) {
+        key += alphanum[distribution(generator)];
+    };
+
+    return key;
+}
+
+ProtoStruct debug_map() {
+    return debug_map(random_debug_key());
+}
+
+ProtoStruct debug_map(std::string debug_key) {
+    ProtoStruct map;
+    map.emplace(impl::debug_map_key, ProtoValue(std::move(debug_key)));
+
+    return map;
+}
+
+void add_debug_entry(ProtoStruct& map, std::string debug_key) {
+    map.emplace(impl::debug_map_key, ProtoValue(std::move(debug_key)));
+}
+
+void add_debug_entry(ProtoStruct& map) {
+    add_debug_entry(map, random_debug_key());
+}
+
+ProtoStruct with_debug_entry(ProtoStruct&& map, std::string debug_key) {
+    add_debug_entry(map, std::move(debug_key));
+    return map;
+}
+
+ProtoStruct with_debug_entry(ProtoStruct&& map) {
+    add_debug_entry(map);
+    return map;
+}
+
+void ClientContext::set_debug_key(const std::string& debug_key) {
+    wrapped_context_.AddMetadata("dtname", debug_key);
+}
+
 void ClientContext::add_viam_client_version_() {
     wrapped_context_.AddMetadata("viam_client", impl::k_version);
 }

src/viam/sdk/common/utils.hpp

@@ -1,8 +1,5 @@
 #pragma once
 
-#include <cmath>
-#include <unordered_map>
-
 #include <boost/optional/optional.hpp>
 #include <grpcpp/client_context.h>
 
@@ -56,13 +53,37 @@ class ClientContext {
     ClientContext();
     operator grpc::ClientContext*();
     operator const grpc::ClientContext*() const;
+    void set_debug_key(const std::string& debug_key);
 
    private:
     void set_client_ctx_authority_();
     void add_viam_client_version_();
     grpc::ClientContext wrapped_context_;
 };
 
+/// @brief Returns a new `ProtoStruct` with a random key for server-side debug logging
+ProtoStruct debug_map();
+
+/// @brief Returns a new `ProtoStruct` with @param debug_key for server-side debug logging
+/// @throws Exception if the debug_key contains invalid (e.g., uppercase) gRPC characters
+ProtoStruct debug_map(std::string debug_key);
+
+/// @brief Adds @param debug_key for server-side debug logging to @param map
+/// @throws Exception if the debug_key contains invalid (e.g., uppercase) gRPC characters
+void add_debug_entry(ProtoStruct& map, std::string debug_key);
+
+/// @brief Adds a random key to @param map for server-side debug logging
+void add_debug_entry(ProtoStruct& map);
+
+/// @brief Adds @param debug_key for server-side debug logging to @param map
+/// @throws Exception if the debug_key contains invalid (e.g., uppercase) gRPC characters
+/// @returns the new ProtoStruct
+ProtoStruct with_debug_entry(ProtoStruct&& map, std::string debug_key);
+
+/// @brief Adds a random key to @param map for server-side debug logging
+/// @returns the new ProtoStruct
+ProtoStruct with_debug_entry(ProtoStruct&& map);
+
 /// @brief Set the boost trivial logger's severity depending on args.
 /// @param argc The number of args.
 /// @param argv The commandline arguments to parse.

src/viam/sdk/components/arm.hpp

@@ -93,6 +93,11 @@ class Arm : public Component, public Stoppable {
     /// @param extra Any additional arguments to the method.
     virtual std::vector<double> get_joint_positions(const ProtoStruct& extra) = 0;
 
+    /// @brief Move each joint on the arm to the corresponding angle specified in @param positions
+    inline void move_to_joint_positions(const std::vector<double>& positions) {
+        return move_to_joint_positions(positions, {});
+    }
+
     /// @brief Move each joint on the arm to the corresponding angle specified in @param positions
     /// @param extra Any additional arguments to the method.
     virtual void move_to_joint_positions(const std::vector<double>& positions,

src/viam/sdk/components/private/motor_client.cpp

@@ -1,8 +1,6 @@
 #include <viam/sdk/components/private/motor_client.hpp>
 
-#include <algorithm>
 #include <memory>
-#include <stdexcept>
 #include <string>
 #include <utility>
 

src/viam/sdk/tests/mocks/mock_motion.cpp

@@ -1,9 +1,10 @@
-#include "viam/sdk/services/motion.hpp"
 #include <viam/sdk/tests/mocks/mock_motion.hpp>
 
 #include <chrono>
 
+#include <viam/sdk/common/private/utils.hpp>
 #include <viam/sdk/common/utils.hpp>
+#include <viam/sdk/services/motion.hpp>
 #include <viam/sdk/spatialmath/geometry.hpp>
 #include <viam/sdk/spatialmath/orientation_types.hpp>
 #include <viam/sdk/tests/test_utils.hpp>
@@ -65,7 +66,12 @@ std::string MockMotion::move_on_globe(
 pose_in_frame MockMotion::get_pose(const Name&,
                                    const std::string&,
                                    const std::vector<WorldState::transform>&,
-                                   const ProtoStruct&) {
+                                   const ProtoStruct& extra) {
+    auto key = extra.find(impl::debug_map_key);
+    if (key != extra.end()) {
+        ProtoValue value = key->second;
+        peek_debug_key = *value.get<std::string>();
+    }
     return current_location;
 }
 

src/viam/sdk/tests/mocks/mock_motion.hpp

@@ -91,6 +91,7 @@ class MockMotion : public sdk::Motion {
     std::string peek_destination_frame;
     double peek_heading;
     bool peek_stop_plan_called = false;
+    std::string peek_debug_key;
     std::vector<sdk::geo_geometry> peek_obstacles;
     std::vector<sdk::GeometryConfig> peek_map_obstacles;
     std::shared_ptr<constraints> peek_constraints;

src/viam/sdk/tests/test_motion.cpp

@@ -3,6 +3,7 @@
 #include <boost/test/included/unit_test.hpp>
 
 #include <viam/sdk/common/pose.hpp>
+#include <viam/sdk/common/utils.hpp>
 #include <viam/sdk/common/world_state.hpp>
 #include <viam/sdk/services/motion.hpp>
 #include <viam/sdk/spatialmath/geometry.hpp>
@@ -164,18 +165,20 @@ BOOST_AUTO_TEST_SUITE(test_motion_client_server)
 
 BOOST_AUTO_TEST_CASE(test_move_and_get_pose) {
     auto mock = std::make_shared<MockMotion>("mock_motion");
-    client_to_mock_pipeline<Motion>(mock, [](Motion& client) {
+    client_to_mock_pipeline<Motion>(mock, [&](Motion& client) {
         std::string destination_frame("destination");
         std::vector<WorldState::transform> transforms;
-        ProtoStruct extra = fake_map();
-        pose_in_frame pose = client.get_pose(fake_component_name(), destination_frame, {}, extra);
+        std::string debug_key = "debug-key";
+        pose_in_frame pose = client.get_pose(
+            fake_component_name(), destination_frame, {}, with_debug_entry(fake_map(), debug_key));
+        BOOST_CHECK_EQUAL(mock->peek_debug_key, debug_key);
         BOOST_CHECK_EQUAL(pose, init_fake_pose());
 
         auto ws = std::make_shared<WorldState>(mock_world_state());
         bool success = client.move(fake_pose(), fake_component_name(), ws, nullptr, fake_map());
         BOOST_TEST(success);
 
-        pose = client.get_pose(fake_component_name(), destination_frame, transforms, extra);
+        pose = client.get_pose(fake_component_name(), destination_frame, transforms, fake_map());
         BOOST_CHECK_EQUAL(pose, fake_pose());
     });
 }