lisp-sentry

System Information

Definition Index

• LISP-SENTRY

  NOTE: this software is of alpha quality, and the API is subject to change.

  lisp-sentry is a full-featured Common Lisp client library for Sentry, specifically designed to properly function in dumped Lisp images.

  Sentry is application monitoring software which helps developers diagnose, fix, and optimize the performance of their code.

  The key entrypoint of this library is WITH-SENTRY macro, which initializes library settings and runs given body of code within HANDLER-BIND which catches unhandled conditions and sends information on those to Sentry; this is called capturing in Sentry argot.

  You can also initialize settings by calling INIT! and handle conditions manually, setting *EXCEPTION-HANDLED* and capturing them with MAYBE-CAPTURE-CONDITION.

  There's also lower-level API that allows to manually create event envelope by MAKE-ENVELOPE, add the event with MAKE-CONDITION-EVENT or even MAKE-MESSAGE-EVENT and capture it by calling CAPTURE.

  Another extension point of the library is *PROCESS-BEFORE-SEND* callback where you can modify the envelope to be sent, by e.g. adding file attachments via MAKE-ATTACHMENT or user comments via MAKE-USER-REPORT.

  The most important setting is *DSN*, which controls the Sentry instance that'll receive the reports sent by the library. If not set in code, the WITH-SENTRY macro will try to use SENTRY_DSN environment variable. If DSN is unset, the library will silently discard the captured data.

  By default, the library does not capture conditions from interactive sessions. To do so, set *CAPTURE-CONDITIONS-OUTSIDE-DUMPED-IMAGE* to T.

  • EXTERNAL SPECIAL-VARIABLE

    *APP-BUILD*

    Source

    Default internal build identifier, as it appears on the platform.

  • EXTERNAL SPECIAL-VARIABLE

    *APP-NAME*

    Source

    Default human readable application name, as it appears on the platform.

  • EXTERNAL SPECIAL-VARIABLE

    *APP-VERSION*

    Source

    Default human readable application version, as it appears on the platform.

  • EXTERNAL SPECIAL-VARIABLE

    *BUILD-TYPE*

    Source

    Default string identifying the kind of build. For example, testflight.

  • EXTERNAL SPECIAL-VARIABLE

    *CAPTURE-CONDITIONS-OUTSIDE-DUMPED-IMAGE*

    Source

    Whether to CAPTURE conditions outside of circumstances of dumped Lisp image, e.g. when running the code via LOAD, in interactive REPL session or Sly/Slime. Defaults to NIL.

  • EXTERNAL SPECIAL-VARIABLE

    *DIST*

    Source

    The distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. Defaults to NIL.

  • EXTERNAL SPECIAL-VARIABLE

    *DSN*

    Source

    Sentry DSN string. If that variable is unset, the SDK will just not send any events.

  • EXTERNAL SPECIAL-VARIABLE

    *ENVIRONMENT*

    Source

    The environment name, such as production or staging. Defaults to production.

  • EXTERNAL SPECIAL-VARIABLE

    *EXCEPTION-HANDLED*

    Source

    A global boolean flag indicating whether the currently processed condition was handled. Defaults to NIL.

  • EXTERNAL SPECIAL-VARIABLE

    *PROCESS-BEFORE-SEND*

    Source

    Designator of function of one argument. The function receives the ENVELOPE object right before it is sent to Sentry. NOTE: the return value of the function is passed instead of original envelope to CAPTURE. If the function returns NIL, nothing gets sent.

    Defaults to IDENTITY.

  • EXTERNAL SPECIAL-VARIABLE

    *PROJECT-PACKAGE*

    Source

    Name of the project package. Used to determine whether the stack frame is related to the app. Defaults to NIL.

  • EXTERNAL SPECIAL-VARIABLE

    *PROJECT-ROOT*

    Source

    Absolute path to the project directory. Defaults to NIL.

  • EXTERNAL SPECIAL-VARIABLE

    *RELEASE*

    Source

    The release version of the application. Release versions must be unique across all projects in your organization. This value can be the git SHA for the given project, or a product identifier with a semantic version (suggested format my-project-name@1.0.0). Defaults to NIL.

  • EXTERNAL SPECIAL-VARIABLE

    *SERVER-NAME*

    Source

    Name of the device, typically a hostname. Defaults to NIL.

  • EXTERNAL SPECIAL-VARIABLE

    *SOURCES*

    Source

    To display source code in Sentry stack traces, the source code should be saved somewhere, since the dumped Lisp image most probably wouldn't run on the same machine it was built on. This variable holds source files saved on build time.

    See MAKE-SAVED-SOURCES

  • EXTERNAL SPECIAL-VARIABLE

    *STARTUP-TIME*

    Source

    Timestamp when the user started the application.

  • EXTERNAL SPECIAL-VARIABLE

    *VARIABLE-ELISION-LENGTH*

    Source

    If set to non-NIL, limits the length of variable values displayed in Sentry stack traces. Emacs Sly's default is 200 which is reasonable value. Defaults to NIL.

  • EXTERNAL STRUCTURE

    APP-CONTEXT

    Source

    App context describes the application. As opposed to the runtime, this is the actual application that was running and carries metadata about the current session.

    See MAKE-APP-CONTEXT

  • EXTERNAL STRUCTURE

    ATTACHMENT

    Source

    Attachment Item contains a raw payload of an attachment file. It is always associated to an event or transaction.

    See MAKE-ATTACHMENT

  • EXTERNAL STRUCTURE

    BREADCRUMB

    Source

    Sentry uses breadcrumbs to create a trail of events that happened prior to an issue. These events are very similar to traditional logs but can record more rich structured data.

    See MAKE-BREADCRUMB, ADD-BREADCRUMBS

  • EXTERNAL STRUCTURE

    BREADCRUMBS-INTERFACE

    Source

    Breadcrumbs event interface.

    See MAKE-BREADCRUMBS-INTERFACE, BREADCRUMB

  • EXTERNAL STRUCTURE

    CONTEXTS-INTERFACE

    Source

    The Contexts Interface provides additional context data. Typically, this is data related to the current user and the environment. For example, the device or application version.

    See MAKE-CONTEXTS-INTERFACE, ADD-CONTEXT, ADD-CONTEXTS, MAKE-DEFAULT-CONTEXTS

  • EXTERNAL STRUCTURE

    DEBUG-META-IMAGE

    Source

    Debug image is dynamic library loaded into process.

    See MAKE-DEBUG-META-IMAGE

  • EXTERNAL STRUCTURE

    DEBUG-META-INTERFACE

    Source

    The debug meta interface carries debug information for processing errors and crash reports.

    See MAKE-DEBUG-META-INTERFACE, ADD-DEBUG-META

  • EXTERNAL STRUCTURE

    DEVICE-CONTEXT

    Source

    Device context describes the device that caused the event.

    See MAKE-DEVICE-CONTEXT

  • EXTERNAL STRUCTURE

    ENVELOPE

    Source

    Envelopes are a data format similar to HTTP form data, comprising common Headers and a set of Items with their own headers and payloads. Envelopes are optimized for fast parsing and human readability. They support a combination of multiple Items in a single payload, such as:

    • Submit events with large binary attachments.
    • Enable communication between hops, for instance, between different SDKs (Native and Mobile, ReactNative and Android) and between Relays.
    • Allow batching of certain Items into a single submission.
    • Offline storage for deferred sending after connection issues.

    See MAKE-ENVELOPE

  • EXTERNAL STRUCTURE

    EVENT

    Source

    Events are the fundamental data that clients, often through the use of an SDK, send to the Sentry server.

    Events are packed into ENVELOPEs.

    See MAKE-EVENT

  • EXTERNAL STRUCTURE

    EXCEPTION-INTERFACE

    Source

    The Exception Interface specifies an exception or error that occurred in a program.

    See MAKE-EXCEPTION-INTERFACE

  • EXTERNAL STRUCTURE

    EXCEPTION-MECHANISM

    Source

    The exception mechanism is an optional field residing in the EXCEPTION-INTERFACE. It carries additional information about the way the exception was created on the target system. This includes general exception values obtained from the operating system or runtime APIs, as well as mechanism-specific values.

    See MAKE-EXCEPTION-MECHANISM, ADD-EXCEPTION

  • EXTERNAL STRUCTURE

    FEATURE-FLAG-CONTEXT

    Source

    The feature flag context contains information about the flags evaluated prior to an error occurring. It is populated with *FEATURES* by default.

    See MAKE-FEATURE-FLAG-CONTEXT

  • EXTERNAL STRUCTURE

    GPU-CONTEXT

    Source

    GPU context describes the GPU of the device.

    See MAKE-GPU-CONTEXT

  • EXTERNAL STRUCTURE

    MESSAGE-INTERFACE

    Source

    The Message Interface carries a log message that describes an event or error.

    See MAKE-MESSAGE-INTERFACE, ADD-MESSAGE

  • EXTERNAL STRUCTURE

    OS-CONTEXT

    Source

    OS context describes the operating system on which the crash happened/the event was created.

    See MAKE-OS-CONTEXT

  • EXTERNAL STRUCTURE

    REQUEST-INTERFACE

    Source

    The Request interface contains information on a HTTP request related to the event.

    See MAKE-REQUEST-INTERFACE, ADD-REQUEST

  • EXTERNAL STRUCTURE

    RUNTIME-CONTEXT

    Source

    Runtime context describes a runtime in more detail.

    See MAKE-RUNTIME-CONTEXT

  • EXTERNAL STRUCTURE

    SDK-INTERFACE

    Source

    The SDK Interface describes the Sentry SDK and its configuration used to capture and transmit an event.

    See MAKE-SDK-INTERFACE, ADD-SDK

  • EXTERNAL STRUCTURE

    STACK-TRACE-FRAME

    Source

    A stack trace contains a list of frames, each with various bits (most optional) describing the context of that frame.

    See MAKE-STACK-TRACE-FRAME, GET-STACK-TRACE

  • EXTERNAL STRUCTURE

    THREAD

    Source

    An object containing information on thread within THREADS-INTERFACE.

    See MAKE-THREAD, GET-THREADS, ADD-THREADS

  • EXTERNAL STRUCTURE

    THREADS-INTERFACE

    Source

    The Threads Interface specifies threads that were running at the time an event happened. These threads can also contain stack traces.

    See MAKE-THREADS-INTERFACE, GET-THREADS

  • EXTERNAL STRUCTURE

    USER-INTERFACE

    Source

    User Interface is an interface describing the authenticated User for a request.

    See MAKE-USER-INTERFACE

  • EXTERNAL STRUCTURE

    USER-REPORT

    Source

    User Report item works by associating user information and comments with an event. If both the item and its associated event are accepted, we convert it to a user feedback.

    Constraints:

    • This Item may occur once per Envelope.
    • User Reports can be ingested separately from their events. However, we recommend sending them in the same Envelope.
    • You may not associate multiple User Reports to the same event.
    • The event can not be more than 30 minutes old.
    • If the event does not exist in the same project or was never ingested, the report is discarded and never converted to feedback.

    See MAKE-USER-REPORT

  • EXTERNAL FUNCTION

    ADD-BREADCRUMBS

    • EVENT

    Source

    Adds all breadcrumbs previously created with MAKE-BREADCRUMB to the EVENT.

    NOTE that breadcrumbs are automatically added by MAKE-MESSAGE-EVENT and MAKE-CONDITION-EVENT.

  • EXTERNAL FUNCTION

    ADD-CONTEXT

    • EVENT
    • CONTEXT

    Source

    Appends given CONTEXT to a list of EVENT contexts.

  • EXTERNAL FUNCTION

    ADD-CONTEXTS

    • EVENT
    • &REST
    • CONTEXTS

    Source

    Sets context list of given EVENT to given CONTEXTS.

  • EXTERNAL FUNCTION

    ADD-DEBUG-META

    • EVENT
    • &KEY
    • LIBRARIES

    Source

    Adds DEBUG-META-INTERFACE with given LIBRARIRES list (defaulting to the results of CFFI:LIST-FOREIGN-LIBRARIES call) to the given EVENT.

  • EXTERNAL FUNCTION

    ADD-EXCEPTION

    • EVENT
    • EXCEPTION
    • STACK-TRACE
    • THREAD

    Source

    Adds EXCEPTION-INTERFACE with info on given EXCEPTION happened in THREAD with STACK-TRACE to given EVENT.

    See GET-STACK-TRACE

  • EXTERNAL FUNCTION

    ADD-EXTRA

    • EVENT
    • &REST
    • EXTRA
    • &KEY
    • &ALLOW-OTHER-KEYS

    Source

    Appends arbitrary keyword arguments as extra data on given EVENT.

  • EXTERNAL FUNCTION

    ADD-MESSAGE

    • EVENT
    • CONTROL
    • &REST
    • ARGS

    Source

    Adds MESSAGE-INTERFACE to given EVENT using FORMAT on given CONTROL and ARGS.

  • EXTERNAL FUNCTION

    ADD-REQUEST

    • EVENT
    • &KEY
    • METHOD
    • URL
    • DATA
    • COOKIES
    • HEADERS
    • ENV

    Source

    Adds REQUEST-INTERFACE with given METHOD, URL, DATA, COOKIES, HEADERS and ENV to the given EVENT.

    See MAKE-REQUEST-INTERFACE.

  • EXTERNAL FUNCTION

    ADD-SDK

    • EVENT

    Source

    Adds SDK-INTERFACE to the given EVENT.

  • EXTERNAL FUNCTION

    ADD-TAGS

    • EVENT
    • &REST
    • TAGS
    • &KEY
    • &ALLOW-OTHER-KEYS

    Source

    Appends arbitrary keyword arguments as tags on given EVENT.

  • EXTERNAL FUNCTION

    ADD-THREADS

    • EVENT
    • &KEY
    • CRASHED

    Source

    Adds THREADS-INTERFACE to the given EVENT. CRASHED is the crashed thread, defaulting to the current thread.

  • EXTERNAL FUNCTION

    ADD-USER

    • EVENT
    • &KEY
    • ID
    • NAME
    • EMAIL
    • IP-ADDRESS

    Source

    Adds USER-INTERFACE with given ID, NAME, EMAIL and IP-ADDRESS (defaulting to "{{auto}}") to the given EVENT.

    You should provide at least one of ID, NAME, EMAIL, IP-ADDRESS for Sentry to be able to tell you how many users are affected by one issue, for example. Sending a user that has none of these attributes and only custom attributes is valid, but not as useful.

  • EXTERNAL FUNCTION

    ENVELOPE-EVENT

    • ENVELOPE

    Source

    Returns EVENT item from given ENVELOPE or NIL if it does not have one.

  • EXTERNAL FUNCTION

    GET-MODULES

    • &OPTIONAL
    • LIST

    Source

    Returns plist of already loaded ASDF systems and their versions.

    If LIST argument is given, the function returns those systems instead.

  • EXTERNAL FUNCTION

    GET-STACK-TRACE

    Source

    Returns a list of STACK-TRACE-FRAME objects corresponding to current stack trace, sorted from oldest to newest.

  • EXTERNAL FUNCTION

    GET-THREADS

    • CRASHED

    Source

    Gets the list of THREAD objects corresponding to the list of all threads returned by (BT2:ALL-THREADS). CRASHED is the thread that has crashed, or NIL.

  • EXTERNAL FUNCTION

    INIT!

    • &KEY
    • DSN
    • CAPTURE-CONDITIONS-OUTSIDE-DUMPED-IMAGE
    • VARIABLE-ELISION-LENGTH
    • PROJECT-ROOT
    • PROJECT-PACKAGE
    • ENVIRONMENT
    • SERVER-NAME
    • RELEASE
    • DIST
    • BUILD-TYPE
    • APP-NAME
    • APP-VERSION
    • APP-BUILD
    • STARTUP-TIME
    • PROCESS-BEFORE-SEND
    • SOURCES

    Source

    Initializes library settings in a manner similar to WITH-SENTRY macro.

    See MAYBE-CAPTURE-CONDITION

  • EXTERNAL FUNCTION

    MAKE-APP-CONTEXT

    • &KEY
    • APP-START-TIME
    • BUILD-TYPE
    • APP-IDENTIFIER
    • APP-NAME
    • APP-VERSION
    • APP-BUILD
    • VIEW-NAMES
    • APP-MEMORY

    Source

    Creates APP-CONTEXT.

    • APP-START-TIME is optional timestamp when the user started the application. See *STARTUP-TIME*.
    • BUILD-TYPE is optional string identifying the kind of build. See *BUILD-TYPE*.
    • APP-IDENTIFIER is optional version-independent application identifier. Calculated automatically using UIOP:ARGV0
    • APP-NAME is optional human readable appication name, as it appears on the platform. See *APP-NAME*.
    • APP-VERSION is optional human readable application version, as it appears on the platform. See *APP-VERSION*.
    • APP-BUILD is optional internal build identifier, as it appears on the platform. See *APP-BUILD*.
    • VIEW-NAMES is optional list of visible UI screens at the current point in time.
    • APP-MEMORY is optional amount of memory used by the application in bytes. Calculated automatically using ROOM.
  • EXTERNAL FUNCTION

    MAKE-ATTACHMENT

    • &KEY
    • ENVELOPE
    • FILENAME
    • TYPE
    • CONTENT-TYPE

    Source

    Creates ATTACHMENT item in the given ENVELOPE.

    • FILENAME is the name of the uploaded file.
    • TYPE is the special type of this attachment. Defaults to event.attachment.
    • CONTENT-TYPE is the content type of the attachment payload. Any MIME type may be used; defaults to the content type deduced from FILENAME.
  • EXTERNAL FUNCTION

    MAKE-BREADCRUMB

    • &KEY
    • TYPE
    • CATEGORY
    • MESSAGE
    • DATA
    • LEVEL
    • ORIGIN
    • TIMESTAMP

    Source

    Creates a BREADCRUMB.

    • TYPE is the type of breadcrumb. By default, all breadcrumbs are recorded as default, which makes them appear as a Debug entry, but Sentry provides other types that influence how the breadcrumbs are rendered. For more information, see the description of recognized breadcrumb types.
    • CATEGORY is an optional dotted string indicating what the crumb is or from where it comes. Typically it is a module name or a descriptive string. For instance, ui.click could be used to indicate that a click happened in the UI or flask could be used to indicate that the event originated in the Flask framework.
    • MESSAGE is optional human-readable message for the breadcrumb.
    • DATA is optional arbitrary data associated with this breadcrumb. See MAKE-BREADCRUMB-DATA.
    • LEVEL is optional severity level of the breadcrumb. Allowed values are, from highest to lowest: :FATAL, :ERROR, :WARNING, :INFO, and :DEBUG. Levels are used in the UI to emphasize and deemphasize the crumb. The default is :INFO.
    • ORIGIN is a string representing the origin of the breadcrumb. This is typically used to identify the source of the breadcrumb. For example hybrid SDKs can identify native breadcrumbs from JS or Flutter.
    • TIMESTAMP is a timestamp representing when the breadcrumb occurred. Breadcrumbs are most useful when they include a timestamp, as it creates a timeline leading up to an event "exception"/"error". This defaults to current time.

    See ADD-BREADCRUMBS

  • EXTERNAL FUNCTION

    MAKE-BREADCRUMB-DATA

    • &REST
    • DATA
    • &KEY
    • &ALLOW-OTHER-KEYS

    Source

    Prepares the arbitrary keyword arguments to be used as the DATA for MAKE-BREADCRUMB.

  • EXTERNAL FUNCTION

    MAKE-BREADCRUMBS-INTERFACE

    • &KEY
    • VALUES

    Source

    Creates BREADCRUMBS-INTERFACE.

    • VALUES is a list of BREADCRUMB objects.
  • EXTERNAL FUNCTION

    MAKE-CONDITION-EVENT

    • CONDITION
    • &OPTIONAL
    • STACK-TRACE
    • THREAD

    Source

    Creates an EVENT with EXCEPTION-INTERFACE containing information on CONDITION.

    See GET-STACK-TRACE

  • EXTERNAL FUNCTION

    MAKE-CONTEXTS-INTERFACE

    • &KEY
    • CONTEXTS

    Source

    Creates CONTEXTS-INTERFACE.

    • CONTEXTS is a list of context objects.
  • EXTERNAL FUNCTION

    MAKE-DEBUG-META-IMAGE

    • LIBRARY

    Source

    Creates DEBUG-META-IMAGE from given CFFI LIBRARY.

  • EXTERNAL FUNCTION

    MAKE-DEBUG-META-INTERFACE

    • &KEY
    • IMAGES

    Source

    Creates DEBUG-META-INTERFACE.

    • IMAGES is a list of dynamic libraries loaded into the process.
  • EXTERNAL FUNCTION

    MAKE-DEFAULT-CONTEXTS

    • &KEY
    • STORAGE-PATH
    • VIEW-NAMES

    Source

    Creates list of applicable contexts and populates them with relevant data.

    STORAGE-PATH is the pathname within a storage which capacity would be reported in DEVICE-CONTEXT. It defaults to *DEFAULT-PATHNAME-DEFAULTS*.

    VIEW-NAMES is the optional list of strings representing visible UI screens at the current point in time, to be reported in APP-CONTEXT.

  • EXTERNAL FUNCTION

    MAKE-DEVICE-CONTEXT

    • &KEY
    • NAME
    • FAMILY
    • ARCH
    • BATTERY-LEVEL
    • MANUFACTURER
    • BRAND
    • SCREEN-WIDTH-PIXELS
    • SCREEN-HEIGHT-PIXELS
    • SCREEN-RESOLUTION
    • CHARGING
    • MEMORY-SIZE
    • FREE-MEMORY
    • STORAGE-SIZE
    • FREE-STORAGE
    • BOOT-TIME
    • PROCESSOR-COUNT
    • CPU-DESCRIPTION
    • BATTERY-STATUS
    • DEVICE-TYPE

    Source

    Creates DEVICE-CONTEXT.

    • NAME is optional name of the device. This is typically a hostname. See *SERVER-NAME*.
    • FAMILY is optional family of the device. This is usually the common part of model names across generations. For instance, iPhone would be a reasonable family, so would be Samsung Galaxy.
    • ARCH is optional CPU architecture.
    • BATTERY-LEVEL is optional floating point value defining the battery level (in the range 0-100), if the device has a battery.
    • MANUFACTURER is optional manufacturer of the device.
    • BRAND is optional brand of the device.
    • SCREEN-WIDTH-PIXELS is optional width of the screen.
    • SCREEN-HEIGHT-PIXELS is optional height of the screen.
    • SCREEN-RESOLUTION is optional screen resolution (e.g.: 800x600, 3040x1444).
    • CHARGING is boolean flag indicating whether the device was charging or not.
    • MEMORY-SIZE is total system memory available in bytes.
    • FREE-MEMORY is free system memory in bytes.
    • STORAGE-SIZE is optional total device storage in bytes.
    • FREE-STORAGE is optional free device storage in bytes.
    • BOOT-TIME is optional timestamp when the system was booted.
    • PROCESSOR-COUNT is number of "logical processors". For example, 8.
    • CPU-DESCRIPTION is optional CPU description. For example, Intel(R) Core(TM)2 Quad CPU Q6600 @ 2.40GHz.
    • BATTERY-STATUS is optional status of the device's battery. For example, Unknown, Charging, Discharging, NotCharging, Full.
    • DEVICE-TYPE is kind of device the application is running on. For example, Unknown, Handheld, Console, Desktop.
  • EXTERNAL FUNCTION

    MAKE-ENVELOPE

    • &KEY
    • ITEMS
    • PROCESSED
    • DSN
    • EVENT-ID
    • SENT-AT

    Source

    Creates ENVELOPE.

    • ITEMS is the list of envelope items.
    • PROCESSED is a boolean flag indicating whether this envelope was processed by *PROCESS-BEFORE-SEND* callback.
    • DSN is Sentry DSN string. Defaults to the value of *DSN*.
    • EVENT-ID is an event ID. Autogenerated.
    • SENT-AT is the timestamp when the event was sent from the client as string in RFC 3339 format. Used for clock drift correction of the event timestamp. The time zone must be UTC. Automatically set when the envelope is sent to Sentry.
  • EXTERNAL FUNCTION

    MAKE-EVENT

    • &KEY
    • ENVELOPE
    • TIMESTAMP
    • PLATFORM
    • LEVEL
    • LOGGER
    • TRANSACTION
    • SERVER-NAME
    • RELEASE
    • DIST
    • TAGS
    • ENVIRONMENT
    • MODULES
    • EXTRA
    • FINGERPRINT

    Source

    Creates EVENT item in the given ENVELOPE.

    • TIMESTAMP indicates when the event was created. The format is a string as defined in RFC 3339. Defaults to current time.
    • PLATFORM is a string representing the platform the client is submitting from. This will be used by the Sentry interface to customize various components in the interface. Defaults to other.
    • LEVEL is an optional record severity. Acceptable values are :FATAL, :ERROR, :WARNING, :INFO and :DEBUG. Defaults to :ERROR.
    • LOGGER is the optional name of the logger which created the record.
    • TRANSACTION is the name of the transaction which caused this exception. For example, in a web app, this might be the route name.
    • SERVER-NAME identifies the host from which the event was recorded. Defaults to the value of *SERVER-NAME*.
    • RELEASE is the optional release version of the application. Defaults to the value of *RELEASE*.
    • DIST is the optional distribution of the application. Defaults to the value of *DIST*.
    • TAGS is an optional plist of tags for this event. Each tag must be less than 200 characters. See MAKE-TAGS.
    • ENVIRONMENT is the environment name, such as production or staging. Defaults to the value of *ENVIRONMENT*.
    • MODULES is an optional plist of modules and their versions. Defaults to the result of call to GET-MODULES.
    • EXTRA is an arbitrary mapping of additional metadata to store with the event in form of plist. NOTE that plist values should be printed with ~A to valid JSON string. See MAKE-EXTRA.
    • FINGERPRINT is an optional list of strings used to dictate the deduplication of this event.
  • EXTERNAL FUNCTION

    MAKE-EXCEPTION-INTERFACE

    • &KEY
    • TYPE
    • VALUE
    • MODULE
    • THREAD-ID
    • MECHANISM
    • STACKTRACE

    Source

    Creates EXCEPTION-INTERFACE.

    • TYPE is the type of exception.
    • VALUE is the value of exception (a string).
    • MODULE is the optional module, or package which the exception type lives in.
    • THREAD-ID is an optional value which refers to a thread in the THREADS-INTERFACE.
    • MECHANISM is optional object describing the mechanism that created this exception. See EXCEPTION-MECHANISM.
    • STACKTRACE is an optional stack trace object, a list of STACK-TRACE-FRAME objects.
  • EXTERNAL FUNCTION

    MAKE-EXCEPTION-MECHANISM

    • &KEY
    • TYPE
    • DESCRIPTION
    • HELP-LINK
    • SYNTHETIC
    • EXCEPTION-ID
    • PARENT-ID
    • IS-EXCEPTION-GROUP
    • META
    • DATA
    • HANDLED

    Source

    Creates EXCEPTION-MECHANISM.

    • TYPE is unique identifier of this mechanism determining rendering and processing of the mechanism data. Defaults to "condition".
    • DESCRIPTION is optional human-readable description of the error mechanism and a possible hint on how to solve this error.
    • HELP-LINK is optional fully qualified URL to an online help resource, possibly interpolated with error parameters.
    • SYNTHETIC is an optional flag indicating that this error is synthetic. Synthetic errors are errors that carry little meaning by themselves. This may be because they are created at a central place (like a crash handler), and are all called the same: Error, Segfault etc. When the flag is set, Sentry will then try to use other information (top in-app frame function) rather than the exception type and value in the UI for the primary event display. Furthermore, if this flag is set, Sentry will ignore the exception type when grouping the exception into issues. This flag should be set for all "segfaults" for instance as every single error group would look very similar otherwise. Also, errors the client creates to add a stack trace to events that don't have one themselves should be marked as synthetic (This happens, for example, when users set attachStackTrace: true and capture a string message via captureException or captureMessage).
    • EXCEPTION-ID is optional numeric value providing an ID for the exception relative to this specific event.
    • PARENT-ID is optional numeric value pointing at the exception-id that is the parent of this exception.
    • IS-EXCEPTION-GROUP is flag indicating that this exception is part of an exception group type specific to the platform or language.
    • META is optional information from the operating system or runtime on the exception mechanism (see meta information). NOTE that this should be printed with ~A to valid JSON string.
    • DATA is optional arbitrary extra data that might help the user understand the error thrown by this mechanism. NOTE that this should be printed with ~A to valid JSON string.
    • HANDLED is flag indicating whether the user has handled the exception (for example, via HANDLER-CASE). Defaults to *EXCEPTION-HANDLED*.
  • EXTERNAL FUNCTION

    MAKE-EXTRA

    • &REST
    • EXTRA
    • &KEY
    • &ALLOW-OTHER-KEYS

    Source

    Prepares the arbitrary keyword arguments to be used as the EXTRA for MAKE-EVENT. NOTE that values should be printed with ~A to valid JSON string, that means that e.g. string values should be quoted.

  • EXTERNAL FUNCTION

    MAKE-FEATURE-FLAG-CONTEXT

    • &KEY
    • VALUES

    Source

    Creates FEATURE-FLAG-CONTEXT.

    • VALUES is the list of string designators corresponding to enabled feature flags. Defaults to *FEATURES*.
  • EXTERNAL FUNCTION

    MAKE-GPU-CONTEXT

    Source

    Creates GPU-CONTEXT.

    NOTE: this works in a meaningful way only when :LISP-SENTRY-GPU was present in *FEATURES* when the system was compiled and there is active OpenGL context in current thread.

  • EXTERNAL FUNCTION

    MAKE-MESSAGE-EVENT

    • LEVEL
    • CONTROL
    • &REST
    • ARGS

    Source

    Creates an EVENT corresponding to simple text message with given LEVEL, using FORMAT on given CONTROL and ARGS.

  • EXTERNAL FUNCTION

    MAKE-MESSAGE-INTERFACE

    • &KEY
    • FORMATTED

    Source

    Creates MESSAGE-INTERFACE.

    • FORMATTED is the fully formatted message.
  • EXTERNAL FUNCTION

    MAKE-OS-CONTEXT

    • &KEY
    • DISTRIBUTION-NAME
    • DISTRIBUTION-VERSION
    • DISTRIBUTION-PRETTY-NAME
    • NAME
    • VERSION

    Source

    Creates OS-CONTEXT.

    • DISTRIBUTION-NAME is optional stable name for each distribution. This maps to ID in /etc/os-release (examples: ubuntu, rhel, alpine; a full list of tested identifiers is available in the Native SDK repository).
    • DISTRIBUTION-VERSION is optional identifier of at least the major release version number. This maps to VERSION_ID in /etc/os-release. Distributions with rolling releases only, will not provide a version.
    • DISTRIBUTION-PRETTY-NAME is optional full name, full version, and release alias. This maps to PRETTY_NAME in /etc/os-release (examples: Ubuntu 22.04.4 LTS, Raspian GNU/Linux 10 (buster)).
    • NAME is the name of the operating system.
    • VERSION is the version of the operating system.
  • EXTERNAL FUNCTION

    MAKE-REQUEST-INTERFACE

    • &KEY
    • METHOD
    • URL
    • DATA
    • COOKIES
    • ENV
    • HEADERS

    Source

    Creates REQUEST-INTERFACE.

    • METHOD is the HTTP method of the request.
    • URL is the URL of the request if available.
    • DATA is optional submitted data in a format that makes the most sense. Can be given as string or structural data of any format. NOTE that this should be printed with ~A to valid JSON string.
    • COOKIES is optional cookie values. Should be given as plist with string keys and string values.
    • ENV is optional dictionary containing environment information passed from the server. This is where information such as Clackup env go that are not HTTP headers. Should be given as plist with keyword keys.
    • HEADERS is dictionary of submitted headers. If a header appears multiple times it, needs to be merged according to the HTTP standard for header merging. Header names are treated case-insensitively by Sentry. Should be given as plist with keyword or string keys and string values.
  • EXTERNAL FUNCTION

    MAKE-RUNTIME-CONTEXT

    • &KEY
    • NAME
    • VERSION

    Source

    Creates RUNTIME-CONTEXT.

    • NAME is the name of the runtime. Defaults to LISP-IMPLEMENTATION-TYPE.
    • VERSION is the version identifier of the runtime. Defaults to LISP-IMPLEMENTATION-VERSION
  • EXTERNAL FUNCTION

    MAKE-SDK-INTERFACE

    • &KEY
    • NAME
    • VERSION
    • PACKAGES

    Source

    Creates SDK-INTERFACE.

    • NAME is the name of the SDK.
    • VERSION is the version of the SDK.
    • PACKAGES is a list of packages that were installed as part of this SDK or the activated integrations. Each package consists of a name in the format source:identifier and version.
  • EXTERNAL FUNCTION

    MAKE-STACK-TRACE-FRAME

    • &KEY
    • FILENAME
    • LINENO
    • COLNO
    • ABS-PATH
    • CONTEXT-LINE
    • PRE-CONTEXT
    • POST-CONTEXT
    • SOURCE-LINK
    • IN-APP
    • VARS
    • INSTRUCTION-ADDR
    • PACKAGE
    • FUNCTION

    Source

    Creates STACK-TRACE-FRAME.

    • FILENAME is optional path to the source file relative to the project root directory (see *PROJECT-ROOT*).
    • LINENO is optional line number of the call, starting at 1.
    • COLNO is optional column number of the call, starting at 1.
    • ABS-PATH is optional absolute path to the source file.
    • CONTEXT-LINE is optional source code in filename at LINENO.
    • PRE-CONTEXT is optional list of source code lines before CONTEXT-LINE (in order).
    • POST-CONTEXT is optional list of source code lines after CONTEXT-LINE (in order).
    • SOURCE-LINK is optional URL representing the source code, e.g. commit-specific GitHub raw source link.
    • IN-APP is the flag indicating whether this frame is related to the execution of the relevant code in this stack trace. For example, the frames that might power the framework’s web server of your app are probably not relevant. However, calls to the framework’s library once you start handling code likely are relevant.
    • VARS is optional mapping of variables which were available within this frame (usually context-locals).
    • INSTRUCTION-ADDR is instruction address for symbolication.
    • PACKAGE is optional "package" the frame was contained in.
    • FUNCTION is the name of the function being called.
  • EXTERNAL FUNCTION

    MAKE-TAGS

    • &REST
    • TAGS
    • &KEY
    • &ALLOW-OTHER-KEYS

    Source

    Prepares the arbitrary keyword arguments to be used as the TAGS for MAKE-EVENT.

  • EXTERNAL FUNCTION

    MAKE-THREAD

    • &KEY
    • ID
    • CRASHED
    • CURRENT
    • STACKTRACE
    • NAME

    Source

    Creates THREAD.

    • ID is the ID of the thread. Typically a number or numeric string. Needs to be unique among the threads. An exception can set the THREAD-ID attribute to cross-reference this thread.
    • CRASHED is a flag indicating whether the thread was the cause for the event being sent, e.g. due to a crash. Defaults to NIL.
    • CURRENT is a flag indicating whether the thread was in the foreground. A thread is in foreground when it's executing. Defaults to NIL.
    • STACKTRACE is optional stack trace. List of STACK-TRACE-FRAME objects.
    • NAME is the thread name.
  • EXTERNAL FUNCTION

    MAKE-THREADS-INTERFACE

    • &KEY
    • VALUES

    Source

    Creates THREADS-INTERFACE.

    • VALUES is the list of THREAD objects.
  • EXTERNAL FUNCTION

    MAKE-USER-INTERFACE

    • &KEY
    • ID
    • USERNAME
    • EMAIL
    • IP-ADDRESS

    Source

    Creates USER-INTERFACE.

    • ID is optional application-specific internal identifier for the user.
    • USERNAME is optional username. Typically used as a better label than the internal id.
    • EMAIL is optional alternative, or addition, to the username. Sentry is aware of email addresses and can display things such as Gravatars and unlock messaging capabilities.
    • IP-ADDRESS is the user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. Set to "{{auto}}" to let Sentry infer the IP address from the connection.
  • EXTERNAL FUNCTION

    MAKE-USER-REPORT

    • &KEY
    • ENVELOPE
    • EMAIL
    • NAME
    • COMMENTS

    Source

    Creates USER-REPORT item in the given ENVELOPE.

    • EMAIL is the email of the user.
    • NAME is the name of the user.
    • COMMENTS is the comments of the user about what happened. The max length is 4096 characters.
  • EXTERNAL FUNCTION

    MAKE-USER-REPORT-EVENT

    • COMMENTS
    • &KEY
    • NAME
    • EMAIL

    Source

    Creates an envelope with dummy EVENT item and USER-REPORT item. Returns the event.

  • EXTERNAL FUNCTION

    MAYBE-CAPTURE-CONDITION

    • CONDITION
    • &REST
    • REST

    Source

    Captures a condition according to settings.

    See *CAPTURE-CONDITIONS-OUTSIDE-DUMPED-IMAGE*

  • EXTERNAL GENERIC-FUNCTION

    CAPTURE

    • OBJECT

    Source

    The reporting of an event is called capturing. When an event is captured, it’s sent to Sentry.

    OBJECT should be ENVELOPE object or one of envelope items (currently supported items are ATTACHMENT, EVENT and USER-REPORT), in which case the envelope where the item belongs is captured.

  • EXTERNAL MACRO

    MAKE-SAVED-SOURCES

    • &KEY
    • SYSTEM
    • EXTRA

    Source

    Specifies the set of source files to be saved for display in stack traces in Sentry. To be used as :SOURCES argument to WITH-SENTRY and INIT!.

    SYSTEM specifies whether to save sources of Lisp runtime. Defaults to NIL since it may significantly blow the size of the dumped Lisp image and those sources are not very interesting usually. Consider using Lisp image compression when setting this to T.

    EXTRA is arbitrary list of directory pathnames to recursively scan for *.lisp files to be saved.

  • EXTERNAL MACRO

    WITH-SENTRY

    • &KEY
    • DSN
    • CAPTURE-CONDITIONS-OUTSIDE-DUMPED-IMAGE
    • CAPTURE-WARNINGS
    • HANDLED
    • VARIABLE-ELISION-LENGTH
    • PROJECT-ROOT
    • PROJECT-PACKAGE
    • ENVIRONMENT
    • SERVER-NAME
    • RELEASE
    • DIST
    • BUILD-TYPE
    • APP-NAME
    • APP-VERSION
    • APP-BUILD
    • STARTUP-TIME
    • PROCESS-BEFORE-SEND
    • SOURCES
    • &BODY
    • BODY

    Source

    Initializes library settings as described below and runs BODY wrapped in HANDLER-BIND that CAPTUREs conditions popping up. Rule of thumb for placing this macro in your code — call it as early as possible, but be sure to still be able to catch all conditions you're interested in.

    • DSN sets *DSN*, a Sentry Data Source Name. Defaults to the value of SENTRY_DSN environment variable. If unset, the SDK will just not send any events.
    • CAPTURE-CONDITIONS-OUTSIDE-DUMPED-IMAGE sets *CAPTURE-CONDITIONS-OUTSIDE-DUMPED-IMAGE* which controls whether to CAPTURE conditions outside of circumstances of dumped Lisp image.
    • CAPTURE-WARNINGS controls whether WARNING conditions are CAPTUREd.
    • HANDLED is form that is evaluated each time the condition is CAPTUREd to determine the value of *EXCEPTION-HANDLED* which indicates whether the condition was handled or not.
    • VARIABLE-ELISION-LENGTH sets *VARIABLE-ELISION-LENGTH* which controls maximum length of variable values displayed in stack traces.
    • PROJECT-ROOT sets *PROJECT-ROOT* which is absolute path to the project directory.
    • PROJECT-PACKAGE sets *PROJECT-PACKAGE* which is name of the project package.
    • ENVIRONMENT sets *ENVIRONMENT* which is the environment name, such as production or staging.
    • SERVER-NAME sets *SERVER-NAME* which is the name of the device, typically a hostname.
    • RELEASE sets *RELEASE* which is the release version of the application.
    • DIST sets *DIST* which is the distribution of the application.
    • BUILD-TYPE sets *BUILD-TYPE* which is string identifying the kind of build.
    • APP-NAME sets *APP-NAME* which is human readable application name, as it appears on the platform.
    • APP-VERSION sets *APP-VERSION* which is human readable application version, as it appears on the platform.
    • APP-BUILD sets *APP-BUILD* which is internal build identifier, as it appears on the platform.
    • STARTUP-TIME is form that is evaluated to set the value of *STARTUP-TIME* which is the timestamp when the user started the application. If set to NIL, *STARTUP-TIME* is not set. Defaults to (LOCAL-TIME:NOW).
    • PROCESS-BEFORE-SEND sets *PROCESS-BEFORE-SEND* which is the designator of function of one argument that processes or cancels the ENVELOPE right before CAPTURE sends it to Sentry.
    • SOURCES is form that is evaluated to set the value of *SOURCES* with the source code the Lisp image was built of to display in Sentry stack traces. Set to NIL to prevent source saving whatsoever. Defaults to the call to MAKE-SAVED-SOURCES.

    See INIT!