The SDK development

  1. Sentry 20. X JS-SDK Design Art
  2. Sentry 20. X JS-SDK Design Art (Development Basics)
  3. Sentry 20.x JS-SDK Design Art

A series of

  1. Snuba: Sentry’s new search infrastructure (based on ClickHouse)
  2. Sentry 10 K8S cloud native architecture exploration, fast access to Vue App in 1 minute
  3. Sentry(V20.x) play forward/back end monitoring and event log big data analysis, deployed to K8S cluster using Helm
  4. Sentry(v20.x) JavaScript SDK three ways to install and load
  5. Sentry(v20.x) JavaScript SDK configuration details
  6. Sentry(v20.x) JavaScript SDK manually captures the basic usage of events
  7. Sentry(v20.x) JavaScript SDK Source Maps
  8. Sentry(v20.x) JavaScript SDK troubleshooting
  9. Sentry(V20.x) JavaScript SDK 1 minute overhand Performance monitor
  10. Sentry(v20.x) JavaScript SDK Performance monitoring management Transactions
  11. Sentry(v20.x) sampling Transactions for JavaScript SDK Performance monitoring
  12. Sentry(V20.x) JavaScript SDK Enriching event information
  13. Sentry(v20.x) JavaScript SDK Data Management

A unified API

The new Sentry SDK should follow the Unified API and use consistent terminology to refer to concepts. This document explains what the Unified API is and why it exists.

motivation

Sentry has a variety of SDKS that have been developed over the years by different developers with different ideas. This leads to different feature sets for different SDKS, using different concepts and terminology, which leads to often unclear how to implement the same things on different platforms.

In addition, these SDKS are entirely centered on error reporting via Explicit Clients, which means that certain integrations (such as breadcrumbs) are often not possible.

General guidelines

  • We hope that allSDK APIUnified language/wording to aid support and documentation, and to make it easier for users to use in different environmentsSentry.
  • In the designSDKInstead of just incident reporting (transactions.APM, etc.).
  • The design is identicalclientThe instanceSDK, we can either work naturally in the runtime environment through dependency injection, etc., or dispatch to existing ones using implicit contextsclients 和 scopesTo hook into most environments. This is important because it allows events to include other integrated data in the process.
  • Common tasks must be simple and clear.
  • To help third-party libraries, the “non-configured Sentry” condition needs to be handled quickly (and executed late).
  • generalAPIRequirements make sense in most languages, and must not depend on super-special constructs. To make it more natural, we should consider language details and explicitly support them as alternatives (disposables.stack guards, etc.).

Simplified diagram

The term

  • minimal: a single one"Facade"Package, which passes through the interface (interfaces) or agent (proxies) reexportSDKSubset of functionality. The package does not directly depend onSDK, conversely, if there is no installationSDK, it should make every operation becomenoop. The purpose of such a package is to allowrandomLibraries record breadcrumbs and set context data without dependenciesSDK.
  • hub: Objects in the managed state. Implicit can be used by defaultglobal thread localOr similarhub.HubsIt can be created manually.
  • scope:scopeContains what should beSentryEvent a data sent implicitly. It can hold context data, extra parameters, level overrides, fingerprints, and more.
  • client:clientIs a once-configured object that can be bound tohub. The user can then discover it automaticallyclientAnd dispatches calls to it. Users usually do not need to communicate directly withclientTo deal with. They either pass throughhubAchieve, or passstatic convenience functionsThe implementation.clientMainly responsible for buildingSentryEvent and send it totransport.
  • client options: is a language – and runtime – specific parameter for configurationclient. This can berelease 和 environmentCan also be configuredintegrations.in-app worksAnd so on.
  • context:Contexts 为 SentryProvide additional data. Have a particular context (userAnd the like) and common contexts (Runtime, OS, Device), and so on. Check for valid keysContexts. Note: in the oldSDKIn, you may encounter a context-free concept that is now scoped deprecated.
  • tags:TagsIt could be anythingstring→ Can search for eventsstring pairs.ContextsIs converted totags.
  • extra:client usersAppend truly arbitrary data. This is a deprecated feature, but will continue to be supported for the foreseeable future. Users are encouraged to use context instead.
  • transport:transportIs the internal construct of the client that abstracts the sending of events. In general,transportRuns in a separate thread and gets events sent through a queue.transportResponsible for sending (sending), retry (retrying) and processing rate limits (handling rate limits). If needed,transportIt is also possible to persist unsent events during a restart.
  • integration: To a specific framework (frameworks) or environment (environments) provides middleware (middlewares), binding (bindings) or hook (hooks), and the code to insert these bindings and activate them. The use of integration does not follow the common interface.
  • event processors: callbacks run for each event (Callbacks). They can modify and return events, or they can benull. returnnullThe event is discarded and will not be processed further. For more information, see Event Pipeline (Event Pipeline).
  • disabled SDK: most of theSDKFunctionality depends on what has been configuredactive client. When you havetransport“, Sentry arguesclient 是 active. Otherwise, the client isinactiveThe,SDKIs considered to be"Disabled". In this case, some callback functions, such asconfigure_scopeOr event handlers (event processors), may not be called. Therefore, the crumbs (breadcrumbs) will not be recorded.

