solarwinds_apm 5.1.6 → 5.1.8

data/ext/oboe_metal/src/oboe_api.h

@@ -1,13 +1,8 @@
 /**
- * @file oboe_api.hpp - C++ liboboe wrapper primarily for generating SWIG interfaces
- * and used by Ruby c++ extension for profiling
- *
- * TODO:  This doc is outdated
- * This API should follow https://github.com/tracelytics/tracelons/wiki/Instrumentation-API
+ * C++ liboboe wrapper primarily for generating SWIG interfaces
  */
-
-#ifndef OBOE_API_HPP
-#define OBOE_API_HPP
+#ifndef OBOE_API_H
+#define OBOE_API_H
 
 #include <unistd.h>
 #include <cstdlib>
@@ -39,28 +34,47 @@ typedef struct frame_data {
 class Metadata : private oboe_metadata_t {
     friend class Reporter;
     friend class Context;
-
-   public:
+public:
     Metadata(const oboe_metadata_t *md);
     ~Metadata();
-
-    // these new objects are managed by SWIG %newobject
     /**
-     * Create a new event object using this Metadata's context.
-     *
-     * NOTE: The returned object must be "delete"d.
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @return Event*
      */
     Event *createEvent();
-
+    /**
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @return Metadata*
+     */
     Metadata *copy();
     bool isValid();
     bool isSampled();
-
+    /**
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @param sampled bool default=true
+     * @return Metadata*
+     */
     static Metadata *makeRandom(bool sampled = true);
-    static Metadata *fromString(std::string s);
-
+    /**
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @param s std::string
+     * @return Metadata*
+     */
+    static Metadata *fromString(const std::string& s);
+    /**
+     * Return this pointer
+     * No Object ownership changed via SWIG
+     * @return oboe_metadata_t*
+     */
     oboe_metadata_t *metadata();
-
 #ifdef SWIGJAVA
     std::string toStr();
 #else
@@ -169,10 +183,12 @@ class Context {
         long header_timestamp = 0);
 
     /**
-     * Get a pointer to the current context (from thread-local storage)
+     * Return a pointer to the current context
+     * Return a pointer in C++ heap
+     * No object ownership changed via SWIG
+     * @return oboe_metadata_t*
      */
     static oboe_metadata_t *get();
-
     /**
      * Get the current context as a printable string.
      */
@@ -189,10 +205,16 @@ class Context {
 
     /**
      * Set the current context from a string.
+     * @param s const std::string&
      */
-    static void fromString(std::string s);
+    static void fromString(const std::string& s);
 
-    // this new object is managed by SWIG %newobject
+    /**
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @return Metadata*
+     */
     static Metadata *copy();
 
     static void setSampledFlag();
@@ -206,7 +228,7 @@ class Context {
     /**
      * Perform validation and replacement of invalid characters on the given service key.
      */
-    static std::string validateTransformServiceName(std::string service_key);
+    static std::string validateTransformServiceName(const std::string& service_key);
 
     /**
      * Shut down the Oboe library.
@@ -235,31 +257,45 @@ class Context {
      */
     static bool isLambda();
 
-    // these new objects are managed by SWIG %newobject
     /**
-     * Create a new event object using the thread's context.
-     *
-     * NOTE: The returned object must be "delete"d.
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @return Event*
      */
     static Event *createEvent();
+    /**
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @return Event*
+     */
     static Event *startTrace();
-
     /**
      * Create entry event with user-defined metadata and timestamp
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
      * @param md const oboe_metadata_t *
      * @param timestamp int64_t
-     * @param parent_md const oboe_metadata_t *
+     * @param parent_md const oboe_metadata_t * default = nullptr
      * @return Event*
      */
     static Event* createEntry(const oboe_metadata_t *md, int64_t timestamp, const oboe_metadata_t *parent_md = nullptr);
     /**
      * Create an continuous event with user-defined timestamp
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
      * @param timestamp int64_t
      * @return Event*
      */
     static Event* createEvent(int64_t timestamp);
     /**
      * Create exit event with user-defined timestamp
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
      * @param timestamp int64_t
      * @return Event*
      */
@@ -280,7 +316,7 @@ class Event : private oboe_event_t {
 
     // called e.g. from Python e.addInfo("Key", None) & Ruby e.addInfo("Key", nil)
     bool addInfo(char *key, void *val);
-    bool addInfo(char *key, const std::string &val);
+    bool addInfo(char *key, const std::string& val);
     bool addInfo(char *key, long val);
     bool addInfo(char *key, double val);
     bool addInfo(char *key, bool val);
@@ -296,9 +332,10 @@ class Event : private oboe_event_t {
     bool addHostname();
 
     /**
-     * Get a new copy of this metadata.
-     *
-     * NOTE: The returned object must be "delete"d.
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @return Metadata*
      */
     Metadata *getMetadata();
     std::string metadataString();
@@ -325,16 +362,15 @@ class Event : private oboe_event_t {
 
     bool addSpanRef(const oboe_metadata_t *md);
     bool addProfileEdge(std::string id);
-
     /**
-      * Create a new event object using the given metadata context.
-      *
-      * NOTE: The metadata context must be unique to the new trace.
-      *
-      * NOTE: The returned object must be "delete"d.
-      *
-      * @param md The metadata object to use when creating the new event.
-      */
+     * Create a new event object using the given metadata context.
+     * NOTE: The metadata context must be unique to the new trace.
+     * Return an `new` C++ object
+     * Object ownership changed via SWIG
+     * SWIG managed the de-allocation using %newobject keyword
+     * @param md const oboe_metadata_t*
+     * @return Event*
+     */
     static Event *startTrace(const oboe_metadata_t *md);
 };
 
@@ -362,6 +398,9 @@ class MetricTags {
      * Please note that SWIG doesn't have the definition of
      * oboe_metric_tag_t.
      * Ruby and Python should not call this method
+     *
+     * Return tags as pointer.
+     * No object ownership changed via SWIG
      * @return oboe_metric_tag_t*
      */
     oboe_metric_tag_t *get() const;
@@ -459,4 +498,4 @@ class Config {
     static std::string getVersionString();
 };
 
-#endif  // OBOE_API_HPP
+#endif  // OBOE_API_H

data/ext/oboe_metal/src/oboe_debug.h

@@ -1,11 +1,3 @@
-/**
- * @file: debug.h - Diagnostic logging functions for liboboe.
- *
- * Most of the diagnostics logging interface is defined in oboe.h but we
- * separate some of it out here for special handling when generating
- * SWIG interfaces.
- */
-
 #ifndef _OBOE_DEBUG_H
 #define _OBOE_DEBUG_H
 
@@ -13,6 +5,8 @@
 extern "C" {
 #endif
 
+#include <stdbool.h>
+
 /**
  * Defined diagnostic log detail levels.
  */
@@ -44,14 +38,287 @@ enum OBOE_DEBUG_MODULE {
     OBOE_MODULE_PHP,                /*!< PHP interpreter */
     OBOE_MODULE_DOTNET,             /*!< dotnet wrapper */
     OBOE_MODULE_RUBY,               /*!< ruby c++ extension */
+    OBOE_MODULE_HOST_ID_SERVICE,
+    OBOE_MODULE_AWS_RESOURCE_PROVIDER,
+    OBOE_MODULE_AZURE_RESOURCE_PROVIDER,
 };
 
+/** Compile time debug logging detail level - cannot log more detailed than this. */
+#define OBOE_DEBUG_LEVEL OBOE_DEBUG_HIGH
+
 /**
  * Initial debug log detail level.
  *
  */
 #define LOGLEVEL_DEFAULT OBOE_DEBUG_INFO
 
+/** Limit for number of messages at specified level before demoting to debug MEDIUM. */
+#define MAX_DEBUG_MSG_COUNT 1
+
+void oboe_debug_log_init(FILE* output);
+
+/**
+ * Low-level diagnostics logging function.
+ *
+ * This is normally used only by the OBOE_DEBUG_LOG_* function macros and not used directly.
+ *
+ * This function may be adapted to format and route diagnostic log messages as desired.
+ *
+ * @param module One of the numeric module identifiers defined in debug.h - used to control logging detail by module.
+ * @param level Diagnostic detail level of this message - used to control logging volume by detail level.
+ * @param source_name Name of the source file, if available, or another useful name, or NULL.
+ * @param source_lineno Number of the line in the source file where message is logged from, if available, or zero.
+ * @param format A C language printf format specification string.
+ * @param args A variable argument list in VA_ARG format containing arguments for each argument specifier in the format.
+ */
+void oboe_debug_logger(int module, int level, const char *source_name, int source_lineno, const char *format, ...);
+
+
+/**
+ * Prototype for a logger call-back function.
+ *
+ * A logging function of this form can be added to the logger chain using
+ * oboe_debug_log_add().
+ *
+ * @param context The context pointer that was registered in the call to
+ *          oboe_debug_log_add().  Use it to pass the pointer-to-self for
+ *          objects (ie. "this" in C++) or just a structure in C,  May be
+ *          NULL.
+ * @param module The module identifier as passed to oboe_debug_logger().
+ * @param level The diagnostic detail level as passed to oboe_debug_logger().
+ * @param source_name Name of the source file as passed to oboe_debug_logger().
+ * @param source_lineno Number of the line in the source file where message is
+ *          logged from as passed to oboe_debug_logger().
+ * @param msg The formatted message produced from the format string and its
+ *          arguments as passed to oboe_debug_logger().
+ */
+typedef void (*OboeDebugLoggerFcn)(void *context, int module, int level, const char *source_name, int source_lineno, const char *msg);
+
+/**
+ * Get a printable name for a diagnostics logging level.
+ */
+const char *oboe_debug_log_level_name(int level);
+
+/**
+ * Get a printable name for a diagnostics logging module identifier.
+ */
+const char *oboe_debug_module_name(int module);
+
+/**
+ * Get the maximum logging detail level for a module or for all modules.
+ *
+ * This level applies to the stderr logger only.  Added loggers get all messages
+ * below their registed detail level and need to do their own module-specific
+ * filtering.
+ *
+ * @param module One of the OBOE_MODULE_* values.  Use OBOE_MODULE_ALL (-1) to
+ *          get the overall maximum detail level.
+ * @return Maximum detail level value for module (or overall) where zero is the
+ *          lowest and higher values generate more detailed log messages.
+ */
+int oboe_debug_log_level_get(int module);
+
+/**
+ * Set the maximum logging detail level for a module or for all modules.
+ *
+ * This level applies to the stderr logger only.  Added loggers get all messages
+ * below their registered detail level and need to do their own module-specific
+ * filtering.
+ *
+ * @param module One of the OBOE_MODULE_* values.  Use OBOE_MODULE_ALL to set
+ *          the overall maximum detail level.
+ * @param newLevel Maximum detail level value where zero is the lowest and higher
+ *          values generate more detailed log messages.
+ */
+void oboe_debug_log_level_set(FILE* output, int module, int newLevel);
+
+/**
+ * Set the output stream for the default logger.
+ *
+ * @param newStream A valid, open FILE* stream or NULL to disable the default logger.
+ * @return Zero on success; otherwise an error code (normally from errno).
+ */
+int oboe_debug_log_to_stream(FILE *newStream);
+
+/**
+ * If we're logging to a stream, flush it.
+ *
+ * @return Zero on success; otherwise an error code (normally from errno).
+ */
+int oboe_debug_log_flush();
+
+/**
+ * Set the default logger to write to the specified file.
+ *
+ * A NULL or empty path name will disable the default logger.
+ *
+ * If the file exists then it will be opened in append mode.
+ *
+ * @param pathname The path name of the
+ * @return Zero on success; otherwise an error code (normally from errno).
+ */
+int oboe_debug_log_to_file(const char *pathname);
+
+/**
+ * Add a logger that takes messages up to a given logging detail level.
+ *
+ * This adds the logger to a chain in order of the logging level.  Log messages
+ * are passed to each logger down the chain until the remaining loggers only
+ * accept messages of a lower detail level.
+ *
+ * @return Zero on success, one if re-registered with the new logging level, and
+ *          otherwise a negative value to indicate an error.
+ */
+int oboe_debug_log_add(OboeDebugLoggerFcn newLogger, void *context, int logLevel);
+
+/**
+ * Remove a logger.
+ *
+ * Remove the logger from the message handling chain.
+ *
+ * @return Zero on success, one if it was not found, and otherwise a negative
+ *          value to indicate an error.
+ */
+int oboe_debug_log_remove(OboeDebugLoggerFcn oldLogger, void *context);
+
+/*
+ * Log the application's Oboe configuration.
+ *
+ * We use this to get a reasonable standard format between apps.
+ *
+ * @param module An OBOE_MODULE_* module identifier.  Use zero for undefined.
+ * @param app_name Either NULL or a pointer to a string containing a name for
+ *          the application - will prefix the log entry.  Useful when multiple
+ *          apps log to the same destination.
+ * @param trace_mode A string identifying the configured tracing mode, one of:
+ *          "enabled", "disabled", "unset", or "undef" (for invalid values)
+ *          Use the oboe_tracing_mode_to_string() function to convert from
+ *          numeric values.
+ * @param sample_rate The configured sampling rate: -1 for unset or a
+ *          integer fraction of 1000000.
+ * @param reporter_type String identifying the type of reporter configured:
+ *          One of 'udp' (the default), 'ssl', or 'file'.
+ * @param reporter_args The string of comma-separated key=value settings
+ *          used to initialize the reporter.
+ * @param extra: Either NULL or a pointer to a string to be appended to
+ *          the log message and designed to include a few other
+ *          configuration parameters of interest.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_INFO
+# define OBOE_DEBUG_LOG_CONFIG_EX(module, app_name, trace_mode, sample_rate, reporter_type, reporter_args, extra) \
+  {                                                                                 \
+    oboe_debug_logger(module, OBOE_DEBUG_INFO, __FILE__, __LINE__,                  \
+        "%s Oboe config: tracing=%s, sampling=%d, reporter=('%s', '%s') %s",        \
+        (app_name == NULL ? "" : app_name),                                         \
+        trace_mode,                                                                 \
+        sample_rate,                                                                \
+        (reporter_type == NULL ? "?" : reporter_type),                              \
+        (reporter_args == NULL ? "?" : reporter_args),                              \
+        (extra == NULL ? "" : extra));                                              \
+  }
+#else
+# define OBOE_DEBUG_LOG_CONFIG_EX(module, app_name, trace_mode, sample_rate, reporter_type, reporter_args, extra) {}
+#endif
+
+/**
+ * Log a fatal error.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_FATAL
+# define OBOE_DEBUG_LOG_FATAL_EX(module, ...)                   \
+  {                                                          \
+    oboe_debug_logger(module, OBOE_DEBUG_FATAL, __FILE__, __LINE__, __VA_ARGS__); \
+  }
+#else
+# define OBOE_DEBUG_LOG_FATAL_EX(module, ...) {}
+#endif
+
+/**
+ * Log a recoverable error.
+ *
+ * Each message is limited in the number of times that it will be reported at the
+ * ERROR level after which it will be logged at the debug MEDIUM level.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_ERROR
+# define OBOE_DEBUG_LOG_ERROR_EX(module, ...)                   \
+  {                                                          \
+    static int usage_counter = 0;                            \
+    int loglev = (++usage_counter <= MAX_DEBUG_MSG_COUNT ? OBOE_DEBUG_ERROR : OBOE_DEBUG_MEDIUM); \
+    oboe_debug_logger(module, loglev, __FILE__, __LINE__, __VA_ARGS__); \
+  }
+#else
+# define OBOE_DEBUG_LOG_ERROR_EX(module, ...) {}
+#endif
+
+/**
+ * Log a warning.
+ *
+ * Each message is limited in the number of times that it will be reported at the
+ * WARNING level after which it will be logged at the debug MEDIUM level.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_WARNING
+# define OBOE_DEBUG_LOG_WARNING_EX(module, ...)                 \
+  {                                                          \
+    static int usage_counter = 0;                            \
+    int loglev = (++usage_counter <= MAX_DEBUG_MSG_COUNT ? OBOE_DEBUG_WARNING : OBOE_DEBUG_MEDIUM); \
+    oboe_debug_logger(module, loglev, __FILE__, __LINE__, __VA_ARGS__); \
+  }
+#else
+# define OBOE_DEBUG_LOG_WARNING_EX(module, ...) {}
+#endif
+
+/**
+ * Log an informative message.
+ *
+ * Each message is limited in the number of times that it will be reported at the
+ * INFO level after which it will be logged at the debug MEDIUM level.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_INFO
+# define OBOE_DEBUG_LOG_INFO_EX(module, ...)                    \
+  {                                                                     \
+    static int usage_counter = 0;                            \
+    int loglev = (++usage_counter <= MAX_DEBUG_MSG_COUNT ? OBOE_DEBUG_INFO : OBOE_DEBUG_MEDIUM); \
+    oboe_debug_logger(module, loglev, __FILE__, __LINE__, __VA_ARGS__); \
+  }
+#else
+# define OBOE_DEBUG_LOG_INFO_EX(module, ...) {}
+#endif
+
+/**
+ * Log a low-detail diagnostic message.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_LOW
+# define OBOE_DEBUG_LOG_LOW_EX(module, ...)                    \
+  {                                                                     \
+    oboe_debug_logger(module, OBOE_DEBUG_LOW, __FILE__, __LINE__, __VA_ARGS__); \
+  }
+#else
+# define OBOE_DEBUG_LOG_LOW_EX(module, ...) {}
+#endif
+
+/**
+ * Log a medium-detail diagnostic message.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_MEDIUM
+# define OBOE_DEBUG_LOG_MEDIUM_EX(module, ...)                    \
+  {                                                                     \
+    oboe_debug_logger(module, OBOE_DEBUG_MEDIUM, __FILE__, __LINE__, __VA_ARGS__); \
+  }
+#else
+# define OBOE_DEBUG_LOG_MEDIUM_EX(module, ...) {}
+#endif
+
+/**
+ * Log a high-detail diagnostic message.
+ */
+#if OBOE_DEBUG_LEVEL >= OBOE_DEBUG_HIGH
+# define OBOE_DEBUG_LOG_HIGH_EX(module, ...)                    \
+  {                                                                     \
+    oboe_debug_logger(module, OBOE_DEBUG_HIGH, __FILE__, __LINE__, __VA_ARGS__); \
+  }
+#else
+# define OBOE_DEBUG_LOG_HIGH_EX(module, ...) {}
+#endif
+
 #ifdef __cplusplus
 } // extern "C"
 #endif