chore: Exception, Machanism, Stacktrace, Stackframe improvments

- JSDoc added
- MechanismMeta added

Author: S3bt3r

packages/types/src/exception.ts

@@ -1,12 +1,38 @@
 import { Mechanism } from './mechanism';
 import { Stacktrace } from './stacktrace';
 
-/** JSDoc */
+/**
+ * The Exception Interface specifies an exception or error that occurred in a program.
+ * @external https://develop.sentry.dev/sdk/event-payloads/exception/
+ */
 export interface Exception {
-  type?: string;
-  value?: string;
-  mechanism?: Mechanism;
+  /**
+   * The type of exception, e.g. ValueError.
+   */
+  type: string;
+
+  /**
+   * The value of the exception.
+   */
+  value: string;
+
+  /**
+   * The module, or package which the exception type lives in.
+   */
   module?: string;
+
+  /**
+   * An value which refers to a thread in the Threads Interface.
+   */
   thread_id?: number;
+
+  /**
+   * An object describing the mechanism that created this exception.
+   */
+  mechanism?: Mechanism;
+
+  /**
+   * An stack trace object corresponding to the Stack Trace Interface.
+   */
   stacktrace?: Stacktrace;
 }

packages/types/src/mechanism.ts

@@ -1,9 +1,133 @@
-/** JSDoc */
+/**
+ * @external https://develop.sentry.dev/sdk/event-payloads/exception/#exception-mechanism
+ */
 export interface Mechanism {
+  /**
+   * Unique identifier of this mechanism determining rendering and processing of the mechanism data.
+   */
   type: string;
-  handled: boolean;
-  data?: {
-    [key: string]: string | boolean;
-  };
+
+  /**
+   * Human-readable description of the error mechanism and a possible hint on how to solve this error.
+   */
+  description?: string;
+
+  /**
+   * Human-readable description of the error mechanism and a possible hint on how to solve this error.
+   */
+  helpLink?: string;
+
+  /**
+   * Flag indicating whether the user has handled the exception (for example, via try ... catch).
+   */
+  handled?: boolean;
+
+  /**
+   * An 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 exception type and value in the UI for the primary event display.
+   * This flag should be set for all "segfaults" for instance as every
+   * single error group would look very similar otherwise.
+   */
   synthetic?: boolean;
+
+  /**
+   * Information from the operating system or runtime on the exception mechanism.
+   */
+  meta?: MechanismMeta;
+
+  /**
+   * Arbitrary extra data that might help the user understand the error thrown by this mechanism.
+   */
+  data?: Record<string, unknown>;
+}
+
+export interface MechanismMeta {
+  /**
+   * Information on the POSIX signal.
+   * On Apple systems, signals also carry a code in addition to the signal number describing the signal in more detail.
+   * On Linux, this code does not exist.
+   */
+  signal?: MechanismMetaSignal;
+
+  /**
+   * A Mach Exception on Apple systems comprising a code triple and optional descriptions.
+   */
+  mach_exception?: MechanismMetaMachException;
+
+  /**
+   * Error codes set by Linux system calls and some library functions as
+   * specified in ISO C99, POSIX.1-2001, and POSIX.1-2008.
+   * See errno(3) for more information.
+   */
+  errno?: MechanismMetaErrorNo;
+}
+
+/**
+ * @external https://develop.sentry.dev/sdk/event-payloads/exception/#meta-information
+ */
+export interface MechanismMetaSignal {
+  /**
+   * The POSIX signal number.
+   */
+  number: number;
+
+  /**
+   * Apple signal code.
+   */
+  code?: string;
+
+  /**
+   * Name of the signal based on the signal number.
+   */
+  name?: string;
+
+  /**
+   * Name of the signal code.
+   */
+  code_name?: string;
+}
+
+/**
+ * @external https://develop.sentry.dev/sdk/event-payloads/exception/#meta-information
+ */
+export interface MechanismMetaMachException {
+  /**
+   * Numeric exception number.
+   */
+  exception: number;
+
+  /**
+   * Numeric exception code.
+   */
+  code: number;
+
+  /**
+   * Numeric exception subcode.
+   */
+  subcode: number;
+
+  /**
+   * Name of the exception constant in iOS / macOS.
+   */
+  name?: string;
+}
+
+/**
+ * @external https://develop.sentry.dev/sdk/event-payloads/exception/#meta-information
+ */
+export interface MechanismMetaErrorNo {
+  /**
+   * The error number
+   */
+  number: number;
+
+  /**
+   * Name of the error
+   */
+  name?: string;
 }

packages/types/src/stackframe.ts