“Static API”

Static API functions are the most common user-facing API. Users simply need to import these functions to start issuing events to Sentry or configuring scopes. These shortcut functions should be exported in the top-level namespace of the package. They use hubs and scopes in the background (see Concurrency for more information) (if available on that platform). Note that most of the functions listed below are aliases for Hub::get_current().function.

  • init(options): This is everySDKThe entry point of.

Often, this creates/reinitializes a global hub that propagates to all new threads/execution contexts, Or create a hub for each thread/execution context.

Take options (DSN, etc.), configure the client and bind it to the current hub or initialize it. A STAND-IN should be returned, which can be used for drain Events (one-time).

This may return a handle or guard to handle. How you achieve this is entirely up to the SDK. This might even be a client, if that makes sense for the SDK. In Rust, it is a ClientInitGuard, and in JavaScript, it can be a helper object with a waiting close method.

You should be able to call this method multiple times, and a second call can either dismantle the previous client, reduce the reference count of the previous client, and so on.

Multiple calls can only be used for testing. If you call init at any time other than application startup, it will be undefined.

The user must call init once, but is allowed to make calls using the disabled DSN. For example, there may be no parameter passing.

In addition, it sets up all the default integrations.

  • capture_event(event): Takes an already composed event and dispatches it to the center of the current activity. Event objects can be normal dictionaries or typed objects, whichever makes more sense in the SDK. It should follow native protocols wherever possible, ignoring platform-specific renaming (case styles, etc.).
  • capture_exception(error)Report:error 或 exceptionObject. Depending on the platform, there may be different parameters. The most obvious version accepts only oneerrorObject, but not passed inerrorAnd use the currentexceptionIs also subject to change.
  • capture_message(message, level)Report:message. The level can be an optional language default parameter, in which case it should default toinfo.
  • add_breadcrumb(crumb)To:scopeAdd new bread crumbs. If the total number of crumbs exceedsmax_breadcrumbsSetting,SDKThe oldest crumbs should be removed. This has to do withHub APIWorks in a similar way. If it’s disabledSDKIt should be ignoredbreadcrumb.
  • configure_scope(callback): Can be reconfiguredscopeObject to call back. This is used to attach context data to future events in the same scope.
  • last_event_id(): Should return the last event emitted by the current scopeID. For example, this is used to implement a user feedback dialog (feedback).

concurrent

All SDKS should have the concept of concurrency Safe Context Storage. What this means depends on the language. The basic idea is that a user of the SDK can call a method to securely provide additional context information for all events that are about to be logged.

In most languages, this is implemented as thread Local Stack, but in some languages (such as JavaScript), it can be global because it is assumed that this makes sense in the environment.

Here are some common concurrency patterns:

  • Thread bound hub: In this mode, eachthreadThey have their own"Hub"thehubInternally manage a series of scopesscopes. If the pattern is followed, onethread(callinit()The thread) will become"The main hubthehubWill be used as the base for the newly generated thread that will get based on the masterhub 的 hub(but independent).
  • Internally scoped hub: On some platforms, such as.NET ambient dataIs available in this caseHubScopes can be managed internallyscopes.
  • Dummy hubOn some platforms, concurrencyconcurrencyIt doesn’t exist. In this case,hubIt may not exist at all, or it may just be one without concurrency managementconcurrency managementThe singleton.

