document the public API

Author: dmehala

BUILD.bazel

@@ -3,6 +3,7 @@ cc_library(
     srcs = [
       "src/datadog/telemetry/configuration.cpp",
       "src/datadog/telemetry/metrics.cpp",
+      "src/datadog/telemetry/log.h",
       "src/datadog/telemetry/telemetry.cpp",
       "src/datadog/base64.cpp",
       "src/datadog/cerr_logger.cpp",

include/datadog/telemetry/telemetry.h

@@ -16,21 +16,39 @@ class TracerTelemetry;
 
 namespace telemetry {
 
-class Telemetry {
+/// The telemetry class is responsible for handling internal telemetry data to
+/// track Datadog product usage. It _can_ collect and report logs and metrics.
+///
+/// IMPORTANT: This is intended for use only by Datadog Engineers.
+class Telemetry final {
+  /// Configuration object containing the validated settings for telemetry
   FinalizedConfiguration config_;
+  /// Shared pointer to the user logger instance.
   std::shared_ptr<tracing::Logger> logger_;
-
+  /// TODO(@dmehala): Legacy dependency.
   std::shared_ptr<tracing::DatadogAgent> datadog_agent_;
   std::shared_ptr<tracing::TracerTelemetry> tracer_telemetry_;
 
  public:
+  /// Constructor for the Telemetry class
+  ///
+  /// @param configuration The finalized configuration settings.
+  /// @param logger User logger instance.
+  /// @param metrics A vector user metrics to report.
   Telemetry(FinalizedConfiguration configuration,
             std::shared_ptr<tracing::Logger> logger,
             std::vector<std::shared_ptr<Metric>> metrics);
 
   ~Telemetry() = default;
 
+  /// Capture and report internal error message to Datadog.
+  ///
+  /// @param message The error message.
   void log_error(std::string message);
+
+  /// capture and report internal warning message to Datadog.
+  ///
+  /// @param message The warning message to log.
   void log_warning(std::string message);
 };
 

src/datadog/telemetry/log.h

@@ -0,0 +1,12 @@
+#include <string>
+
+namespace datadog::telemetry {
+
+enum class LogLevel : char { ERROR, WARNING };
+
+struct LogMessage final {
+  std::string message;
+  LogLevel level;
+};
+
+}  // namespace datadog::telemetry