feat: metrics #1498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

jpnurmi wants to merge 25 commits into master from jpnurmi/feat/metrics

CHANGELOG.md

-Original file line number
+Diff line change
@@ -1,5 +1,11 @@
     # Changelog
+    ## Unreleased
+    **Features**:
+    - Add support for metrics. It is currently experimental, and one can enable it by setting `sentry_options_set_enable_metrics`. When enabled, you can record a metric using `sentry_metrics_count()`, `sentry_metrics_gauge()`, or `sentry_metrics_distribution()`. Metrics can be filtered by setting the `before_send_metric` hook. ([#1498](https://github.com/getsentry/sentry-native/pull/1498))
     ## 0.12.5
     **Features**:
@@ Expand Down @@

examples/example.c

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -183,6 +183,25 @@ discarding_before_send_log_callback(sentry_value_t log, void *user_data)
  
        return log;

    }

    static sentry_value_t

    before_send_metric_callback(sentry_value_t metric, void *user_data)

    {

        (void)user_data;

        sentry_value_t attribute

            = sentry_value_new_attribute(sentry_value_new_string("little"), NULL);

        sentry_value_set_by_key(sentry_value_get_by_key(metric, "attributes"),

            "coffeepot.size", attribute);

        return metric;

    }

    static sentry_value_t

    discarding_before_send_metric_callback(sentry_value_t metric, void *user_data)

    {

        (void)user_data;

        sentry_value_decref(metric);

        return sentry_value_new_null();

    }

    // Test logger that outputs in a format the integration tests can parse

    static void

    test_logger_callback(

    @@ -317,8 +336,8 @@ create_debug_crumb(const char *message)
  
    }

    #define NUM_THREADS 50

    #define NUM_LOGS 100 // how many log calls each thread makes

    #define LOG_SLEEP_MS 1 // time (in ms) between log calls

    #define NUM_TELEMETRY 100 // how many telemetry calls each thread makes

    #define TELEMETRY_SLEEP_MS 1 // time (in ms) between telemetry calls

    #if defined(SENTRY_PLATFORM_WINDOWS)

    #    define sleep_ms(MILLISECONDS) Sleep(MILLISECONDS)

    @@ -327,29 +346,80 @@ create_debug_crumb(const char *message)
  
    #endif

    #ifdef SENTRY_PLATFORM_WINDOWS

    typedef DWORD(WINAPI *thread_func_t)(LPVOID);

    DWORD WINAPI

    log_thread_func(LPVOID lpParam)

    {

        (void)lpParam;

        for (int i = 0; i < NUM_LOGS; i++) {

        for (int i = 0; i < NUM_TELEMETRY; i++) {

            sentry_log_debug(

                "thread log %d on thread %lu", i, get_current_thread_id());

            sleep_ms(LOG_SLEEP_MS);

            sleep_ms(TELEMETRY_SLEEP_MS);

        }

        return 0;

    }

    DWORD WINAPI

    metric_thread_func(LPVOID lpParam)

    {

        (void)lpParam;

        for (int i = 0; i < NUM_TELEMETRY; i++) {

            sentry_metrics_count("thread.counter", 1, sentry_value_new_null());

            sleep_ms(TELEMETRY_SLEEP_MS);

        }

        return 0;

    }

    static void

    run_threads(thread_func_t func)

    {

        HANDLE threads[NUM_THREADS];

        for (int t = 0; t < NUM_THREADS; t++) {

            threads[t] = CreateThread(NULL, 0, func, NULL, 0, NULL);

        }

        WaitForMultipleObjects(NUM_THREADS, threads, TRUE, INFINITE);

        for (int t = 0; t < NUM_THREADS; t++) {

            CloseHandle(threads[t]);

        }

    }

    #else

    typedef void *(*thread_func_t)(void *);

    void *

    log_thread_func(void *arg)

    {

        (void)arg;

        for (int i = 0; i < NUM_LOGS; i++) {

        for (int i = 0; i < NUM_TELEMETRY; i++) {

            sentry_log_debug(

                "thread log %d on thread %llu", i, get_current_thread_id());

            sleep_ms(LOG_SLEEP_MS);

            sleep_ms(TELEMETRY_SLEEP_MS);

        }

        return NULL;

    }

    void *

    metric_thread_func(void *arg)

    {

        (void)arg;

        for (int i = 0; i < NUM_TELEMETRY; i++) {

            sentry_metrics_count("thread.counter", 1, sentry_value_new_null());

            sleep_ms(TELEMETRY_SLEEP_MS);

        }

        return NULL;

    }

    static void

    run_threads(thread_func_t func)

    {

        pthread_t threads[NUM_THREADS];

        for (int t = 0; t < NUM_THREADS; t++) {

            pthread_create(&threads[t], NULL, func, NULL);

        }

        for (int t = 0; t < NUM_THREADS; t++) {

            pthread_join(threads[t], NULL);

        }

    }

    #endif

    int

    @@ -504,6 +574,20 @@ main(int argc, char **argv)
  
            sentry_options_set_logs_with_attributes(options, true);

        }

        if (has_arg(argc, argv, "enable-metrics")) {

            sentry_options_set_enable_metrics(options, true);

        }

        if (has_arg(argc, argv, "before-send-metric")) {

            sentry_options_set_before_send_metric(

                options, before_send_metric_callback, NULL);

        }

        if (has_arg(argc, argv, "discarding-before-send-metric")) {

            sentry_options_set_before_send_metric(

                options, discarding_before_send_metric_callback, NULL);

        }

        if (0 != sentry_init(options)) {

            return EXIT_FAILURE;

        }

    @@ -580,28 +664,39 @@ main(int argc, char **argv)
  
                sentry_log_debug("post-sleep log");

            }

            if (has_arg(argc, argv, "logs-threads")) {

                // Spawn multiple threads to test concurrent logging

    #ifdef SENTRY_PLATFORM_WINDOWS

                HANDLE threads[NUM_THREADS];

                for (int t = 0; t < NUM_THREADS; t++) {

                    threads[t]

                        = CreateThread(NULL, 0, log_thread_func, NULL, 0, NULL);

                }

                WaitForMultipleObjects(NUM_THREADS, threads, TRUE, INFINITE);

                run_threads(log_thread_func);

            }

        }

                for (int t = 0; t < NUM_THREADS; t++) {

                    CloseHandle(threads[t]);

                }

    #else

                pthread_t threads[NUM_THREADS];

                for (int t = 0; t < NUM_THREADS; t++) {

                    pthread_create(&threads[t], NULL, log_thread_func, NULL);

                }

                for (int t = 0; t < NUM_THREADS; t++) {

                    pthread_join(threads[t], NULL);

        if (sentry_options_get_enable_metrics(options)) {

            if (has_arg(argc, argv, "capture-metric")) {

                sentry_metrics_count("test.counter", 1, sentry_value_new_null());

            }

            if (has_arg(argc, argv, "capture-metric-all-types")) {

                sentry_metrics_count("test.counter", 1, sentry_value_new_null());

                sentry_metrics_gauge("test.gauge", 42.5, SENTRY_UNIT_PERCENT,

                    sentry_value_new_null());

                sentry_metrics_distribution("test.distribution", 123.456,

                    SENTRY_UNIT_MILLISECOND, sentry_value_new_null());

            }

            if (has_arg(argc, argv, "metric-with-attributes")) {

                sentry_value_t attributes = sentry_value_new_object();

                sentry_value_t attr = sentry_value_new_attribute(

                    sentry_value_new_string("my_value"), NULL);

                sentry_value_set_by_key(attributes, "my.custom.attribute", attr);

                sentry_metrics_count("test.counter.with.attributes", 1, attributes);

            }

            if (has_arg(argc, argv, "metrics-timer")) {

                for (int i = 0; i < 10; i++) {

                    sentry_metrics_count(

                        "batch.counter", 1, sentry_value_new_null());

                }

    #endif

                sleep_s(6);

                sentry_metrics_count(

                    "post.sleep.counter", 1, sentry_value_new_null());

            }

            if (has_arg(argc, argv, "metrics-threads")) {

                run_threads(metric_thread_func);

            }

        }

    @@ -881,6 +976,10 @@ main(int argc, char **argv)
  
                if (has_arg(argc, argv, "logs-scoped-transaction")) {

                    sentry_log_debug("logging during scoped transaction event");

                }

                if (has_arg(argc, argv, "metrics-scoped-transaction")) {

                    sentry_metrics_count(

                        "scoped.transaction.metric", 1, sentry_value_new_null());

                }

            }

            sentry_transaction_finish(tx);

