Add Metrics API

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+**Features**:
+
+- Add Metrics API ([#985](https://github.com/getsentry/sentry-native/pull/985))
+
 ## 0.7.5
 
 **Features**:

examples/example.c

@@ -386,6 +386,18 @@ main(int argc, char **argv)
 
         sentry_capture_user_feedback(user_feedback);
     }
+    if (has_arg(argc, argv, "metrics-emit-increment")) {
+        sentry_metrics_emit_increment("test-inc", 5.0, "second");
+    }
+    if (has_arg(argc, argv, "metrics-emit-distribution")) {
+        sentry_metrics_emit_distribution("test-dist", 5.0, "second");
+    }
+    if (has_arg(argc, argv, "metrics-emit-gauge")) {
+        sentry_metrics_emit_gauge("test-gauge", 5.0, "second");
+    }
+    if (has_arg(argc, argv, "metrics-emit-set")) {
+        sentry_metrics_emit_set("test-set", 5.0, "second");
+    }
 
     if (has_arg(argc, argv, "capture-transaction")) {
         sentry_transaction_context_t *tx_ctx

include/sentry.h

@@ -2058,6 +2058,98 @@ SENTRY_EXPERIMENTAL_API const char *sentry_sdk_name(void);
  */
 SENTRY_EXPERIMENTAL_API const char *sentry_sdk_user_agent(void);
 
+/**
+ * Emits a counter metric.
+ *
+ * Counters are one of the more basic types of metrics and can be
+ * used to count certain event occurrences.
+ *
+ * Counter value can only be incremented.
+ *
+ * Metrics can be tagged by key-value pairs
+ * that are set as a variadic parameter.
+ * For any non-empty tag sequence a terminating `NULL` has to be provided.
+ *
+ * See https://develop.sentry.dev/delightful-developer-metrics/
+ */
+SENTRY_EXPERIMENTAL_API void sentry_metrics_emit_increment_(
+    const char *key, double value, const char *unit, ...);
+
+/**
+ * Convenience macro for `sentry_metrics_emit_increment_`.
+ */
+#define sentry_metrics_emit_increment(key, value, unit, ...)                   \
+    sentry_metrics_emit_increment_(key, value, unit, ##__VA_ARGS__, NULL)
+
+/**
+ * Emits a distribution metric.
+ *
+ * Distributions track a list of values over time on which
+ * aggregations like `p90`, `max`, `min`, `avg` can be performed.
+ *
+ * Metrics can be tagged by key-value pairs
+ * that are set as a variadic parameter.
+ * For any non-empty tag sequence a terminating `NULL` has to be provided.
+ *
+ * See https://develop.sentry.dev/delightful-developer-metrics/
+ */
+SENTRY_EXPERIMENTAL_API void sentry_metrics_emit_distribution_(
+    const char *key, double value, const char *unit, ...);
+
+/**
+ * Convenience macro for `sentry_metrics_emit_distribution_`.
+ */
+#define sentry_metrics_emit_distribution(key, value, unit, ...)                \
+    sentry_metrics_emit_distribution_(key, value, unit, ##__VA_ARGS__, NULL)
+
+/**
+ * Emits a gauge metric.
+ *
+ * Gauges track a value that can go up and down on which
+ * aggregations like `max`, `min`, `avg`, `sum` and `count` can be performed.
+ *
+ * Gauges can be represented in a more space-efficient way than distributions,
+ * but they can't be used to get percentiles.
+ *
+ * Metrics can be tagged by key-value pairs
+ * that are set as a variadic parameter.
+ * For any non-empty tag sequence a terminating `NULL` has to be provided.
+ *
+ * See https://develop.sentry.dev/delightful-developer-metrics/
+ */
+SENTRY_EXPERIMENTAL_API void sentry_metrics_emit_gauge_(
+    const char *key, double value, const char *unit, ...);
+
+/**
+ * Convenience macro for `sentry_metrics_emit_gauge_`.
+ */
+#define sentry_metrics_emit_gauge(key, value, unit, ...)                       \
+    sentry_metrics_emit_gauge_(key, value, unit, ##__VA_ARGS__, NULL)
+
+/**
+ * Emits a set metric.
+ *
+ * Sets are useful for looking at unique occurrences and counting
+ * the unique elements that were added.
+ *
+ * Sets track a set of values on which aggregations such as `count_unique`
+ * can be performed.
+ *
+ * Metrics can be tagged by key-value pairs
+ * that are set as a variadic parameter.
+ * For any non-empty tag sequence a terminating `NULL` has to be provided.
+ *
+ * See https://develop.sentry.dev/delightful-developer-metrics/
+ */
+SENTRY_EXPERIMENTAL_API void sentry_metrics_emit_set_(
+    const char *key, int32_t value, const char *unit, ...);
+
+/**
+ * Convenience macro for `sentry_metrics_emit_set_`.
+ */
+#define sentry_metrics_emit_set(key, value, unit, ...)                         \
+    sentry_metrics_emit_set_(key, value, unit, ##__VA_ARGS__, NULL)
+
 #ifdef __cplusplus
 }
 #endif

src/CMakeLists.txt

@@ -15,6 +15,8 @@ sentry_target_sources_cwd(sentry
 	sentry_json.h
 	sentry_logger.c
 	sentry_logger.h
+	sentry_metrics.c
+	sentry_metrics.h
 	sentry_options.c
 	sentry_options.h
 	sentry_os.c
@@ -154,3 +156,8 @@ if(SENTRY_INTEGRATION_QT)
 		integrations/sentry_integration_qt.h
 	)
 endif()
+
+# integration tests
+if(SENTRY_INTEGRATIONTEST)
+	target_compile_definitions(sentry PRIVATE SENTRY_INTEGRATIONTEST)
+endif()

src/sentry_core.c

@@ -7,6 +7,7 @@
 #include "sentry_core.h"
 #include "sentry_database.h"
 #include "sentry_envelope.h"
+#include "sentry_metrics.h"
 #include "sentry_options.h"
 #include "sentry_path.h"
 #include "sentry_random.h"
@@ -257,6 +258,7 @@ sentry_close(void)
     sentry__mutex_unlock(&g_options_lock);
 
     sentry__scope_cleanup();
+    sentry__metrics_aggregator_cleanup();
     sentry_clear_modulecache();
 
     return (int)dumped_envelopes;
@@ -570,6 +572,24 @@ sentry__prepare_user_feedback(sentry_value_t user_feedback)
     return NULL;
 }
 
+sentry_envelope_t *
+sentry__prepare_metrics(const char *encoded_metrics)
+{
+    sentry_envelope_t *envelope = NULL;
+
+    envelope = sentry__envelope_new();
+    if (!envelope || !sentry__envelope_add_metrics(envelope, encoded_metrics)) {
+        goto fail;
+    }
+
+    return envelope;
+
+fail:
+    SENTRY_WARN("dropping metrics");
+    sentry_envelope_free(envelope);
+    return NULL;
+}
+
 void
 sentry_handle_exception(const sentry_ucontext_t *uctx)
 {
@@ -1171,3 +1191,16 @@ sentry_clear_crashed_last_run(void)
     sentry__options_unlock();
     return success ? 0 : 1;
 }
+
+void
+sentry__metrics_flush(const char *encoded_metrics)
+{
+    sentry_envelope_t *envelope = NULL;
+
+    SENTRY_WITH_OPTIONS (options) {
+        envelope = sentry__prepare_metrics(encoded_metrics);
+        if (envelope) {
+            sentry__capture_envelope(options->transport, envelope);
+        }
+    }
+}

src/sentry_core.h

@@ -95,6 +95,11 @@ sentry_uuid_t sentry__new_event_id(void);
 sentry_value_t sentry__ensure_event_id(
     sentry_value_t event, sentry_uuid_t *uuid_out);
 
+/**
+ * Sends statsd-encoded metrics to Sentry
+ */
+void sentry__metrics_flush(const char *encoded_metrics);
+
 /**
  * This will return an owned reference to the global options.
  */

src/sentry_envelope.c

@@ -325,6 +325,16 @@ sentry__envelope_add_user_feedback(
     return item;
 }
 
+sentry_envelope_item_t *
+sentry__envelope_add_metrics(sentry_envelope_t *envelope, const char *metrics)
+{
+    if (!envelope || !metrics) {
+        return NULL;
+    }
+    return sentry__envelope_add_from_buffer(
+        envelope, metrics, strlen(metrics), "statsd");
+}
+
 sentry_envelope_item_t *
 sentry__envelope_add_session(
     sentry_envelope_t *envelope, const sentry_session_t *session)

src/sentry_envelope.h

@@ -48,6 +48,12 @@ sentry_envelope_item_t *sentry__envelope_add_transaction(
 sentry_envelope_item_t *sentry__envelope_add_user_feedback(
     sentry_envelope_t *envelope, sentry_value_t user_feedback);
 
+/**
+ * Add a encoded metrics data to this envelope.
+ */
+sentry_envelope_item_t *sentry__envelope_add_metrics(
+    sentry_envelope_t *envelope, const char *metrics);
+
 /**
  * Add a session to this envelope.
  */