Hub

Normally, a hub consists of a bunch of Clients and scopes.

The SDK maintains two variables: Main hub (a global variable) and current hub (a local variable of the current thread theAD or executing the context execution context, sometimes called asynchronous local async local or context-local context local variable)

  • Hub::new(client, scope): uses the givenclient 和 scopeCreate a new onehub.clientCan be found inhubsReuse between.scopeShould belong tohubAll (if necessary, please proceedclone)
  • Hub::new_from_top(hub)/ or the native constructor is overloadednative constructor overloads: By cloning anotherhubThe top stack oftop stackTo create a newhub.
  • get_current_hub() / Hub::current() / Hub::get_current(): global function or static function to return the current (thread’s)hub.
  • get_main_hub() / Hub::main() / Hub::get_main(): in the main threadmain threadIs in a particular language ("Thread bound hub"Model), which returnsmain threadInstead of the current threadcurrent threadIn the center. This may not be true in all languages.
  • Hub::capture_event / Hub::capture_message / Hub::capture_exceptionCapture:message / exception 到 capture event.capture_eventWill pass theevent 与 scopeData is merged and dispatched toclient. As an additional argument, it also needs a hint. The relevanthintFor details, seehints.
  • Hub::push_scope(): pushes a new scope layer that inherits the previous datanew scope layer. This should return meaningful languagedisposable 或 stack guard. When using “Inner scope center”internally scoped hubIn concurrent models, you usually need to make this call, or you might accidentally misshare the scope.
  • Hub::with_scope(callback)(optional) :PythonIn, this could be a context manager; inRubyIn, this could be a block function. Push and pop integration to workscope.
  • Hub::pop_scope(callback)(optional) : Only exists without better resource managementresource managementIn the language of. In the bestpush_scopeUse this function on the return value of thewith_scope. This is sometimes calledpop_scope_unsafeTo indicate that the method should not be used directly.
  • Hub::configure_scope(callback): invokes the callback using a mutable reference to the modified scope. This can also be a language with it (Python) in thewithStatements. If there is noactive clientBound to thehub,SDKCallbacks should not be invoked.
  • Hub::add_breadcrumb(crumb, hint): adds the breadcrumbs to the current scope.
    • The supported parameters are as follows:
      • Function to create bread crumbs
      • The breadcrumb object that has been created
      • Breadcrumb list (optional)
    • In languages without a basic overload form, there are only primitive breadcrumb objectsraw breadcrumb objectShould be accepted.
    • If there is noactive clientBound to thehub,SDKBreadcrumbs should be ignored.
    • The relevanthintFor details, seehints.
  • Hub::client() / Hub::get_client()(optional) : Returns the currentclient 或 None 的 Accessor 或 getter.
  • Hub::bind_client(new_client): will be differentclientBound to thehub. ifhubIs alsoinitTo create theclientThe owner, then ifhubIs the object responsible for processing it, and a reference to it needs to be preserved.
  • Hub::unbind_client()(optional) :bind_clientOptional unbinding method for languages that do not accept null values.
  • Hub::last_event_id(): should return currentscopeThe last one sent outevent ID. For example, this is used to implement user feedback dialogsfeedback dialogs.
  • Hub::run(hub, callback) hub.run(callback), run_in_hub(hub, callback)(optional) : Run willhubBind to currenthubThe callback.

Scope

Scope contains the data that should be sent implicitly with the Sentry event. It can save context data, extra parameters, level overrides, fingerprints, etc.

Users can modify the current scope (setting extra, tag, current user) by using the global function configure_scope. Configure_scope accepts a callback function and passes the current scope to it.

The reason for using this callback-based API is efficiency. If the SDK is disabled, it should not call the callback function to avoid unnecessary work.

Sentry.configureScope(scope= >
  scope.setExtra("character_name"."Mighty Fighter"));
