diff --git a/common/windows/cpp/include/keymansentry.h b/common/windows/cpp/include/keymansentry.h index bb65c37b5e..4bc3c9e4cf 100644 --- a/common/windows/cpp/include/keymansentry.h +++ b/common/windows/cpp/include/keymansentry.h @@ -1,5 +1,7 @@ #pragma once +#include + /* * Map of Sentry levels for events and breadcrumbs. */ @@ -26,7 +28,7 @@ int keyman_sentry_main(bool is_keyman_developer, const char *logger, int argc, c int keyman_sentry_wmain(bool is_keyman_developer, const char *logger, int argc, wchar_t *argv[], int(*run)(int, wchar_t**)); void keyman_sentry_setexceptionfilter(); -void keyman_sentry_report_message(keyman_sentry_level_t level, const char *message, bool includeStack = false); +sentry_uuid_t keyman_sentry_report_message(keyman_sentry_level_t level, const char *message, bool includeStack = false); void keyman_sentry_report_start(); // @@ -37,3 +39,4 @@ void keyman_sentry_report_start(); // d) privacy options are correctly checked // void keyman_sentry_test_crash(); +void keyman_sentry_test_message(); diff --git a/common/windows/cpp/src/keymansentry.cpp b/common/windows/cpp/src/keymansentry.cpp index ce287723e1..6a4ce0e4da 100644 --- a/common/windows/cpp/src/keymansentry.cpp +++ b/common/windows/cpp/src/keymansentry.cpp @@ -32,7 +32,7 @@ int keyman_sentry_init(bool is_keyman_developer, const char *logger) { // Set the sentry-db-directory to a writeable location - char szPath[MAX_PATH + 64]; // sufficient length for sentry-0.4.9-db etc + char szPath[MAX_PATH + 64]; // sufficient length for sentry-0.6.0-db etc LPITEMIDLIST pidl; if (SUCCEEDED(SHGetFolderLocation(0, CSIDL_LOCAL_APPDATA, NULL, 0, &pidl))) { @@ -43,7 +43,8 @@ int keyman_sentry_init(bool is_keyman_developer, const char *logger) { *p = 0; } - strcat_s(szPath, "sentry-0.4.9-db"); + // TODO: this should use the SENTRY_VERSOIN + strcat_s(szPath, "sentry-0.6.0-db"); sentry_options_set_database_path(options, szPath); } ILFree(pidl); @@ -132,7 +133,7 @@ sentry_value_t CaptureStackTrace(PVOID TopAddr, DWORD FramesToSkip) { void keyman_sentry_report_exception(DWORD ExceptionCode, PVOID ExceptionAddress) { sentry_value_t event; const int FRAMES_TO_SKIP = 0; - + sentry_uuid_t uuid = { 0 }; char message[64]; wsprintfA(message, "Exception %x at %p", (unsigned int) ExceptionCode, ExceptionAddress); @@ -159,18 +160,22 @@ void keyman_sentry_report_exception(DWORD ExceptionCode, PVOID ExceptionAddress) sentry_value_set_by_key(event, "threads", threads); } - sentry_capture_event(event); + uuid = sentry_capture_event(event); } fputs(message, stderr); fputs("\n", stderr); if(g_report_exceptions) { fputs("This error has been automatically reported to the Keyman team.\n", stderr); + char uuid_string[37]; + sentry_uuid_as_string(&uuid, uuid_string); + fprintf(stderr, "Sentry uuid: %s\n", uuid_string); } } -void keyman_sentry_report_message(keyman_sentry_level_t level, const char *message, bool includeStack) { +sentry_uuid_t keyman_sentry_report_message(keyman_sentry_level_t level, const char *message, bool includeStack) { const int FRAMES_TO_SKIP = 0; + sentry_uuid_t uuid = { 0 }; if ((g_report_exceptions && (level == SENTRY_LEVEL_ERROR || level == SENTRY_LEVEL_DEBUG)) || g_report_messages) { sentry_value_t event; @@ -190,12 +195,15 @@ void keyman_sentry_report_message(keyman_sentry_level_t level, const char *messa } } - sentry_capture_event(event); + uuid = sentry_capture_event(event); } + + return uuid; } /* Wrappers for main, wmain */ +#define SENTRY_USE_LOCAL_FILTER #ifdef SENTRY_USE_LOCAL_FILTER LPTOP_LEVEL_EXCEPTION_FILTER LastFilter; @@ -236,6 +244,11 @@ int keyman_sentry_main(bool is_keyman_developer, const char *logger, int argc, c keyman_sentry_test_crash(); } + if (argc > 1 && !strcmp(argv[1], "-sentry-client-test-message")) { + // Undocumented test parameter + keyman_sentry_test_message(); + } + int res = run(argc, argv); keyman_sentry_shutdown(); @@ -253,6 +266,11 @@ int keyman_sentry_wmain(bool is_keyman_developer, const char *logger, int argc, keyman_sentry_test_crash(); } + if (argc > 1 && !wcscmp(argv[1], L"-sentry-client-test-message")) { + // Undocumented test parameter + keyman_sentry_test_message(); + } + int res = run(argc, argv); keyman_sentry_shutdown(); @@ -260,9 +278,19 @@ int keyman_sentry_wmain(bool is_keyman_developer, const char *logger, int argc, return res; } +void keyman_sentry_test_message() { + fputs("Testing Sentry reporting:\n", stderr); + auto uuid = keyman_sentry_report_message(KEYMAN_SENTRY_LEVEL_INFO, "Testing Sentry message reporting", true); + char uuid_string[37]; + sentry_uuid_as_string(&uuid, uuid_string); + fprintf(stderr, "Sentry uuid: %s\n", uuid_string); + exit(0); +} void keyman_sentry_test_crash() { - fputs("Testing exception reporting:\n", stderr); + fputs("Testing Sentry exception reporting:\n", stderr); RaiseException(0x0EA0BEEF, EXCEPTION_NONCONTINUABLE, 0, NULL); + fputs("Should not have gotten here\n", stderr); + exit(1); } /* Delay load sentry.dll from our subdirectory: #5166 */ @@ -274,12 +302,12 @@ void keyman_sentry_test_crash() { #else #define SENTRY_DLL SENTRY_BASE_DLL #endif -#define SENTRY_INSTALL_PATH "sentry-0.4.9\\" SENTRY_DLL +#define SENTRY_INSTALL_PATH "sentry-0.6.0\\" SENTRY_DLL #define SENTRY_DEV_PATH "common\\windows\\delphi\\ext\\sentry\\" SENTRY_DLL #define ENV_KEYMAN_ROOT "KEYMAN_ROOT" HMODULE LoadSentryLibrary() { - //MAX_PATH + 64 chars leaves space for "\sentry-0.4.9\sentry.x64.dll" + //MAX_PATH + 64 chars leaves space for "\sentry-0.6.0\sentry.x64.dll" char buf[MAX_PATH + 64], keyman_root[MAX_PATH + 64]; int nsize = GetModuleFileNameA(0, buf, MAX_PATH); diff --git a/common/windows/delphi/ext/sentry.txt b/common/windows/delphi/ext/sentry.txt index 2463cd98f3..e3ba432380 100644 --- a/common/windows/delphi/ext/sentry.txt +++ b/common/windows/delphi/ext/sentry.txt @@ -4,7 +4,7 @@ Keyman Third Party Package Readme: Sentry Name: Sentry Purpose: Sentry provides error reporting to a Sentry server Source: https://github.com/getsentry/sentry-native -Version: 0.4.9 +Version: 0.6.0 License: MIT Updated for: N/A Documentation: https://docs.sentry.io/platforms/native/ diff --git a/common/windows/delphi/ext/sentry/crashpad_handler.exe b/common/windows/delphi/ext/sentry/crashpad_handler.exe index 41e10b88e1..76276e6bec 100644 Binary files a/common/windows/delphi/ext/sentry/crashpad_handler.exe and b/common/windows/delphi/ext/sentry/crashpad_handler.exe differ diff --git a/common/windows/delphi/ext/sentry/sentry.dll b/common/windows/delphi/ext/sentry/sentry.dll index 96d753e4cc..86fbd12db6 100644 Binary files a/common/windows/delphi/ext/sentry/sentry.dll and b/common/windows/delphi/ext/sentry/sentry.dll differ diff --git a/common/windows/delphi/ext/sentry/sentry.h b/common/windows/delphi/ext/sentry/sentry.h index 91146520a9..b5381642da 100644 --- a/common/windows/delphi/ext/sentry/sentry.h +++ b/common/windows/delphi/ext/sentry/sentry.h @@ -23,8 +23,14 @@ extern "C" { #endif /* SDK Version */ -#define SENTRY_SDK_NAME "sentry.native" -#define SENTRY_SDK_VERSION "0.4.9" +#ifndef SENTRY_SDK_NAME +# ifdef __ANDROID__ +# define SENTRY_SDK_NAME "sentry.native.android" +# else +# define SENTRY_SDK_NAME "sentry.native" +# endif +#endif +#define SENTRY_SDK_VERSION "0.6.0" #define SENTRY_SDK_USER_AGENT SENTRY_SDK_NAME "/" SENTRY_SDK_VERSION /* common platform detection */ @@ -46,6 +52,10 @@ extern "C" { #elif defined(__linux) || defined(__linux__) # define SENTRY_PLATFORM_LINUX # define SENTRY_PLATFORM_UNIX +#elif defined(_AIX) +/* IBM i PASE is also counted as AIX */ +# define SENTRY_PLATFORM_AIX +# define SENTRY_PLATFORM_UNIX #else # error unsupported platform #endif @@ -189,7 +199,7 @@ SENTRY_API sentry_value_t sentry_value_new_int32(int32_t value); SENTRY_API sentry_value_t sentry_value_new_double(double value); /** - * Creates a new boolen value. + * Creates a new boolean value. */ SENTRY_API sentry_value_t sentry_value_new_bool(int value); @@ -399,8 +409,8 @@ SENTRY_EXPERIMENTAL_API sentry_value_t sentry_value_new_thread( * * See https://develop.sentry.dev/sdk/event-payloads/stacktrace/ * - * The returned object needs to be attached to either an exception - * event, or a thread object. + * The returned object must be attached to either an exception or thread + * object. * * If `ips` is NULL the current stack trace is captured, otherwise `len` * stack trace instruction pointers are attached to the event. @@ -408,6 +418,17 @@ SENTRY_EXPERIMENTAL_API sentry_value_t sentry_value_new_thread( SENTRY_EXPERIMENTAL_API sentry_value_t sentry_value_new_stacktrace( void **ips, size_t len); +/** + * Sets the Stack Trace conforming to the Stack Trace Interface in a value. + * + * The value argument must be either an exception or thread object. + * + * If `ips` is NULL the current stack trace is captured, otherwise `len` stack + * trace instruction pointers are attached to the event. + */ +SENTRY_EXPERIMENTAL_API void sentry_value_set_stacktrace( + sentry_value_t value, void **ips, size_t len); + /** * Adds an Exception to an Event value. * @@ -469,9 +490,12 @@ typedef struct sentry_ucontext_s { * * If the address is given in `addr` the stack is unwound form there. * Otherwise (NULL is passed) the current instruction pointer is used as - * start address. The stack trace is written to `stacktrace_out` with up to - * `max_len` frames being written. The actual number of unwound stackframes - * is returned. + * start address. + * Unwinding with a given `addr` is not supported on all platforms. + * + * The stack trace in the form of instruction-addresses, is written to the + * caller allocated `stacktrace_out`, with up to `max_len` frames being written. + * The actual number of unwound stackframes is returned. */ SENTRY_EXPERIMENTAL_API size_t sentry_unwind_stack( void *addr, void **stacktrace_out, size_t max_len); @@ -479,8 +503,12 @@ SENTRY_EXPERIMENTAL_API size_t sentry_unwind_stack( /** * Unwinds the stack from the given context. * - * The stack trace is written to `stacktrace_out` with up to `max_len` frames - * being written. The actual number of unwound stackframes is returned. + * The caller is responsible to construct an appropriate `sentry_ucontext_t`. + * Unwinding from a user context is not supported on all platforms. + * + * The stack trace in the form of instruction-addresses, is written to the + * caller allocated `stacktrace_out`, with up to `max_len` frames being written. + * The actual number of unwound stackframes is returned. */ SENTRY_EXPERIMENTAL_API size_t sentry_unwind_stack_from_ucontext( const sentry_ucontext_t *uctx, void **stacktrace_out, size_t max_len); @@ -543,13 +571,21 @@ typedef struct sentry_envelope_s sentry_envelope_t; SENTRY_API void sentry_envelope_free(sentry_envelope_t *envelope); /** - * Given an envelope returns the embedded event if there is one. + * Given an Envelope, returns the embedded Event if there is one. * - * This returns a borrowed value to the event in the envelope. + * This returns a borrowed value to the Event in the Envelope. */ SENTRY_API sentry_value_t sentry_envelope_get_event( const sentry_envelope_t *envelope); +/** + * Given an Envelope, returns the embedded Transaction if there is one. + * + * This returns a borrowed value to the Transaction in the Envelope. + */ +SENTRY_EXPERIMENTAL_API sentry_value_t sentry_envelope_get_transaction( + const sentry_envelope_t *envelope); + /** * Serializes the envelope. * @@ -571,7 +607,7 @@ SENTRY_API int sentry_envelope_write_to_file( /** * The Sentry Client Options. * - * See https://docs.sentry.io/error-reporting/configuration/ + * See https://docs.sentry.io/platforms/native/configuration/ */ struct sentry_options_s; typedef struct sentry_options_s sentry_options_t; @@ -595,13 +631,16 @@ typedef struct sentry_options_s sentry_options_t; * * `startup_func`: This hook will be called by sentry inside of `sentry_init` * and instructs the transport to initialize itself. Failures will bubble up * to `sentry_init`. + * * `flush_func`: Instructs the transport to flush its queue. + * This hook receives a millisecond-resolution `timeout` parameter and should + * return `0` if the transport queue is flushed within the timeout. * * `shutdown_func`: Instructs the transport to flush its queue and shut down. * This hook receives a millisecond-resolution `timeout` parameter and should - * return `true` when the transport was flushed and shut down successfully. - * In case of `false`, sentry will log an error, but continue with freeing the - * transport. + * return `0` if the transport is flushed and shut down successfully. + * In case of a non-zero return value, sentry will log an error, but continue + * with freeing the transport. * * `free_func`: Frees the transports `state`. This hook might be called even - * though `shutdown_func` returned `false` previously. + * though `shutdown_func` returned a failure code previously. * * The transport interface might be extended in the future with hooks to flush * its internal queue without shutting down, and to dump its internal queue to @@ -641,6 +680,16 @@ SENTRY_API void sentry_transport_set_free_func( SENTRY_API void sentry_transport_set_startup_func(sentry_transport_t *transport, int (*startup_func)(const sentry_options_t *options, void *state)); +/** + * Sets the transport flush hook. + * + * This hook will receive a millisecond-resolution timeout. + * It should return `0` if all the pending envelopes are + * sent within the timeout, or `1` if the timeout is hit. + */ +SENTRY_API void sentry_transport_set_flush_func(sentry_transport_t *transport, + int (*flush_func)(uint64_t timeout, void *state)); + /** * Sets the transport shutdown hook. * @@ -671,6 +720,20 @@ SENTRY_API void sentry_transport_free(sentry_transport_t *transport); SENTRY_API sentry_transport_t *sentry_new_function_transport( void (*func)(const sentry_envelope_t *envelope, void *data), void *data); +/** + * This represents an interface for user-defined backends. + * + * Backends are responsible to handle crashes. They are maintained at runtime + * via various life-cycle hooks from the sentry-core. + * + * At this point none of those interfaces are exposed in the API including + * creation and destruction. The main use-case of the backend in the API at this + * point is to disable it via `sentry_options_set_backend` at runtime before it + * is initialized. + */ +struct sentry_backend_s; +typedef struct sentry_backend_s sentry_backend_t; + /* -- Options APIs -- */ /** @@ -707,11 +770,28 @@ SENTRY_API void sentry_options_set_transport( * call `sentry_value_decref` on the provided event, and return a * `sentry_value_new_null()` instead. * + * If you have set an `on_crash` callback (independent of whether it discards or + * retains the event), `before_send` will no longer be invoked for crash-events, + * which allows you to better distinguish between crashes and all other events + * in client-side pre-processing. + * * This function may be invoked inside of a signal handler and must be safe for * that purpose, see https://man7.org/linux/man-pages/man7/signal-safety.7.html. * On Windows, it may be called from inside of a `UnhandledExceptionFilter`, see * the documentation on SEH (structured exception handling) for more information * https://docs.microsoft.com/en-us/windows/win32/debug/structured-exception-handling + * + * Up to version 0.4.18 the `before_send` callback wasn't invoked in case the + * event sampling discarded an event. In the current implementation the + * `before_send` callback is invoked even if the event sampling discards the + * event, following the cross-SDK session filter order: + * + * https://develop.sentry.dev/sdk/sessions/#filter-order + * + * On Windows the crashpad backend can capture fast-fail crashes which by-pass + * SEH. Since the `before_send` is called by a local exception-handler, it will + * not be invoked when such a crash happened, even though a minidump will be + * sent. */ typedef sentry_value_t (*sentry_event_function_t)( sentry_value_t event, void *hint, void *closure); @@ -724,6 +804,64 @@ typedef sentry_value_t (*sentry_event_function_t)( SENTRY_API void sentry_options_set_before_send( sentry_options_t *opts, sentry_event_function_t func, void *data); +/** + * Type of the `on_crash` callback. + * + * The `on_crash` callback replaces the `before_send` callback for crash events. + * The interface is analogous to `before_send` in that the callback takes + * ownership of the `event`, and should usually return that same event. In case + * the event should be discarded, the callback needs to call + * `sentry_value_decref` on the provided event, and return a + * `sentry_value_new_null()` instead. + * + * Only the `inproc` backend currently fills the passed-in event with useful + * data and processes any modifications to the return value. Since both + * `breakpad` and `crashpad` use minidumps to capture the crash state, the + * passed-in event is empty when using these backends, and they ignore any + * changes to the return value. + * + * If you set this callback in the options, it prevents a concurrently enabled + * `before_send` callback from being invoked in the crash case. This allows for + * better differentiation between crashes and other events and gradual migration + * from existing `before_send` implementations: + * + * - if you have a `before_send` implementation and do not define an `on_crash` + * callback your application will receive both normal and crash events as + * before + * - if you have a `before_send` implementation but only want to handle normal + * events with it, then you can define an `on_crash` callback that returns + * the passed-in event and does nothing else + * - if you are not interested in normal events, but only want to act on + * crashes (within the limits mentioned below), then only define an + * `on_crash` callback with the option to filter (on all backends) or enrich + * (only inproc) the crash event + * + * This function may be invoked inside of a signal handler and must be safe for + * that purpose, see https://man7.org/linux/man-pages/man7/signal-safety.7.html. + * On Windows, it may be called from inside of a `UnhandledExceptionFilter`, see + * the documentation on SEH (structured exception handling) for more information + * https://docs.microsoft.com/en-us/windows/win32/debug/structured-exception-handling + * + * Platform-specific behavior: + * + * - does not work with crashpad on macOS. + * - for breakpad on Linux the `uctx` parameter is always NULL. + * - on Windows the crashpad backend can capture fast-fail crashes which + * by-pass SEH. Since `on_crash` is called by a local exception-handler, it will + * not be invoked when such a crash happened, even though a minidump will be + * sent. + */ +typedef sentry_value_t (*sentry_crash_function_t)( + const sentry_ucontext_t *uctx, sentry_value_t event, void *closure); + +/** + * Sets the `on_crash` callback. + * + * See the `sentry_crash_function_t` typedef above for more information. + */ +SENTRY_API void sentry_options_set_on_crash( + sentry_options_t *opts, sentry_crash_function_t func, void *data); + /** * Sets the DSN. */ @@ -738,6 +876,19 @@ SENTRY_API const char *sentry_options_get_dsn(const sentry_options_t *opts); * Sets the sample rate, which should be a double between `0.0` and `1.0`. * Sentry will randomly discard any event that is captured using * `sentry_capture_event` when a sample rate < 1 is set. + * + * The sampling happens at the end of the event processing according to the + * following order: + * + * https://develop.sentry.dev/sdk/sessions/#filter-order + * + * Only items 3. to 6. are currently applicable to sentry-native. This means + * each processing step is executed even if the sampling discards the event + * before sending it to the backend. This is particularly relevant to users of + * the `before_send` callback. + * + * The above is in contrast to versions up to 0.4.18 where the sampling happened + * at the beginning of the processing/filter sequence. */ SENTRY_API void sentry_options_set_sample_rate( sentry_options_t *opts, double sample_rate); @@ -999,6 +1150,29 @@ SENTRY_API void sentry_options_set_database_pathw( SENTRY_API void sentry_options_set_system_crash_reporter_enabled( sentry_options_t *opts, int enabled); +/** + * Sets the maximum time (in milliseconds) to wait for the asynchronous tasks to + * end on shutdown, before attempting a forced termination. + */ +SENTRY_API void sentry_options_set_shutdown_timeout( + sentry_options_t *opts, uint64_t shutdown_timeout); + +/** + * Gets the maximum time (in milliseconds) to wait for the asynchronous tasks to + * end on shutdown, before attempting a forced termination. + */ +SENTRY_API uint64_t sentry_options_get_shutdown_timeout(sentry_options_t *opts); + +/** + * Sets a user-defined backend. + * + * Since creation and destruction of backends is not exposed in the API, this + * can only be used to set the backend to `NULL`, which disables the backend in + * the initialization. + */ +SENTRY_API void sentry_options_set_backend( + sentry_options_t *opts, sentry_backend_t *backend); + /* -- Global APIs -- */ /** @@ -1012,6 +1186,15 @@ SENTRY_API void sentry_options_set_system_crash_reporter_enabled( */ SENTRY_API int sentry_init(sentry_options_t *options); +/** + * Instructs the transport to flush its send queue. + * + * The `timeout` parameter is in milliseconds. + * + * Returns 0 on success, or a non-zero return value in case the timeout is hit. + */ +SENTRY_API int sentry_flush(uint64_t timeout); + /** * Shuts down the sentry client and forces transports to flush out. * @@ -1080,6 +1263,10 @@ SENTRY_API sentry_user_consent_t sentry_user_consent_get(void); /** * Sends a sentry event. + * + * If returns a nil UUID if the event being passed in is a transaction, and the + * transaction will not be sent nor consumed. `sentry_transaction_finish` should + * be used to send transactions. */ SENTRY_API sentry_uuid_t sentry_capture_event(sentry_value_t event); @@ -1154,16 +1341,48 @@ SENTRY_API void sentry_remove_fingerprint(void); */ SENTRY_API void sentry_set_transaction(const char *transaction); -/** - * Removes the transaction. - */ -SENTRY_API void sentry_remove_transaction(void); - /** * Sets the event level. */ SENTRY_API void sentry_set_level(sentry_level_t level); +/** + * Sets the maximum number of spans that can be attached to a + * transaction. + */ +SENTRY_EXPERIMENTAL_API void sentry_options_set_max_spans( + sentry_options_t *opts, size_t max_spans); + +/** + * Gets the maximum number of spans that can be attached to a + * transaction. + */ +SENTRY_EXPERIMENTAL_API size_t sentry_options_get_max_spans( + sentry_options_t *opts); + +/** + * Sets the sample rate for transactions. Should be a double between + * `0.0` and `1.0`. Transactions will be randomly discarded during + * `sentry_transaction_finish` when the sample rate is < 1.0. + */ +SENTRY_EXPERIMENTAL_API void sentry_options_set_traces_sample_rate( + sentry_options_t *opts, double sample_rate); + +/** + * Returns the sample rate for transactions. + */ +SENTRY_EXPERIMENTAL_API double sentry_options_get_traces_sample_rate( + sentry_options_t *opts); + +/* -- Session APIs -- */ + +typedef enum { + SENTRY_SESSION_STATUS_OK, + SENTRY_SESSION_STATUS_CRASHED, + SENTRY_SESSION_STATUS_ABNORMAL, + SENTRY_SESSION_STATUS_EXITED, +} sentry_session_status_t; + /** * Starts a new session. */ @@ -1174,6 +1393,505 @@ SENTRY_API void sentry_start_session(void); */ SENTRY_API void sentry_end_session(void); +/** + * Ends a session with an explicit `status` code. + */ +SENTRY_EXPERIMENTAL_API void sentry_end_session_with_status( + sentry_session_status_t status); + +/* -- Performance Monitoring/Tracing APIs -- */ + +/** + * A sentry Transaction Context. + * + * See Transaction Interface under + * https://develop.sentry.dev/sdk/performance/#new-span-and-transaction-classes + */ +struct sentry_transaction_context_s; +typedef struct sentry_transaction_context_s sentry_transaction_context_t; + +/** + * A sentry Transaction. + * + * See https://develop.sentry.dev/sdk/event-payloads/transaction/ + */ +struct sentry_transaction_s; +typedef struct sentry_transaction_s sentry_transaction_t; + +/** + * A sentry Span. + * + * See https://develop.sentry.dev/sdk/event-payloads/span/ + */ +struct sentry_span_s; +typedef struct sentry_span_s sentry_span_t; + +/** + * Constructs a new Transaction Context. The returned value needs to be passed + * into `sentry_transaction_start` in order to be recorded and sent to sentry. + * + * See + * https://docs.sentry.io/platforms/native/enriching-events/transaction-name/ + * for an explanation of a Transaction's `name`, and + * https://develop.sentry.dev/sdk/performance/span-operations/ for conventions + * around an `operation`'s value. + * + * Also see https://develop.sentry.dev/sdk/event-payloads/transaction/#anatomy + * for an explanation of `operation`, in addition to other properties and + * actions that can be performed on a Transaction. + * + * The returned value is not thread-safe. Users are expected to ensure that + * appropriate locking mechanisms are implemented over the Transaction Context + * if it needs to be mutated across threads. Methods operating on the + * Transaction Context will mention what kind of expectations they carry if they + * need to mutate or access the object in a thread-safe way. + */ +SENTRY_EXPERIMENTAL_API sentry_transaction_context_t * +sentry_transaction_context_new(const char *name, const char *operation); + +/** + * Sets the `name` on a Transaction Context, which will be used in the + * Transaction constructed off of the context. + * + * The Transaction Context should not be mutated by other functions while + * setting a name on it. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_name( + sentry_transaction_context_t *tx_cxt, const char *name); + +/** + * Sets the `operation` on a Transaction Context, which will be used in the + * Transaction constructed off of the context + * + * See https://develop.sentry.dev/sdk/performance/span-operations/ for + * conventions on `operation`s. + * + * The Transaction Context should not be mutated by other functions while + * setting an operation on it. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_operation( + sentry_transaction_context_t *tx_cxt, const char *operation); + +/** + * Sets the `sampled` field on a Transaction Context, which will be used in the + * Transaction constructed off of the context. + * + * When passed any value above 0, the Transaction will bypass all sampling + * options and always be sent to sentry. If passed 0, this Transaction and its + * child spans will never be sent to sentry. + * + * The Transaction Context should not be mutated by other functions while + * setting `sampled` on it. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_sampled( + sentry_transaction_context_t *tx_cxt, int sampled); + +/** + * Removes the `sampled` field on a Transaction Context, which will be used in + * the Transaction constructed off of the context. + * + * The Transaction will use the sampling rate as defined in `sentry_options`. + * + * The Transaction Context should not be mutated by other functions while + * removing `sampled`. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_context_remove_sampled( + sentry_transaction_context_t *tx_cxt); + +/** + * Update the Transaction Context with the given HTTP header key/value pair. + * + * This is used to propagate distributed tracing metadata from upstream + * services. Therefore, the headers of incoming requests should be fed into this + * function so that sentry is able to continue a trace that was started by an + * upstream service. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_context_update_from_header( + sentry_transaction_context_t *tx_cxt, const char *key, const char *value); + +/** + * Starts a new Transaction based on the provided context, restored from an + * external integration (i.e. a span from a different SDK) or manually + * constructed by a user. + * + * The second parameter is a custom Sampling Context to be used with a Traces + * Sampler to make a more informed sampling decision. The SDK does not currently + * support a custom Traces Sampler and this parameter is ignored for the time + * being but needs to be provided. + * + * Returns a Transaction, which is expected to be manually managed by the + * caller. Manual management involves ensuring that `sentry_transaction_finish` + * is invoked for the Transaction, and that the caller manually starts and + * finishes any child Spans as needed on the Transaction. + * + * Not invoking `sentry_transaction_finish` with the returned Transaction means + * it will be discarded, and will not be sent to sentry. + * + * To ensure that any Events or Message Events are associated with this + * Transaction while it is active, invoke and pass in the Transaction returned + * by this function to `sentry_set_transaction_object`. Further documentation on + * this can be found in `sentry_set_transaction_object`'s docstring. + * + * Takes ownership of `transaction_context`. A Transaction Context cannot be + * modified or re-used after it is used to start a Transaction. + * + * The returned value is not thread-safe. Users are expected to ensure that + * appropriate locking mechanisms are implemented over the Transaction if it + * needs to be mutated across threads. Methods operating on the Transaction will + * mention what kind of expectations they carry if they need to mutate or access + * the object in a thread-safe way. + */ +SENTRY_EXPERIMENTAL_API sentry_transaction_t *sentry_transaction_start( + sentry_transaction_context_t *tx_cxt, sentry_value_t sampling_ctx); + +/** + * Finishes and sends a Transaction to sentry. The event ID of the Transaction + * will be returned if this was successful; A nil UUID will be returned + * otherwise. + * + * Always takes ownership of `transaction`, regardless of whether the operation + * was successful or not. A Transaction cannot be modified or re-used after it + * is finished. + */ +SENTRY_EXPERIMENTAL_API sentry_uuid_t sentry_transaction_finish( + sentry_transaction_t *tx); + +/** + * Sets the Transaction so any Events sent while the Transaction + * is active will be associated with the Transaction. + * + * If the Transaction being passed in is unsampled, it will still be associated + * with any new Events. This will lead to some Events pointing to orphan or + * missing traces in sentry, see + * https://docs.sentry.io/product/sentry-basics/tracing/trace-view/#orphan-traces-and-broken-subtraces + * + * This increases the number of references pointing to the Transaction. Invoke + * `sentry_transaction_finish` to remove the Transaction set by this function as + * well as its reference by passing in the same Transaction as the one passed + * into this function. + */ +SENTRY_EXPERIMENTAL_API void sentry_set_transaction_object( + sentry_transaction_t *tx); + +/** + * Sets the Span so any Events sent while the Span + * is active will be associated with the Span. + * + * This increases the number of references pointing to the Span. Invoke + * `sentry_span_finish` to remove the Span set by this function as well + * as its reference by passing in the same Span as the one passed into + * this function. + */ +SENTRY_EXPERIMENTAL_API void sentry_set_span(sentry_span_t *span); + +/** + * Starts a new Span. + * + * The return value of `sentry_transaction_start` should be passed in as + * `parent`. + * + * Both `operation` and `description` can be null, but it is recommended to + * supply the former. See + * https://develop.sentry.dev/sdk/performance/span-operations/ for conventions + * around operations. + * + * See https://develop.sentry.dev/sdk/event-payloads/span/ for a description of + * the created Span's properties and expectations for `operation` and + * `description`. + * + * Returns a value that should be passed into `sentry_span_finish`. Not + * finishing the Span means it will be discarded, and will not be sent to + * sentry. `sentry_value_null` will be returned if the child Span could not be + * created. + * + * To ensure that any Events or Message Events are associated with this + * Span while it is active, invoke and pass in the Span returned + * by this function to `sentry_set_span`. Further documentation on this can be + * found in `sentry_set_span`'s docstring. + * + * This increases the number of references pointing to the Transaction. + * + * The returned value is not thread-safe. Users are expected to ensure that + * appropriate locking mechanisms are implemented over the Span if it needs + * to be mutated across threads. Methods operating on the Span will mention what + * kind of expectations they carry if they need to mutate or access the object + * in a thread-safe way. + */ +SENTRY_EXPERIMENTAL_API sentry_span_t *sentry_transaction_start_child( + sentry_transaction_t *parent, char *operation, char *description); + +/** + * Starts a new Span. + * + * The return value of `sentry_span_start_child` may be passed in as `parent`. + * + * Both `operation` and `description` can be null, but it is recommended to + * supply the former. See + * https://develop.sentry.dev/sdk/performance/span-operations/ for conventions + * around operations. + * + * See https://develop.sentry.dev/sdk/event-payloads/span/ for a description of + * the created Span's properties and expectations for `operation` and + * `description`. + * + * Returns a value that should be passed into `sentry_span_finish`. Not + * finishing the Span means it will be discarded, and will not be sent to + * sentry. `sentry_value_null` will be returned if the child Span could not be + * created. + * + * To ensure that any Events or Message Events are associated with this + * Span while it is active, invoke and pass in the Span returned + * by this function to `sentry_set_span`. Further documentation on this can be + * found in `sentry_set_span`'s docstring. + * + * The returned value is not thread-safe. Users are expected to ensure that + * appropriate locking mechanisms are implemented over the Span if it needs + * to be mutated across threads. Methods operating on the Span will mention what + * kind of expectations they carry if they need to mutate or access the object + * in a thread-safe way. + */ +SENTRY_EXPERIMENTAL_API sentry_span_t *sentry_span_start_child( + sentry_span_t *parent, char *operation, char *description); + +/** + * Finishes a Span. + * + * This takes ownership of `span`. A Span cannot be modified or re-used after it + * is finished. + * + * This will mutate the `span`'s containing Transaction, so the containing + * Transaction should also not be mutated by other functions when finishing a + * span. + */ +SENTRY_EXPERIMENTAL_API void sentry_span_finish(sentry_span_t *span); + +/** + * Sets a tag on a Transaction to the given string value. + * + * Tags longer than 200 bytes will be truncated. + * + * The Transaction should not be mutated by other functions while a tag is being + * set on it. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_set_tag( + sentry_transaction_t *transaction, const char *tag, const char *value); + +/** + * Removes a tag from a Transaction. + * + * The Transaction should not be mutated by other functions while a tag is being + * removed from it. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_remove_tag( + sentry_transaction_t *transaction, const char *tag); + +/** + * Sets the given key in a Transaction's "data" section to the given value. + * + * The Transaction should not be mutated by other functions while data is being + * set on it. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_set_data( + sentry_transaction_t *transaction, const char *key, sentry_value_t value); + +/** + * Removes a key from a Transaction's "data" section. + * + * The Transaction should not be mutated by other functions while data is being + * removed from it. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_remove_data( + sentry_transaction_t *transaction, const char *key); + +/** + * Sets a tag on a Span to the given string value. + * + * Tags longer than 200 bytes will be truncated. + * + * The Span should not be mutated by other functions while a tag is being set on + * it. + */ +SENTRY_EXPERIMENTAL_API void sentry_span_set_tag( + sentry_span_t *span, const char *tag, const char *value); + +/** + * Removes a tag from a Span. + * + * The Span should not be mutated by other functions while a tag is being + * removed from it. + */ +SENTRY_EXPERIMENTAL_API void sentry_span_remove_tag( + sentry_span_t *span, const char *tag); + +/** + * Sets the given key in a Span's "data" section to the given value. + * + * The Span should not be mutated by other functions while data is being set on + * it. + */ +SENTRY_EXPERIMENTAL_API void sentry_span_set_data( + sentry_span_t *span, const char *key, sentry_value_t value); + +/** + * Removes a key from a Span's "data" section. + * + * The Span should not be mutated by other functions while data is being removed + * from it. + */ +SENTRY_EXPERIMENTAL_API void sentry_span_remove_data( + sentry_span_t *span, const char *key); + +/** + * Sets a Transaction's name. + * + * The Transaction should not be mutated by other functions while setting its + * name. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_set_name( + sentry_transaction_t *transaction, const char *name); + +/** + * The status of a Span or Transaction. + * + * See https://develop.sentry.dev/sdk/event-payloads/span/ for documentation. + */ +typedef enum { + // The operation completed successfully. + // HTTP status 100..299 + successful redirects from the 3xx range. + SENTRY_SPAN_STATUS_OK, + // The operation was cancelled (typically by the user). + SENTRY_SPAN_STATUS_CANCELLED, + // Unknown. Any non-standard HTTP status code. + // "We do not know whether the transaction failed or succeeded." + SENTRY_SPAN_STATUS_UNKNOWN, + // Client specified an invalid argument. 4xx. + // Note that this differs from FailedPrecondition. InvalidArgument + // indicates arguments that are problematic regardless of the + // state of the system. + SENTRY_SPAN_STATUS_INVALID_ARGUMENT, + // Deadline expired before operation could complete. + // For operations that change the state of the system, this error may be + // returned even if the operation has been completed successfully. + // HTTP redirect loops and 504 Gateway Timeout. + SENTRY_SPAN_STATUS_DEADLINE_EXCEEDED, + // 404 Not Found. Some requested entity (file or directory) was not found. + SENTRY_SPAN_STATUS_NOT_FOUND, + // Already exists (409) + // Some entity that we attempted to create already exists. + SENTRY_SPAN_STATUS_ALREADY_EXISTS, + // 403 Forbidden + // The caller does not have permission to execute the specified operation. + SENTRY_SPAN_STATUS_PERMISSION_DENIED, + // 429 Too Many Requests + // Some resource has been exhausted, perhaps a per-user quota or perhaps + // the entire file system is out of space. + SENTRY_SPAN_STATUS_RESOURCE_EXHAUSTED, + // Operation was rejected because the system is not in a state required for + // the operation's execution. + SENTRY_SPAN_STATUS_FAILED_PRECONDITION, + // The operation was aborted, typically due to a concurrency issue. + SENTRY_SPAN_STATUS_ABORTED, + // Operation was attempted past the valid range. + SENTRY_SPAN_STATUS_OUT_OF_RANGE, + // 501 Not Implemented + // Operation is not implemented or not enabled. + SENTRY_SPAN_STATUS_UNIMPLEMENTED, + // Other/generic 5xx + SENTRY_SPAN_STATUS_INTERNAL_ERROR, + // 503 Service Unavailable + SENTRY_SPAN_STATUS_UNAVAILABLE, + // Unrecoverable data loss or corruption + SENTRY_SPAN_STATUS_DATA_LOSS, + // 401 Unauthorized (actually does mean unauthenticated according to RFC + // 7235) + // Prefer PermissionDenied if a user is logged in. + SENTRY_SPAN_STATUS_UNAUTHENTICATED, +} sentry_span_status_t; + +/** + * Sets a Span's status. + * + * The Span should not be mutated by other functions while setting its status. + */ +SENTRY_EXPERIMENTAL_API void sentry_span_set_status( + sentry_span_t *span, sentry_span_status_t status); + +/** + * Sets a Transaction's status. + * + * The Transaction should not be mutated by other functions while setting its + * status. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_set_status( + sentry_transaction_t *tx, sentry_span_status_t status); + +/** + * Type of the `iter_headers` callback. + * + * The callback is being called with HTTP header key/value pairs. + * These headers can be attached to outgoing HTTP requests to propagate + * distributed tracing metadata to downstream services. + * + */ +typedef void (*sentry_iter_headers_function_t)( + const char *key, const char *value, void *userdata); + +/** + * Iterates the distributed tracing HTTP headers for the given span. + */ +SENTRY_EXPERIMENTAL_API void sentry_span_iter_headers(sentry_span_t *span, + sentry_iter_headers_function_t callback, void *userdata); + +/** + * Iterates the distributed tracing HTTP headers for the given transaction. + */ +SENTRY_EXPERIMENTAL_API void sentry_transaction_iter_headers( + sentry_transaction_t *tx, sentry_iter_headers_function_t callback, + void *userdata); + +/** + * Returns whether the application has crashed on the last run. + * + * Notes: + * * The underlying value is set by sentry_init() - it must be called first. + * * Call sentry_clear_crashed_last_run() to reset for the next app run. + * + * Possible return values: + * 1 = the last run was a crash + * 0 = no crash recognized + * -1 = sentry_init() hasn't been called yet + */ +SENTRY_EXPERIMENTAL_API int sentry_get_crashed_last_run(void); + +/** + * Clear the status of the "crashed-last-run". You should explicitly call + * this after sentry_init() if you're using sentry_get_crashed_last_run(). + * Otherwise, the same information is reported on any subsequent runs. + * + * Notes: + * * This doesn't change the value of sentry_get_crashed_last_run() yet. + * However, if sentry_init() is called again, the value will change. + * * This may only be called after sentry_init() and before sentry_close(). + * + * Returns 0 on success, 1 on error. + */ +SENTRY_EXPERIMENTAL_API int sentry_clear_crashed_last_run(void); + +/** + * Sentry SDK version. + */ +SENTRY_EXPERIMENTAL_API const char *sentry_sdk_version(void); + +/** + * Sentry SDK name. + */ +SENTRY_EXPERIMENTAL_API const char *sentry_sdk_name(void); + +/** + * Sentry SDK User-Agent. + */ +SENTRY_EXPERIMENTAL_API const char *sentry_sdk_user_agent(void); + #ifdef __cplusplus } #endif diff --git a/common/windows/delphi/ext/sentry/sentry.lib b/common/windows/delphi/ext/sentry/sentry.lib index f9c6b6671d..9858e8c039 100644 Binary files a/common/windows/delphi/ext/sentry/sentry.lib and b/common/windows/delphi/ext/sentry/sentry.lib differ diff --git a/common/windows/delphi/ext/sentry/sentry.pas b/common/windows/delphi/ext/sentry/sentry.pas index 24e85c9b9a..af47eb383f 100644 --- a/common/windows/delphi/ext/sentry/sentry.pas +++ b/common/windows/delphi/ext/sentry/sentry.pas @@ -1,35 +1,35 @@ -{$D-} // Don't include debug information -// Delphi translation of sentry.h -// Sentry Native API 0.4.9 -// https://github.com/getsentry/sentry-native -unit sentry; - -{ - * NOTE on encodings: - * - * Sentry will assume an encoding of UTF-8 for all string data that is captured - * and being sent to sentry as an Event. - * All the functions that are dealing with *paths* will assume an OS-specific - * encoding, typically ANSI on Windows, UTF-8 macOS, and the locale encoding on - * Linux; and they provide wchar-compatible alternatives on Windows which are - * preferred. -} - -interface - -{$DEFINE SENTRY_API} - -//{$ALIGN ON} -{$MINENUMSIZE 4} - -{$WARN SYMBOL_PLATFORM OFF} - -{$IF DEFINED(MSWINDOWS)} - -uses - Winapi.Windows; - -{$DEFINE SENTRY_UUID_WINDOWS} +{$D-} // Don't include debug information +// Delphi translation of sentry.h +// Sentry Native API 0.6.0 - ***excluding performance APIs*** +// https://github.com/getsentry/sentry-native +unit sentry; + +{ + * NOTE on encodings: + * + * Sentry will assume an encoding of UTF-8 for all string data that is captured + * and being sent to sentry as an Event. + * All the functions that are dealing with *paths* will assume an OS-specific + * encoding, typically ANSI on Windows, UTF-8 macOS, and the locale encoding on + * Linux; and they provide wchar-compatible alternatives on Windows which are + * preferred. +} + +interface + +{$DEFINE SENTRY_API} + +//{$ALIGN ON} +{$MINENUMSIZE 4} + +{$WARN SYMBOL_PLATFORM OFF} + +{$IF DEFINED(MSWINDOWS)} + +uses + Winapi.Windows; + +{$DEFINE SENTRY_UUID_WINDOWS} {$ELSEIF DEFINED(ANDROID)} @@ -45,15 +45,15 @@ uses {$ENDIF} const -{$IFDEF WIN64} +{$IFDEF WIN64} sentry_dll = 'sentry.x64.dll'; {$ELSE} sentry_dll = 'sentry.dll'; {$ENDIF} - + const SENTRY_SDK_NAME = 'sentry.native'; - SENTRY_SDK_VERSION = '0.4.9'; + SENTRY_SDK_VERSION = '0.6.0'; SENTRY_SDK_USER_AGENT = SENTRY_SDK_NAME + '/' + SENTRY_SDK_VERSION; {$IF DEFINED(MSWINDOWS)} @@ -62,32 +62,32 @@ const {$MESSAGE ERROR 'Unsupported platform'} {$ENDIF} -type - size_t = NativeUInt; - -// The library internally uses the system malloc and free functions to manage -// memory. It does not use realloc. The reason for this is that on unix -// platforms we fall back to a simplistic page allocator once we have -// encountered a SIGSEGV or other terminating signal as malloc is no longer -// safe to use. Since we cannot portably reallocate allocations made on the -// pre-existing allocator we're instead not using realloc. -// -// Note also that after SIGSEGV sentry_free() becomes a noop. - -// -// allocates memory with the underlying allocator -// -function sentry_malloc(size: size_t): Pointer; cdecl; external sentry_dll delayed; - -// -// releases memory allocated from the underlying allocator -procedure sentry_free(ptr: Pointer); cdecl; external sentry_dll delayed; - +type + size_t = NativeUInt; + +// The library internally uses the system malloc and free functions to manage +// memory. It does not use realloc. The reason for this is that on unix +// platforms we fall back to a simplistic page allocator once we have +// encountered a SIGSEGV or other terminating signal as malloc is no longer +// safe to use. Since we cannot portably reallocate allocations made on the +// pre-existing allocator we're instead not using realloc. +// +// Note also that after SIGSEGV sentry_free() becomes a noop. + +// +// allocates memory with the underlying allocator +// +function sentry_malloc(size: size_t): Pointer; cdecl; external sentry_dll delayed; + +// +// releases memory allocated from the underlying allocator +procedure sentry_free(ptr: Pointer); cdecl; external sentry_dll delayed; + // legacy function. Alias for `sentry_free`. procedure sentry_string_free(str: PAnsiChar); cdecl; - + // -- Protocol Value API -- - + // // Type of a sentry value. // @@ -102,7 +102,7 @@ type SENTRY_VALUE_TYPE_LIST, SENTRY_VALUE_TYPE_OBJECT ); - + // // Represents a sentry protocol value. // @@ -119,20 +119,20 @@ type // automatically happens for some shared values in the event payload like // the module list. // - -type - {sentry_value_u = record - case Integer of - 0: (_bits: UInt64); - 1: (_double: Double); - end; - + +type + {sentry_value_u = record + case Integer of + 0: (_bits: UInt64); + 1: (_double: Double); + end; + sentry_value_t = sentry_value_u;} sentry_value_t = UInt64; - + +// +// Increments the reference count on the value.\ // -// Increments the reference count on the value.\ -// procedure sentry_value_incref( value: sentry_value_t ); cdecl; external sentry_dll delayed; @@ -214,7 +214,7 @@ function sentry_value_new_object: sentry_value_t; cdecl; external sentry_dll de function sentry_value_get_type( value: sentry_value_t ): sentry_value_type_t; cdecl; external sentry_dll delayed; - + // // Sets a key to a value in the map. // @@ -234,8 +234,8 @@ function sentry_value_remove_by_key( value: sentry_value_t; const k: PAnsiChar ): Integer; cdecl; external sentry_dll delayed; - -// + +// // Appends a value to a list. // // This moves the ownership of the value into the list. The caller does not @@ -278,9 +278,12 @@ function sentry_value_get_by_key( const k: PAnsiChar ): sentry_value_t; cdecl; external sentry_dll delayed; - // - // Looks up a value in a map by key. If missing a null value is returned. - // The returned value is owned. + +// + +// Looks up a value in a map by key. If missing a null value is returned. + +// The returned value is owned. // // If the caller no longer needs the value it must be released with // `sentry_value_decref`. @@ -376,20 +379,20 @@ type sentry_level_e = ( sentry_level_t = sentry_level_e; // -// Creates a new empty Event value. -// -// See https://docs.sentry.io/platforms/native/enriching-events/ for how to -// further work with events, and https://develop.sentry.dev/sdk/event-payloads/ -// for a detailed overview of the possible properties of an Event. -// +// Creates a new empty Event value. +// +// See https://docs.sentry.io/platforms/native/enriching-events/ for how to +// further work with events, and https://develop.sentry.dev/sdk/event-payloads/ +// for a detailed overview of the possible properties of an Event. +// function sentry_value_new_event: sentry_value_t; cdecl; external sentry_dll delayed; // // Creates a new Message Event value. -// -// See https://develop.sentry.dev/sdk/event-payloads/message/ -// -// `logger` can be NULL to omit the logger value. +// +// See https://develop.sentry.dev/sdk/event-payloads/message/ +// +// `logger` can be NULL to omit the logger value. // function sentry_value_new_message_event( level: sentry_level_t; @@ -399,8 +402,8 @@ function sentry_value_new_message_event( // // Creates a new Breadcrumb with a specific type and message. -// -// See https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/ +// +// See https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/ // function sentry_value_new_breadcrumb( const _type: PAnsiChar; @@ -408,73 +411,87 @@ function sentry_value_new_breadcrumb( ): sentry_value_t; cdecl; external sentry_dll delayed; // -// Creates a new Exception value. -// -// This is intended for capturing language-level exception, such as from a -// try-catch block. `type` and `value` here refer to the exception class and -// a possible description. -// -// See https://develop.sentry.dev/sdk/event-payloads/exception/ -// -// The returned value needs to be attached to an event via -// `sentry_event_add_exception`. -// -function {SENTRY_EXPERIMENTAL_API} sentry_value_new_exception( - const _type: PAnsiChar; - const value: PAnsiChar -): sentry_value_t; cdecl; external sentry_dll delayed; - -// -// Creates a new Thread value. -// -// See https://develop.sentry.dev/sdk/event-payloads/threads/ -// -// The returned value needs to be attached to an event via -// `sentry_event_add_thread`. -// -// `name` can be NULL. -// -function {SENTRY_EXPERIMENTAL_API} sentry_value_new_thread( - id: UInt64; - const name: PAnsiChar -): sentry_value_t; cdecl; external sentry_dll delayed; - -// -// Creates a new Stack Trace conforming to the Stack Trace Interface. -// -// See https://develop.sentry.dev/sdk/event-payloads/stacktrace/ -// -// The returned object needs to be attached to either an exception -// event, or a thread object. -// -// If `ips` is NULL the current stack trace is captured, otherwise `len` -// stack trace instruction pointers are attached to the event. -// -function {SENTRY_EXPERIMENTAL_API} sentry_value_new_stacktrace( - ips: PPVoid; - len: NativeUInt -): sentry_value_t; cdecl; external sentry_dll delayed; - -// -// Adds an Exception to an Event value. -// -// This takes ownership of the `exception`. -// -procedure {SENTRY_EXPERIMENTAL_API} sentry_event_add_exception( - event: sentry_value_t; - exception: sentry_value_t -); cdecl; external sentry_dll delayed; - -// -// Adds a Thread to an Event value. -// -// This takes ownership of the `thread`. -// -procedure {SENTRY_EXPERIMENTAL_API} sentry_event_add_thread( - event: sentry_value_t; - thread: sentry_value_t -); cdecl; external sentry_dll delayed; - +// Creates a new Exception value. +// +// This is intended for capturing language-level exception, such as from a +// try-catch block. `type` and `value` here refer to the exception class and +// a possible description. +// +// See https://develop.sentry.dev/sdk/event-payloads/exception/ +// +// The returned value needs to be attached to an event via +// `sentry_event_add_exception`. +// +function {SENTRY_EXPERIMENTAL_API} sentry_value_new_exception( + const _type: PAnsiChar; + const value: PAnsiChar +): sentry_value_t; cdecl; external sentry_dll delayed; + +// +// Creates a new Thread value. +// +// See https://develop.sentry.dev/sdk/event-payloads/threads/ +// +// The returned value needs to be attached to an event via +// `sentry_event_add_thread`. +// +// `name` can be NULL. +// +function {SENTRY_EXPERIMENTAL_API} sentry_value_new_thread( + id: UInt64; + const name: PAnsiChar +): sentry_value_t; cdecl; external sentry_dll delayed; + +// +// Creates a new Stack Trace conforming to the Stack Trace Interface. +// +// See https://develop.sentry.dev/sdk/event-payloads/stacktrace/ +// +// The returned object needs to be attached to either an exception +// event, or a thread object. +// +// If `ips` is NULL the current stack trace is captured, otherwise `len` +// stack trace instruction pointers are attached to the event. +// +function {SENTRY_EXPERIMENTAL_API} sentry_value_new_stacktrace( + ips: PPVoid; + len: NativeUInt +): sentry_value_t; cdecl; external sentry_dll delayed; + +// +// Sets the Stack Trace conforming to the Stack Trace Interface in a value. +// +// The value argument must be either an exception or thread object. +// +// If `ips` is NULL the current stack trace is captured, otherwise `len` stack +// trace instruction pointers are attached to the event. +// +procedure {SENTRY_EXPERIMENTAL_API} sentry_value_set_stacktrace( + value: sentry_value_t; + ips: PPVoid; + len: NativeUInt +); cdecl; external sentry_dll delayed; + +// +// Adds an Exception to an Event value. +// +// This takes ownership of the `exception`. +// +procedure {SENTRY_EXPERIMENTAL_API} sentry_event_add_exception( + event: sentry_value_t; + exception: sentry_value_t +); cdecl; external sentry_dll delayed; + +// +// Adds a Thread to an Event value. +// +// This takes ownership of the `thread`. +// +procedure {SENTRY_EXPERIMENTAL_API} sentry_event_add_thread( + event: sentry_value_t; + thread: sentry_value_t +); cdecl; external sentry_dll delayed; + // -- Experimental APIs -- // @@ -493,33 +510,35 @@ function sentry_value_to_msgpack( // Adds a stack trace to an event. // // The stack trace is added as part of a new thread object. -// This function is **deprecated** in favor of using -// `sentry_value_new_stacktrace` in combination with `sentry_value_new_thread` -// and `sentry_event_add_thread`. -// -// If `ips` is NULL the current stack trace is captured, otherwise `len` -// stack trace instruction pointers are attached to the event. +// This function is **deprecated** in favor of using +// `sentry_value_new_stacktrace` in combination with `sentry_value_new_thread` +// and `sentry_event_add_thread`. +// +// If `ips` is NULL the current stack trace is captured, otherwise `len` +// stack trace instruction pointers are attached to the event. // procedure sentry_event_value_add_stacktrace( event: sentry_value_t; ips: Pointer; len: Integer - ); cdecl; external sentry_dll delayed; - - // -// This represents the OS dependent user context in the case of a crash, and can -// be used to manually capture a crash. +); cdecl; external sentry_dll delayed; + + + +// +// This represents the OS dependent user context in the case of a crash, and can +// be used to manually capture a crash. // type sentry_ucontext_s = record -{$IF DEFINED(MSWINDOWS)} - exception_ptrs: EXCEPTION_POINTERS; -{$ELSE} - signum: Integer; - siginfo: siginfo_t; +{$IF DEFINED(MSWINDOWS)} + exception_ptrs: EXCEPTION_POINTERS; +{$ELSE} + signum: Integer; + siginfo: siginfo_t; user_context: ucontext_t; -{$ENDIF} +{$ENDIF} end; sentry_ucontext_t = sentry_ucontext_s; @@ -551,9 +570,10 @@ function sentry_unwind_stack_from_ucontext( max_len: size_t ): size_t; cdecl; external sentry_dll delayed; - - - // + + + +// // A UUID // type @@ -613,12 +633,12 @@ procedure sentry_uuid_as_string( type // -// A Sentry Envelope. -// -// The Envelope is an abstract type which represents a payload being sent to -// sentry. It can contain one or more items, typically an Event. -// See https://develop.sentry.dev/sdk/envelopes/ -// +// A Sentry Envelope. +// +// The Envelope is an abstract type which represents a payload being sent to +// sentry. It can contain one or more items, typically an Event. +// See https://develop.sentry.dev/sdk/envelopes/ +// sentry_envelope_s = record end; sentry_envelope_t = sentry_envelope_s; psentry_envelope_t = Pointer; @@ -626,9 +646,9 @@ type // // Frees an envelope. // -procedure sentry_envelope_free( - envelope: sentry_envelope_t -); cdecl; external sentry_dll delayed; +procedure sentry_envelope_free( + envelope: sentry_envelope_t +); cdecl; external sentry_dll delayed; // // Given an envelope returns the embedded event if there is one. @@ -639,6 +659,15 @@ function sentry_envelope_get_event( const envelope: psentry_envelope_t ): sentry_value_t; cdecl; external sentry_dll delayed; +// +// Given an Envelope, returns the embedded Transaction if there is one. +// +// This returns a borrowed value to the Transaction in the Envelope. +// +function {SENTRY_EXPERIMENTAL_API} sentry_envelope_get_transaction( + const envelope: psentry_envelope_t +): sentry_value_t; cdecl; external sentry_dll delayed; + // // Serializes the envelope // @@ -651,10 +680,10 @@ function sentry_envelope_serialize( // // Serializes the envelope into a file. -// -// `path` is assumed to be in platform-specific filesystem path encoding. -// -// Returns 0 on success. +// +// `path` is assumed to be in platform-specific filesystem path encoding. +// +// Returns 0 on success. // function sentry_envelope_write_to_file( const envelope: psentry_envelope_t; @@ -663,8 +692,8 @@ function sentry_envelope_write_to_file( // // The Sentry Client Options. -// -// See https://docs.sentry.io/error-reporting/configuration/ +// +// See https://docs.sentry.io/error-reporting/configuration/ // type sentry_options_s = record end; @@ -672,130 +701,161 @@ type psentry_options_t = ^sentry_options_t; // -// This represents an interface for user-defined transports. -// -// Transports are responsible for sending envelopes to sentry and are the last -// step in the event pipeline. -// -// Envelopes will be submitted to the transport in a _fire and forget_ fashion, -// and the transport must send those envelopes _in order_. -// -// A transport has the following hooks, all of which -// take the user provided `state` as last parameter. The transport state needs -// to be set with `sentry_transport_set_state` and typically holds handles and -// other information that can be reused across requests. -// -// * `send_func`: This function will take ownership of an envelope, and is -// responsible for freeing it via `sentry_envelope_free`. -// * `startup_func`: This hook will be called by sentry inside of `sentry_init` -// and instructs the transport to initialize itself. Failures will bubble up -// to `sentry_init`. -// * `shutdown_func`: Instructs the transport to flush its queue and shut down. -// This hook receives a millisecond-resolution `timeout` parameter and should -// return `true` when the transport was flushed and shut down successfully. -// In case of `false`, sentry will log an error, but continue with freeing the -// transport. -// * `free_func`: Frees the transports `state`. This hook might be called even -// though `shutdown_func` returned `false` previously. -// -// The transport interface might be extended in the future with hooks to flush -// its internal queue without shutting down, and to dump its internal queue to -// disk in case of a hard crash. -// +// This represents an interface for user-defined transports. +// +// Transports are responsible for sending envelopes to sentry and are the last +// step in the event pipeline. +// +// Envelopes will be submitted to the transport in a _fire and forget_ fashion, +// and the transport must send those envelopes _in order_. +// +// A transport has the following hooks, all of which +// take the user provided `state` as last parameter. The transport state needs +// to be set with `sentry_transport_set_state` and typically holds handles and +// other information that can be reused across requests. +// +// * `send_func`: This function will take ownership of an envelope, and is +// responsible for freeing it via `sentry_envelope_free`. +// * `startup_func`: This hook will be called by sentry inside of `sentry_init` +// and instructs the transport to initialize itself. Failures will bubble up +// to `sentry_init`. +// * `shutdown_func`: Instructs the transport to flush its queue and shut down. +// This hook receives a millisecond-resolution `timeout` parameter and should +// return `true` when the transport was flushed and shut down successfully. +// In case of `false`, sentry will log an error, but continue with freeing the +// transport. +// * `free_func`: Frees the transports `state`. This hook might be called even +// though `shutdown_func` returned `false` previously. +// +// The transport interface might be extended in the future with hooks to flush +// its internal queue without shutting down, and to dump its internal queue to +// disk in case of a hard crash. +// type sentry_transport_s = record end; psentry_transport_s = ^sentry_transport_s; sentry_transport_t = sentry_transport_s; - psentry_transport_t = ^sentry_transport_t; - - _sentry_transport_new_func = procedure(e: psentry_envelope_t; state: Pointer); cdecl; - _sentry_transport_free_func = procedure(state: Pointer); cdecl; - _sentry_transport_startup_func = function(const options: psentry_options_t; state: Pointer): Integer; cdecl; - _sentry_transport_shutdown_func = function(timeout: UInt64; state: Pointer): Integer; cdecl; - -// -// Creates a new transport with an initial `send_func`. -// -function sentry_transport_new( - send_func: _sentry_transport_new_func -): psentry_transport_t; cdecl; external sentry_dll delayed; - -// -// Sets the transport `state`. -// -// If the state is owned by the transport and needs to be freed, use -// `sentry_transport_set_free_func` to set an appropriate hook. -// -procedure sentry_transport_set_state( - transport: psentry_transport_t; - state: Pointer -); cdecl; external sentry_dll delayed; - -// -// Sets the transport hook to free the transport `state`. -// -procedure sentry_transport_set_free_func( - transport: psentry_transport_t; - free_func: _sentry_transport_free_func -); cdecl; external sentry_dll delayed; - -// -// Sets the transport startup hook. -// -// This hook is called from within `sentry_init` and will get a reference to the -// options which can be used to initialize a transports internal state. -// It should return `0` on success. A failure will bubble up to `sentry_init`. -// -procedure sentry_transport_set_startup_func( - transport: psentry_transport_t; - startup_func: _sentry_transport_startup_func -); cdecl; external sentry_dll delayed; - -// -// Sets the transport shutdown hook. -// -// This hook will receive a millisecond-resolution timeout. -// It should return `0` on success in case all the pending envelopes have been -// sent within the timeout, or `1` if the timeout was hit. -// -procedure sentry_transport_set_shutdown_func( - transport: psentry_transport_t; - shutdown_func: _sentry_transport_shutdown_func -); cdecl; external sentry_dll delayed; - -// -// Generic way to free a transport. -// -procedure sentry_transport_free( - transport: psentry_transport_t -); cdecl; external sentry_dll delayed; - -// -// Create a new function transport. -// -// It is a convenience function which works with a borrowed `data`, and will -// automatically free the envelope, so the user provided function does not need -// to do that. -// -// This function is *deprecated* and will be removed in a future version. -// It is here for backwards compatibility. Users should migrate to the -// `sentry_transport_new` API. -// -function sentry_new_function_transport( - func: _sentry_transport_new_func; - data: Pointer -): psentry_transport_t; cdecl; external sentry_dll delayed; - + psentry_transport_t = ^sentry_transport_t; + + _sentry_transport_new_func = procedure(e: psentry_envelope_t; state: Pointer); cdecl; + _sentry_transport_free_func = procedure(state: Pointer); cdecl; + _sentry_transport_startup_func = function(const options: psentry_options_t; state: Pointer): Integer; cdecl; + _sentry_transport_shutdown_func = function(timeout: UInt64; state: Pointer): Integer; cdecl; + _sentry_transport_flush_func = function(timeout: UInt64; state: Pointer): Integer; cdecl; + +// +// Creates a new transport with an initial `send_func`. +// +function sentry_transport_new( + send_func: _sentry_transport_new_func +): psentry_transport_t; cdecl; external sentry_dll delayed; + +// +// Sets the transport `state`. +// +// If the state is owned by the transport and needs to be freed, use +// `sentry_transport_set_free_func` to set an appropriate hook. +// +procedure sentry_transport_set_state( + transport: psentry_transport_t; + state: Pointer +); cdecl; external sentry_dll delayed; + +// +// Sets the transport hook to free the transport `state`. +// +procedure sentry_transport_set_free_func( + transport: psentry_transport_t; + free_func: _sentry_transport_free_func +); cdecl; external sentry_dll delayed; + +// +// Sets the transport startup hook. +// +// This hook is called from within `sentry_init` and will get a reference to the +// options which can be used to initialize a transports internal state. +// It should return `0` on success. A failure will bubble up to `sentry_init`. +// +procedure sentry_transport_set_startup_func( + transport: psentry_transport_t; + startup_func: _sentry_transport_startup_func +); cdecl; external sentry_dll delayed; + +// +// Sets the transport flush hook. +// +// This hook will receive a millisecond-resolution timeout. +// It should return `0` if all the pending envelopes are +// sent within the timeout, or `1` if the timeout is hit. +// +procedure {SENTRY_API} sentry_transport_set_flush_func( + transport: psentry_transport_t; + flush_func: _sentry_transport_flush_func +); cdecl; external sentry_dll delayed; + + + +// +// Sets the transport shutdown hook. +// +// This hook will receive a millisecond-resolution timeout. +// It should return `0` on success in case all the pending envelopes have been +// sent within the timeout, or `1` if the timeout was hit. +// +procedure sentry_transport_set_shutdown_func( + transport: psentry_transport_t; + shutdown_func: _sentry_transport_shutdown_func +); cdecl; external sentry_dll delayed; + +// +// Generic way to free a transport. +// +procedure sentry_transport_free( + transport: psentry_transport_t +); cdecl; external sentry_dll delayed; + +// +// Create a new function transport. +// +// It is a convenience function which works with a borrowed `data`, and will +// automatically free the envelope, so the user provided function does not need +// to do that. +// +// This function is *deprecated* and will be removed in a future version. +// It is here for backwards compatibility. Users should migrate to the +// `sentry_transport_new` API. +// +function sentry_new_function_transport( + func: _sentry_transport_new_func; + data: Pointer +): psentry_transport_t; cdecl; external sentry_dll delayed; + +// +// This represents an interface for user-defined backends. +// +// Backends are responsible to handle crashes. They are maintained at runtime +// via various life-cycle hooks from the sentry-core. +// +// At this point none of those interfaces are exposed in the API including +// creation and destruction. The main use-case of the backend in the API at this +// point is to disable it via `sentry_options_set_backend` at runtime before it +// is initialized. +// +type + sentry_backend_s = record end; + sentry_backend_t = sentry_backend_s; + psentry_backend_t = Pointer; + // -- Options APIs -- // -// The state of user consent. -// -type sentry_user_consent_t = ( - SENTRY_USER_CONSENT_UNKNOWN = -1, - SENTRY_USER_CONSENT_GIVEN = 1, - SENTRY_USER_CONSENT_REVOKED = 0 -); +// The state of user consent. +// +type sentry_user_consent_t = ( + SENTRY_USER_CONSENT_UNKNOWN = -1, + SENTRY_USER_CONSENT_GIVEN = 1, + SENTRY_USER_CONSENT_REVOKED = 0 +); // // Creates a new options struct. @@ -819,20 +879,20 @@ procedure sentry_options_set_transport( ); cdecl; external sentry_dll delayed; // -// Type of the `before_send` callback. -// -// The callback takes ownership of the `event`, and should usually return that -// same event. In case the event should be discarded, the callback needs to -// call `sentry_value_decref` on the provided event, and return a -// `sentry_value_new_null()` instead. -// -// This function may be invoked inside of a signal handler and must be safe for -// that purpose, see https://man7.org/linux/man-pages/man7/signal-safety.7.html. -// On Windows, it may be called from inside of a `UnhandledExceptionFilter`, see -// the documentation on SEH (structured exception handling) for more information -// https://docs.microsoft.com/en-us/windows/win32/debug/structured-exception-handling -// -type +// Type of the `before_send` callback. +// +// The callback takes ownership of the `event`, and should usually return that +// same event. In case the event should be discarded, the callback needs to +// call `sentry_value_decref` on the provided event, and return a +// `sentry_value_new_null()` instead. +// +// This function may be invoked inside of a signal handler and must be safe for +// that purpose, see https://man7.org/linux/man-pages/man7/signal-safety.7.html. +// On Windows, it may be called from inside of a `UnhandledExceptionFilter`, see +// the documentation on SEH (structured exception handling) for more information +// https://docs.microsoft.com/en-us/windows/win32/debug/structured-exception-handling +// +type sentry_event_function_t = function( event: sentry_value_t; hint: Pointer; @@ -841,15 +901,80 @@ type // // Sets the `before_send` callback. -// -// See the `sentry_event_function_t` typedef above for more information. -// +// +// See the `sentry_event_function_t` typedef above for more information. +// procedure sentry_options_set_before_send( opts: psentry_options_t; func: sentry_event_function_t; data: Pointer ); cdecl; external sentry_dll delayed; +// +// Type of the `on_crash` callback. +// +// The `on_crash` callback replaces the `before_send` callback for crash events. +// The interface is analogous to `before_send` in that the callback takes +// ownership of the `event`, and should usually return that same event. In case +// the event should be discarded, the callback needs to call +// `sentry_value_decref` on the provided event, and return a +// `sentry_value_new_null()` instead. +// +// Only the `inproc` backend currently fills the passed-in event with useful +// data and processes any modifications to the return value. Since both +// `breakpad` and `crashpad` use minidumps to capture the crash state, the +// passed-in event is empty when using these backends, and they ignore any +// changes to the return value. +// +// If you set this callback in the options, it prevents a concurrently enabled +// `before_send` callback from being invoked in the crash case. This allows for +// better differentiation between crashes and other events and gradual migration +// from existing `before_send` implementations: +// +// - if you have a `before_send` implementation and do not define an `on_crash` +// callback your application will receive both normal and crash events as +// before +// - if you have a `before_send` implementation but only want to handle normal +// events with it, then you can define an `on_crash` callback that returns +// the passed-in event and does nothing else +// - if you are not interested in normal events, but only want to act on +// crashes (within the limits mentioned below), then only define an +// `on_crash` callback with the option to filter (on all backends) or enrich +// (only inproc) the crash event +// +// This function may be invoked inside of a signal handler and must be safe for +// that purpose, see https://man7.org/linux/man-pages/man7/signal-safety.7.html. +// On Windows, it may be called from inside of a `UnhandledExceptionFilter`, see +// the documentation on SEH (structured exception handling) for more information +// https://docs.microsoft.com/en-us/windows/win32/debug/structured-exception-handling +// +// Platform-specific behavior: +// +// - does not work with crashpad on macOS. +// - for breakpad on Linux the `uctx` parameter is always NULL. +// - on Windows the crashpad backend can capture fast-fail crashes which +// by-pass SEH. Since `on_crash` is called by a local exception-handler, it will +// not be invoked when such a crash happened, even though a minidump will be +// sent. +// +type + sentry_crash_function_t = function( + const uctx: psentry_ucontext_t; + event: sentry_value_t; + closure: Pointer + ): sentry_value_t; cdecl; + +// +// Sets the `on_crash` callback. +// +// See the `sentry_crash_function_t` typedef above for more information. +// +procedure {SENTRY_API} sentry_options_set_on_crash( + opts: psentry_options_t; + func: sentry_crash_function_t; + data: Pointer +); cdecl; external sentry_dll delayed; + // // Sets the DSN. // @@ -866,21 +991,21 @@ function sentry_options_get_dsn( ): PAnsiChar; cdecl; external sentry_dll delayed; // -// Sets the sample rate, which should be a double between `0.0` and `1.0`. -// Sentry will randomly discard any event that is captured using -// `sentry_capture_event` when a sample rate < 1 is set. -// -procedure sentry_options_set_sample_rate( - opts: psentry_options_t; - sample_rate: double -); cdecl; external sentry_dll delayed; - -// -// Gets the sample rate. -// -function sentry_options_get_sample_rate( - const opts: psentry_options_t -): double; cdecl; external sentry_dll delayed; +// Sets the sample rate, which should be a double between `0.0` and `1.0`. +// Sentry will randomly discard any event that is captured using +// `sentry_capture_event` when a sample rate < 1 is set. +// +procedure sentry_options_set_sample_rate( + opts: psentry_options_t; + sample_rate: double +); cdecl; external sentry_dll delayed; + +// +// Gets the sample rate. +// +function sentry_options_get_sample_rate( + const opts: psentry_options_t +): double; cdecl; external sentry_dll delayed; // // Sets the release. @@ -961,20 +1086,20 @@ function sentry_options_get_ca_certs( ): PAnsiChar; cdecl; external sentry_dll delayed; // -// Configures the name of the http transport thread. -// -procedure sentry_options_set_transport_thread_name( - opts: psentry_options_t; - const name: PAnsiChar -); cdecl; external sentry_dll delayed; - -// -// Returns the configured http transport thread name. -// -function sentry_options_get_transport_thread_name( - const opts: psentry_options_t -): PAnsiChar; cdecl; external sentry_dll delayed; - +// Configures the name of the http transport thread. +// +procedure sentry_options_set_transport_thread_name( + opts: psentry_options_t; + const name: PAnsiChar +); cdecl; external sentry_dll delayed; + +// +// Returns the configured http transport thread name. +// +function sentry_options_get_transport_thread_name( + const opts: psentry_options_t +): PAnsiChar; cdecl; external sentry_dll delayed; + // // Enables or disables debug printing mode. // @@ -991,111 +1116,111 @@ function sentry_options_get_debug( ): Integer; cdecl; external sentry_dll delayed; // -// Sets the number of breadcrumbs being tracked and attached to events. -// -// Defaults to 100. -// -procedure sentry_options_set_max_breadcrumbs( - opts: psentry_options_t; - max_breadcrumbs: NativeUInt -); cdecl; external sentry_dll delayed; - -// -// Gets the number of breadcrumbs being tracked and attached to events. -// -function sentry_options_get_max_breadcrumbs( - const opts: psentry_options_t -): NativeUInt; cdecl; external sentry_dll delayed; - -// -// Type of the callback for logger function. -// -type - sentry_logger_function_t = procedure( - level: sentry_level_t; - const message: PAnsiChar; - args: va_list; - userdata: Pointer - ); cdecl; - -// -// Sets the sentry-native logger function. -// -// Used for logging debug events when the `debug` option is set to true. -// -procedure sentry_options_set_logger( - opts: psentry_options_t; - func: sentry_logger_function_t; - userdata: Pointer -); cdecl; external sentry_dll delayed; - -// -// Enables or disables automatic session tracking. -// -// Automatic session tracking is enabled by default and is equivalent to calling -// `sentry_start_session` after startup. -// There can only be one running session, and the current session will always be -// closed implicitly by `sentry_close`, when starting a new session with -// `sentry_start_session`, or manually by calling `sentry_end_session`. -// -procedure sentry_options_set_auto_session_tracking( - opts: psentry_options_t; - val: Integer -); cdecl; external sentry_dll delayed; - -// -// Returns true if automatic session tracking is enabled. -// -function sentry_options_get_auto_session_tracking( - const opts: psentry_options_t +// Sets the number of breadcrumbs being tracked and attached to events. +// +// Defaults to 100. +// +procedure sentry_options_set_max_breadcrumbs( + opts: psentry_options_t; + max_breadcrumbs: NativeUInt +); cdecl; external sentry_dll delayed; + +// +// Gets the number of breadcrumbs being tracked and attached to events. +// +function sentry_options_get_max_breadcrumbs( + const opts: psentry_options_t +): NativeUInt; cdecl; external sentry_dll delayed; + +// +// Type of the callback for logger function. +// +type + sentry_logger_function_t = procedure( + level: sentry_level_t; + const message: PAnsiChar; + args: va_list; + userdata: Pointer + ); cdecl; + +// +// Sets the sentry-native logger function. +// +// Used for logging debug events when the `debug` option is set to true. +// +procedure sentry_options_set_logger( + opts: psentry_options_t; + func: sentry_logger_function_t; + userdata: Pointer +); cdecl; external sentry_dll delayed; + +// +// Enables or disables automatic session tracking. +// +// Automatic session tracking is enabled by default and is equivalent to calling +// `sentry_start_session` after startup. +// There can only be one running session, and the current session will always be +// closed implicitly by `sentry_close`, when starting a new session with +// `sentry_start_session`, or manually by calling `sentry_end_session`. +// +procedure sentry_options_set_auto_session_tracking( + opts: psentry_options_t; + val: Integer +); cdecl; external sentry_dll delayed; + +// +// Returns true if automatic session tracking is enabled. +// +function sentry_options_get_auto_session_tracking( + const opts: psentry_options_t ): Integer; cdecl; external sentry_dll delayed; // -// Enables or disabled user consent requirements for uploads. -// -// This disables uploads until the user has given the consent to the SDK. -// Consent itself is given with `sentry_user_consent_give` and -// `sentry_user_consent_revoke`. -// -procedure sentry_options_set_require_user_consent( - opts: psentry_options_t; - val: Integer); cdecl; external sentry_dll delayed; - -// -// Returns true if user consent is required. -// -function sentry_options_get_require_user_consent( - const opts: psentry_options_t -): Integer; cdecl; external sentry_dll delayed; - +// Enables or disabled user consent requirements for uploads. // -// Enables or disables on-device symbolication of stack traces. -// -// This feature can have a performance impact, and is enabled by default on -// Android. It is usually only needed when it is not possible to provide debug -// information files for system libraries which are needed for serverside -// symbolication. -// -procedure sentry_options_set_symbolize_stacktraces( - opts: psentry_options_t; - val: Integer -); cdecl; external sentry_dll delayed; - -// -// Returns true if on-device symbolication of stack traces is enabled. -// -function sentry_options_get_symbolize_stacktraces( - const opts: psentry_options_t -): Integer; cdecl; external sentry_dll delayed; - +// This disables uploads until the user has given the consent to the SDK. +// Consent itself is given with `sentry_user_consent_give` and +// `sentry_user_consent_revoke`. +// +procedure sentry_options_set_require_user_consent( + opts: psentry_options_t; + val: Integer); cdecl; external sentry_dll delayed; + +// +// Returns true if user consent is required. +// +function sentry_options_get_require_user_consent( + const opts: psentry_options_t +): Integer; cdecl; external sentry_dll delayed; + +// +// Enables or disables on-device symbolication of stack traces. +// +// This feature can have a performance impact, and is enabled by default on +// Android. It is usually only needed when it is not possible to provide debug +// information files for system libraries which are needed for serverside +// symbolication. +// +procedure sentry_options_set_symbolize_stacktraces( + opts: psentry_options_t; + val: Integer +); cdecl; external sentry_dll delayed; + +// +// Returns true if on-device symbolication of stack traces is enabled. +// +function sentry_options_get_symbolize_stacktraces( + const opts: psentry_options_t +): Integer; cdecl; external sentry_dll delayed; + // // Adds a new attachment to be sent along. // -// `path` is assumed to be in platform-specific filesystem path encoding. -// API Users on windows are encouraged to use `sentry_options_add_attachmentw` -// instead. -// +// `path` is assumed to be in platform-specific filesystem path encoding. +// API Users on windows are encouraged to use `sentry_options_add_attachmentw` +// instead. +// procedure sentry_options_add_attachment( opts: psentry_options_t; const path: PAnsiChar @@ -1105,15 +1230,15 @@ procedure sentry_options_add_attachment( // Sets the path to the crashpad handler if the crashpad backend is used. // // The path defaults to the `crashpad_handler`/`crashpad_handler.exe` -// executable, depending on platform, which is expected to be present in the -// same directory as the app executable. -// -// It is recommended that library users set an explicit handler path, depending +// executable, depending on platform, which is expected to be present in the +// same directory as the app executable. +// +// It is recommended that library users set an explicit handler path, depending // on the directory/executable structure of their app. // -// `path` is assumed to be in platform-specific filesystem path encoding. -// API Users on windows are encouraged to use `sentry_options_set_handler_pathw` -// instead. +// `path` is assumed to be in platform-specific filesystem path encoding. +// API Users on windows are encouraged to use `sentry_options_set_handler_pathw` +// instead. // procedure sentry_options_set_handler_path( opts: psentry_options_t; @@ -1122,33 +1247,33 @@ procedure sentry_options_set_handler_path( // // Sets the path to the Sentry Database Directory. -// -// Sentry will use this path to persist user consent, sessions, and other -// artifacts in case of a crash. This will also be used by the crashpad backend -// if it is configured. -// -// The directory is used for "cached" data, which needs to persist across -// application restarts to ensure proper flagging of release-health sessions, -// but might otherwise be safely purged regularly. -// -// It is roughly equivalent to the type of `AppData/Local` on Windows and -// `XDG_CACHE_HOME` on Linux, and equivalent runtime directories on other -// platforms. -// -// It is recommended that users set an explicit absolute path, depending -// on their apps runtime directory. The path will be created if it does not -// exist, and will be resolved to an absolute path inside of `sentry_init`. The -// directory should not be shared with other application data/configuration, as -// sentry-native will enumerate and possibly delete files in that directory. An -// example might be `$XDG_CACHE_HOME/your-app/sentry` -// -// If no explicit path it set, sentry-native will default to `.sentry-native` in -// the current working directory, with no specific platform-specific handling. -// -// `path` is assumed to be in platform-specific filesystem path encoding. -// API Users on windows are encouraged to use -// `sentry_options_set_database_pathw` instead. -// +// +// Sentry will use this path to persist user consent, sessions, and other +// artifacts in case of a crash. This will also be used by the crashpad backend +// if it is configured. +// +// The directory is used for "cached" data, which needs to persist across +// application restarts to ensure proper flagging of release-health sessions, +// but might otherwise be safely purged regularly. +// +// It is roughly equivalent to the type of `AppData/Local` on Windows and +// `XDG_CACHE_HOME` on Linux, and equivalent runtime directories on other +// platforms. +// +// It is recommended that users set an explicit absolute path, depending +// on their apps runtime directory. The path will be created if it does not +// exist, and will be resolved to an absolute path inside of `sentry_init`. The +// directory should not be shared with other application data/configuration, as +// sentry-native will enumerate and possibly delete files in that directory. An +// example might be `$XDG_CACHE_HOME/your-app/sentry` +// +// If no explicit path it set, sentry-native will default to `.sentry-native` in +// the current working directory, with no specific platform-specific handling. +// +// `path` is assumed to be in platform-specific filesystem path encoding. +// API Users on windows are encouraged to use +// `sentry_options_set_database_pathw` instead. +// procedure sentry_options_set_database_path( opts: psentry_options_t; const path: PAnsiChar @@ -1193,6 +1318,37 @@ procedure sentry_options_set_system_crash_reporter_enabled( enabled: Integer ); cdecl; external sentry_dll delayed; +// +// Sets the maximum time (in milliseconds) to wait for the asynchronous tasks to +// end on shutdown, before attempting a forced termination. +// +procedure {SENTRY_API} sentry_options_set_shutdown_timeout( + opts: psentry_options_t; + shutdown_timeout: UInt64 +); cdecl; external sentry_dll delayed; + +// +// Gets the maximum time (in milliseconds) to wait for the asynchronous tasks to +// end on shutdown, before attempting a forced termination. +// +function {SENTRY_API} sentry_options_get_shutdown_timeout( + opts: psentry_options_t +): UInt64; cdecl; external sentry_dll delayed; + +// +// Sets a user-defined backend. +// +// Since creation and destruction of backends is not exposed in the API, this +// can only be used to set the backend to `NULL`, which disables the backend in +// the initialization. +// +procedure {SENTRY_API} sentry_options_set_backend( + opts: psentry_options_t; + backend: psentry_backend_t +); cdecl; external sentry_dll delayed; + + + // -- Global APIs -- // @@ -1201,33 +1357,45 @@ procedure sentry_options_set_system_crash_reporter_enabled( // This takes ownership of the options. After the options have been set they // cannot be modified any more. // Depending on the configured transport and backend, this function might not be -// fully thread-safe. -// Returns 0 on success. +// fully thread-safe. +// Returns 0 on success. // function sentry_init( options: psentry_options_t ): Integer; cdecl; external sentry_dll delayed; +// +// Instructs the transport to flush its send queue. +// +// The `timeout` parameter is in milliseconds. +// +// Returns 0 on success, or a non-zero return value in case the timeout is hit. +// +function {SENTRY_API} sentry_flush( + timeout: UInt64 +): Integer; cdecl; external sentry_dll delayed; + + // // Shuts down the sentry client and forces transports to flush out. // -// Returns 0 on success. -// -function sentry_close: Integer; cdecl; external sentry_dll delayed; - -// -// Shuts down the sentry client and forces transports to flush out. -// -// This is a **deprecated** alias for `sentry_close`. -// -// Returns 0 on success. -// -function sentry_shutdown: Integer; cdecl; external sentry_dll delayed; - -// -// This will lazily load and cache a list of all the loaded libraries. -// -// Returns a new reference to an immutable, frozen list. +// Returns 0 on success. +// +function sentry_close: Integer; cdecl; external sentry_dll delayed; + +// +// Shuts down the sentry client and forces transports to flush out. +// +// This is a **deprecated** alias for `sentry_close`. +// +// Returns 0 on success. +// +function sentry_shutdown: Integer; cdecl; external sentry_dll delayed; + +// +// This will lazily load and cache a list of all the loaded libraries. +// +// Returns a new reference to an immutable, frozen list. // The reference must be released with `sentry_value_decref`. // function sentry_get_modules_list: sentry_value_t; cdecl; external sentry_dll delayed; @@ -1236,43 +1404,43 @@ function sentry_get_modules_list: sentry_value_t; cdecl; external sentry_dll de // Clears the internal module cache. // // For performance reasons, sentry will cache the list of loaded libraries when -// capturing events. This cache can get out-of-date when loading or unloading -// libraries at runtime. It is therefore recommended to call -// `sentry_clear_modulecache` when doing so, to make sure that the next call to +// capturing events. This cache can get out-of-date when loading or unloading +// libraries at runtime. It is therefore recommended to call +// `sentry_clear_modulecache` when doing so, to make sure that the next call to // `sentry_capture_event` will have an up-to-date module list. // procedure sentry_clear_modulecache; cdecl; external sentry_dll delayed; // // Re-initializes the Sentry backend. -// -// This is needed if a third-party library overrides the previously installed -// signal handler. Calling this function can be potentially dangerous and should -// only be done when necessary. -// -// Returns 0 on success. -// +// +// This is needed if a third-party library overrides the previously installed +// signal handler. Calling this function can be potentially dangerous and should +// only be done when necessary. +// +// Returns 0 on success. +// function sentry_reinstall_backend: Integer; cdecl; external sentry_dll delayed; // -// Gives user consent. -// -procedure sentry_user_consent_give; external sentry_dll delayed; - -// -// Revokes user consent. -// -procedure sentry_user_consent_revoke; external sentry_dll delayed; - -// -// Resets the user consent (back to unknown). -// -procedure sentry_user_consent_reset; external sentry_dll delayed; - -// -// Checks the current state of user consent. -// -function sentry_user_consent_get: sentry_user_consent_t; external sentry_dll delayed; +// Gives user consent. +// +procedure sentry_user_consent_give; external sentry_dll delayed; + +// +// Revokes user consent. +// +procedure sentry_user_consent_revoke; external sentry_dll delayed; + +// +// Resets the user consent (back to unknown). +// +procedure sentry_user_consent_reset; external sentry_dll delayed; + +// +// Checks the current state of user consent. +// +function sentry_user_consent_get: sentry_user_consent_t; external sentry_dll delayed; // // Sends a sentry event. @@ -1282,14 +1450,14 @@ function sentry_capture_event( ): sentry_uuid_t; cdecl; external sentry_dll delayed; // -// Captures an exception to be handled by the backend. -// -// This is safe to be called from a crashing thread and may not return. -// -procedure sentry_handle_exception( - const uctx: psentry_ucontext_t -); cdecl; external sentry_dll delayed; - +// Captures an exception to be handled by the backend. +// +// This is safe to be called from a crashing thread and may not return. +// +procedure sentry_handle_exception( + const uctx: psentry_ucontext_t +); cdecl; external sentry_dll delayed; + // // Adds the breadcrumb to be sent in case of an event. // @@ -1357,8 +1525,8 @@ procedure sentry_remove_context( // // Sets the event fingerprint. // -// This accepts a variable number of arguments, and needs to be terminated by a -// trailing `NULL`. +// This accepts a variable number of arguments, and needs to be terminated by a +// trailing `NULL`. // procedure sentry_set_fingerprint( const fingerprint: PAnsiChar @@ -1389,36 +1557,43 @@ procedure sentry_set_level( level: sentry_level_t ); cdecl; external sentry_dll delayed; - // -// Starts a new session. -// -procedure sentry_start_session; cdecl; external sentry_dll delayed; - -// -// Ends a session. -// -procedure sentry_end_session; cdecl; external sentry_dll delayed; - // - // Sets the path to sentry.dll; this must - // be called before any other sentry apis - // - procedure sentry_set_library_path(const path: string); - - implementation - -uses - System.SysUtils; - -procedure sentry_set_library_path(const path: string); -begin - if LoadLibrary(PChar(path)) = 0 then - RaiseLastOSError; -end; - -procedure sentry_string_free(str: PAnsiChar); cdecl; -begin - sentry_free(str); -end; - -end. +// +// Starts a new session. +// +procedure sentry_start_session; cdecl; external sentry_dll delayed; + +// +// Ends a session. +// +procedure sentry_end_session; cdecl; external sentry_dll delayed; + + +// + +// Sets the path to sentry.dll; this must + +// be called before any other sentry apis + +// + +procedure sentry_set_library_path(const path: string); + + +implementation + +uses + System.SysUtils; + +procedure sentry_set_library_path(const path: string); +begin + if LoadLibrary(PChar(path)) = 0 then + RaiseLastOSError; +end; + +procedure sentry_string_free(str: PAnsiChar); cdecl; +begin + sentry_free(str); +end; + +end. diff --git a/common/windows/delphi/ext/sentry/sentry.x64.dll b/common/windows/delphi/ext/sentry/sentry.x64.dll index 9737a5acc0..5587ebaa0c 100644 Binary files a/common/windows/delphi/ext/sentry/sentry.x64.dll and b/common/windows/delphi/ext/sentry/sentry.x64.dll differ diff --git a/common/windows/delphi/ext/sentry/sentry.x64.lib b/common/windows/delphi/ext/sentry/sentry.x64.lib index 1a9f57d57c..31fe092754 100644 Binary files a/common/windows/delphi/ext/sentry/sentry.x64.lib and b/common/windows/delphi/ext/sentry/sentry.x64.lib differ diff --git a/common/windows/delphi/ext/sentry/test/Sentry.Client.Test.SentryClientTestMain.pas b/common/windows/delphi/ext/sentry/test/Sentry.Client.Test.SentryClientTestMain.pas index c9f33f6533..fe987fea4b 100644 --- a/common/windows/delphi/ext/sentry/test/Sentry.Client.Test.SentryClientTestMain.pas +++ b/common/windows/delphi/ext/sentry/test/Sentry.Client.Test.SentryClientTestMain.pas @@ -29,7 +29,7 @@ begin //o.DSN := 'https://7b1ff1dae2c8495b84f90dadcf512b84@sentry.io/4853461'; o.Release := 'keyman-14.0.22-alpha-local'; o.HandlerPath := 'c:\Projects\keyman\app\windows\src\ext\sentry\test\Win32\Release\crashpad_handler.exe'; - o.DatabasePath := '.\sentry-0.4.9-db'; + o.DatabasePath := '.\sentry-0.6.0-db'; Result := TSentryClient.Create(o); end; diff --git a/common/windows/delphi/general/Keyman.System.KeymanSentryClient.pas b/common/windows/delphi/general/Keyman.System.KeymanSentryClient.pas index 5504f66f9e..1a71649727 100644 --- a/common/windows/delphi/general/Keyman.System.KeymanSentryClient.pas +++ b/common/windows/delphi/general/Keyman.System.KeymanSentryClient.pas @@ -375,7 +375,7 @@ begin end; o.HandlerPath := ExtractFilePath(path) + 'crashpad_handler.exe'; - o.DatabasePath := TKeymanPaths.ErrorLogPath + 'sentry-0.4.9-db'; + o.DatabasePath := TKeymanPaths.ErrorLogPath + 'sentry-0.6.0-db'; FClient := SentryClientClass.Create(o, ALogger, f); FClient.OnAfterEvent := ClientAfterEvent; diff --git a/developer/src/inst/kmdev.wxs b/developer/src/inst/kmdev.wxs index 0847b93cc9..cd91f84f38 100644 --- a/developer/src/inst/kmdev.wxs +++ b/developer/src/inst/kmdev.wxs @@ -55,7 +55,7 @@ - + @@ -211,7 +211,7 @@ - + diff --git a/windows/src/desktop/inst/keymandesktop.wxs b/windows/src/desktop/inst/keymandesktop.wxs index be5f410504..b78ff8c422 100644 --- a/windows/src/desktop/inst/keymandesktop.wxs +++ b/windows/src/desktop/inst/keymandesktop.wxs @@ -202,7 +202,7 @@ - + @@ -223,7 +223,7 @@ - + diff --git a/windows/src/engine/inst/components.wxs b/windows/src/engine/inst/components.wxs index 27824789e3..2f6072c30d 100644 --- a/windows/src/engine/inst/components.wxs +++ b/windows/src/engine/inst/components.wxs @@ -243,7 +243,7 @@ - + diff --git a/windows/src/engine/inst/keymanengine.wxs b/windows/src/engine/inst/keymanengine.wxs index 999beaf6ce..255f1ff903 100644 --- a/windows/src/engine/inst/keymanengine.wxs +++ b/windows/src/engine/inst/keymanengine.wxs @@ -13,7 +13,7 @@ - +