@@ -1,17 +1,116 @@
-/** JSDoc */
+/**
+ * @external https://develop.sentry.dev/sdk/event-payloads/stacktrace/#frame-attributes
+ */
 export interface StackFrame {
+  /**
+   * The path to the source file relative to the project root directory.
+   * The value should not make file names indistinguishable and should only change between releases for files that were actually renamed.
+   * In some SDKs, this is implemented as the path relative to a certain entry point relevant to the language/platform.
+   */
   filename?: string;
+
+  /**
+   * The name of the function being called.
+   * This function name may be shortened or demangled. If not, Sentry will demangle and shorten it.
+   * The original function name will be stored in rawFunction.
+   */
   function?: string;
+
+  /**
+   * The original function name, if the function name is shortened or demangled.
+   * Sentry shows the raw function when clicking on the shortened one in the UI.
+   */
+  raw_function?: string;
+
+  /**
+   * Platform-specific module path (e.g. sentry.interfaces.Stacktrace).
+   */
   module?: string;
-  platform?: string;
+
+  /**
+   * The line number of the call, starting at 1.
+   */
   lineno?: number;
+
+  /**
+   * The column number of the call, starting at 1.
+   */
   colno?: number;
+
+  /**
+   * The absolute path to the source file.
+   */
   abs_path?: string;
+
+  /**
+   * Source code in filename at lineno.
+   */
   context_line?: string;
+
+  /**
+   * A list of source code lines before context_line (in order) –
+   * usually [lineno - 5:lineno].
+   */
   pre_context?: string[];
+
+  /**
+   * A list of source code lines after context_line (in order) –
+   * usually [lineno + 1:lineno + 5].
+   */
   post_context?: string[];
+
+  /**
+   * Signals 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.
+   */
   in_app?: boolean;
+
+  /**
+   * A mapping of variables which were available within this frame (usually context-locals).
+   */
+  vars?: Record<string, unknown>;
+
+  /**
+   * An instruction address for symbolication.
+   * This should be a string with a hexadecimal number that includes a 0x prefix.
+   * If this is set and a known image is defined in the Debug Meta Interface,
+   * then symbolication can take place.
+   * Note that the addr_mode attribute can control the behavior of this address.
+   */
   instruction_addr?: string;
+
+  /**
+   * Optionally changes the addressing mode.
+   * The default value is the same as "abs" which means absolute referencing.
+   * This can also be set to "rel:DEBUG_ID" or "rel:IMAGE_INDEX" to make addresses relative to an object referenced by debug id or index.
+   * This for instance is necessary for WASM processing as WASM does not use a unified address space.
+   */
   addr_mode?: string;
-  vars?: { [key: string]: any };
+
+  /**
+   * An address that points to a symbol.
+   * We use the instruction address for symbolication,
+   * but this can be used to calculate an instruction offset automatically.
+   * Note that the addr_mode attribute can control the behavior of this address.
+   */
+  symbol_addr?: string;
+
+  /**
+   * An address of the debug image to reference.
+   */
+  image_addr?: string;
+
+  /**
+   * The "package" the frame was contained in.
+   * Depending on the platform, this can be different things.
+   */
+  package?: string;
+
+  /**
+   * This can override the platform for a single frame.
+   * Otherwise, the platform of the event is assumed.
+   * This can be used for multi-platform stack traces, such as in React Native.
+   */
+  platform?: string;
 }

packages/types/src/stacktrace.ts

@@ -1,7 +1,25 @@
 import { StackFrame } from './stackframe';
 
-/** JSDoc */
+/**
+ * A stack trace contains a list of frames,
+ * each with various bits (most optional) describing the context of that frame.
+ * Frames should be sorted from oldest to newest.
+ * @external https://develop.sentry.dev/sdk/event-payloads/stacktrace/
+ */
 export interface Stacktrace {
+  /**
+   * A non-empty list of stack frames.
+   * The list is ordered from caller to callee, or oldest to youngest.
+   * The last frame is the one creating the exception.
+   */
   frames?: StackFrame[];
+
+  /**
+   * A map of register names and their values.
+   * The values should contain the actual register values of the thread,
+   * thus mapping to the last frame in the list.
+   */
+  registers?: Record<string, unknown>;
+
   frames_omitted?: [number, number];
 }

packages/types/src/thread.ts

@@ -1,10 +1,36 @@
 import { Stacktrace } from './stacktrace';
 
-/** JSDoc */
+/**
+ * The Threads Interface specifies threads that were running at the time an event happened.
+ * These threads can also contain stack traces.
+ * @external https://develop.sentry.dev/sdk/event-payloads/threads/
+ */
 export interface Thread {
+  /**
+   * 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.
+   */
   id?: number;
-  name?: string;
-  stacktrace?: Stacktrace;
+
+  /**
+   * A flag indicating whether the thread crashed. Defaults to false.
+   */
   crashed?: boolean;
+
+  /**
+   * A flag indicating whether the thread was in the foreground.
+   */
   current?: boolean;
+
+  /**
+   * The thread name.
+   */
+  name?: string;
+
+  /**
+   * A stack trace object corresponding to the Stack Trace Interface.
+   */
+  stacktrace?: Stacktrace;
 }