Copy the code
  • scope.set_user(user): Shallow merge userShallow mergesConfigure (emailemailThe user nameusername, etc.). Deleting user data is defined by the SDK and can be usedremove_userFunction, or pass no data at all.
  • scope.set_extra(key, value): Sets the additional key to any value, overwriting the potential previous value. deletekey 是 SDKDefined, can be usedremove_extraFunction or do not pass any data as data. This is not a recommended feature and users should be encouraged to switch to context.
  • scope.set_extras(extras): Sets a havekey/valueYes, convenience objects, not multiple objectsset_extraThe call. withset_extraAgain, this is considered a deprecated feature.
  • scope.set_tag(key, value)Will:tagSet to a string value that overrides potential previous values. deletekey 是 SDKDefined, can be usedremove_tagFunction or do not pass any data as data.
  • scope.set_tags(tags): Sets a havekey/valueYes, convenience objects, not multiple objectsset_tagThe call.
  • scope.set_context(key, value): Sets the context key to a value, overwriting a potential previous value. deletekey 是 SDKDefined, can be usedremove_contextFunction or do not pass any data as data. These types aresdkThe specified.
  • scope.set_level(level): Set herescopeThe level of all events sent within.
  • scope.set_transaction(transaction_name): Set currenttransactionThe name of the.
  • scope.set_fingerprint(fingerprint[]): Sets the fingerprint to group specific events together.
  • scope.add_event_processor(processor): Registers event handler functionsevent processor. It accepts an event and returns a new event, or returnsNoneTo delete it. This is the basis of many integrations.
  • scope.add_error_processor(processor)(optional) : Registers error handler functions. It takes an event and exception object and returns a new event or"None"Delete it. This can be used fromSDKOther information is extracted from an exception object that cannot extract itself.
  • scope.clear()Will:scopeReset to the default, while preserving all registered event handlersevent processors. This does not affect the child or parent scope.
  • scope.add_breadcrumb(breadcrumb): Adds the breadcrumbs to the currentscope.
  • scope.clear_breadcrumbs()From:scopeDelete the current breadcrumbs from thebreadcrumbs.
  • scope.apply_to_event(event[, max_breadcrumbs])Will:scopeData is applied to the given event object. This also applies to internal storage inscopeEvent handlers inevent processors. Some implementations may want to set the maximum breadcrumb count here.

Client

The Client is the part of the SDK responsible for event creation. For example, the Client should convert an exception to a Sentry Event. The Client is supposed to be stateless, injecting the scope and delegating the work of sending events to Transport.

  • Client::from_config(config)(or plain old constructors) this usually takes a stringoptions + dsnThe object.
  • Client::capture_event(event, scope): By combining events with other data (clientDefault) to capture events. In addition, if thescopeWhen passed to the system, data from that range is passed internallytransport.
  • Client::close(timeout): Flushs the queue until timeout seconds. This approach is preferred if the client can guarantee that the delivery of the event lasts only up to the current point in time. This may block because of timeout seconds. In the callcloseAfter that, the client should be disabled or destroyed.
  • Client::flush(timeout)And:closeThe difference is the same as when the client is callingflushWill not be released.

Hints

(Optional) Additional arguments to support event capture and breadcrumb addition: Hint.

Hint is SDK-specific, but provides high-level information about the origin of the event. For example, if an exception is caught, the prompt may carry the original exception object. Not all SDKS are required to provide this functionality. However, this parameter is reserved for this purpose.

Event Pipeline

Capture_event captured events are processed in the following order.

Note: Events can be dropped at any stage, at which point no further processing occurs.

  1. If you disableSDK.SentryThe event is immediately discarded.
  2. The client samples events based on the configured sampling rate. Events can be discarded randomly based on the sampling rate.
  3. useapply_to_eventApply the scope. Invoke the scoped event handlers in sequence.
  4. Sentrycallbefore-sendHook.
  5. SentryPasses events to configuredtransport. If the transmission is not validDSN, the event can be discarded. Its internal queue is full; Or due to rate limits required by the server.

Options

Many options are standardized across SDKS. For a list of these options, see the Main Options Documentation.

I am weishao wechat: uuhells123 public number: hackers afternoon tea add my wechat (mutual learning exchange), pay attention to the public number (for more learning materials ~)Copy the code