include/sentry.h

-Original file line number
+Diff line change
@@ Expand Up @@
         const char *username, size_t username_len, const char *email,
         size_t email_len, const char *ip_address, size_t ip_address_len);
+    /**
+     * Measurement units for telemetry.
+     *
+     * These constants represent the standardized units supported by Sentry.
+     * Custom units can also be passed as arbitrary strings.
+     *
+     * See: https://develop.sentry.dev/sdk/telemetry/attributes/#units
+     */
+    /* Duration units */
+    #define SENTRY_UNIT_NANOSECOND "nanosecond"
+    #define SENTRY_UNIT_MICROSECOND "microsecond"
+    #define SENTRY_UNIT_MILLISECOND "millisecond"
+    #define SENTRY_UNIT_SECOND "second"
+    #define SENTRY_UNIT_MINUTE "minute"
+    #define SENTRY_UNIT_HOUR "hour"
+    #define SENTRY_UNIT_DAY "day"
+    #define SENTRY_UNIT_WEEK "week"
+    /* Information units */
+    #define SENTRY_UNIT_BIT "bit"
+    #define SENTRY_UNIT_BYTE "byte"
+    #define SENTRY_UNIT_KILOBYTE "kilobyte"
+    #define SENTRY_UNIT_KIBIBYTE "kibibyte"
+    #define SENTRY_UNIT_MEGABYTE "megabyte"
+    #define SENTRY_UNIT_MEBIBYTE "mebibyte"
+    #define SENTRY_UNIT_GIGABYTE "gigabyte"
+    #define SENTRY_UNIT_GIBIBYTE "gibibyte"
+    #define SENTRY_UNIT_TERABYTE "terabyte"
+    #define SENTRY_UNIT_TEBIBYTE "tebibyte"
+    #define SENTRY_UNIT_PETABYTE "petabyte"
+    #define SENTRY_UNIT_PEBIBYTE "pebibyte"
+    #define SENTRY_UNIT_EXABYTE "exabyte"
+    #define SENTRY_UNIT_EXBIBYTE "exbibyte"
+    /* Fraction units */
+    #define SENTRY_UNIT_RATIO "ratio"
+    #define SENTRY_UNIT_PERCENT "percent"
     /**
      * Creates a new attribute object.
-     *  value is required, unit is optional.
+     *  value is required, unit is optional, but has to be one of the
+     * `SENTRY_UNIT_X` macros.
      *
      * value must be a bool, int, double or string `sentry_value_t`
      * OR a list of bool, int, double or string (with all items being the same type)
@@ Expand Down Expand Up @@
      * Sets attributes created with `sentry_value_new_attribute` to be applied to
      * all:
      * - logs
+     * - metrics
      */
     SENTRY_API void sentry_set_attribute(const char *key, sentry_value_t attribute);
     SENTRY_API void sentry_set_attribute_n(
@@ Expand Down Expand Up @@
     SENTRY_EXPERIMENTAL_API void sentry_options_set_before_send_log(
         sentry_options_t *opts, sentry_before_send_log_function_t func, void *data);
+    /**
+     * Enables or disables the metrics feature.
+     * When disabled, all calls to `sentry_metrics_*()` are no-ops.
+     */
+    SENTRY_EXPERIMENTAL_API void sentry_options_set_enable_metrics(
+        sentry_options_t *opts, int enable_metrics);
+    SENTRY_EXPERIMENTAL_API int sentry_options_get_enable_metrics(
+        const sentry_options_t *opts);
+    /**
+     * Type of the `before_send_metric` callback.
+     *
+     * The callback takes ownership of the `metric` and should usually return
+     * that same metric. In case the metric should be discarded, the
+     * callback needs to call `sentry_value_decref` on the provided metric and
+     * return a `sentry_value_new_null()` instead.
+     */
+    typedef sentry_value_t (*sentry_before_send_metric_function_t)(
+        sentry_value_t metric, void *user_data);
+    /**
+     * Sets the `before_send_metric` callback.
+     */
+    SENTRY_EXPERIMENTAL_API void sentry_options_set_before_send_metric(
+        sentry_options_t *opts, sentry_before_send_metric_function_t func,
+        void *data);
+    /**
+     * Result type for metric operations.
+     * - Success means the metric was enqueued
+     * - Discard means the `before_send_metric` callback discarded the metric
+     * - Failed means the metric wasn't enqueued (buffers are full)
+     * - Disabled means metrics are disabled
+     */
+    typedef enum {
+        SENTRY_METRICS_RESULT_SUCCESS = 0,
+        SENTRY_METRICS_RESULT_DISCARD = 1,
+        SENTRY_METRICS_RESULT_FAILED = 2,
+        SENTRY_METRICS_RESULT_DISABLED = 3
+    } sentry_metrics_result_t;
+    /**
+     * Metrics interface for recording application metrics.
+     *
+     * Metrics are buffered and sent in batches. Each metric includes:
+     * - name: Hierarchical name with dot separators (e.g., "api.requests")
+     * - value: The numeric value to record
+     * - unit: Optional measurement unit (e.g., SENTRY_UNIT_MILLISECOND), or NULL
+     * - attributes: Optional sentry_value_t object with custom attributes, or
+     *   sentry_value_new_null(). Each attribute should be created with
+     *   sentry_value_new_attribute().
+     *
+     * Ownership of the attributes is transferred to the metric function.
+     *
+     * To re-use the same attributes, call `sentry_value_incref` on it
+     * before passing the attributes to the metric function.
+     *
+     * Metrics are automatically associated with the current trace and span if
+     * available. Default attributes (environment, release, SDK info) are attached
+     * automatically.
+     */
+    /**
+     * Records a counter metric. Counters track incrementing values like
+     * request counts or error counts.
+     */
+    SENTRY_EXPERIMENTAL_API sentry_metrics_result_t sentry_metrics_count(
+        const char *name, int64_t value, sentry_value_t attributes);
+    /**
+     * Records a gauge metric. Gauges track values that can go up or down,
+     * like memory usage or active connections.
+     */
+    SENTRY_EXPERIMENTAL_API sentry_metrics_result_t sentry_metrics_gauge(
+        const char *name, double value, const char *unit,
+        sentry_value_t attributes);
+    /**
+     * Records a distribution metric. Distributions track the statistical
+     * distribution of values, useful for timing data and percentiles.
+     */
+    SENTRY_EXPERIMENTAL_API sentry_metrics_result_t sentry_metrics_distribution(
+        const char *name, double value, const char *unit,
+        sentry_value_t attributes);
     #ifdef SENTRY_PLATFORM_LINUX
     /**
@@ Expand Down @@

src/CMakeLists.txt

-Original file line number
+Diff line change
@@ Expand Up / @@ -24,6 +24,8 @@ sentry_target_sources_cwd(sentry @@
     	sentry_logger.h
     	sentry_logs.c
     	sentry_logs.h
+    	sentry_metrics.c
+    	sentry_metrics.h
     	sentry_options.c
     	sentry_options.h
     	sentry_os.c
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: metrics #1498

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feat: metrics #1498

Are you sure you want to change the base?

Uh oh!

feat: metrics #1498

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!