Stackframe.hs

module Data.Bugsnag.Types.Stackframe
  ( Stackframe (..)
  , exampleStackframe
  ) where

import Data.Bugsnag.Types.Prelude


data Stackframe = Stackframe
  { file :: Text
  -- ^ The file that this stack frame was executing. It is recommended that you
  -- strip any unnecessary or common information from the beginning of the path.
  , lineNumber :: Int
  -- ^ The line of the file that this frame of the stack was in.
  , columnNumber :: Maybe Int
  -- ^ The column of the file that this frame of the stack was in.
  , method :: Text
  -- ^ The method that this particular stack frame is within.
  , inProject :: Maybe Bool
  -- ^ If this stacktrace line is in the user's project code, set this to true. It
  -- is useful for developers to be able to see which lines of a stacktrace are
  -- within their own application, and which are within third party libraries.
  -- This boolean field allows Bugsnag to display this information in the
  -- stacktrace as well as use the information to help group errors better.
  , code :: Maybe (KeyMap Text)
  -- ^ The code in this file surrounding this line. This is an object containing
  -- key value pairs where each key is a line number and each value is the code
  -- from that line. You can include up to three lines on either side of the line
  -- where the error occurred. These will be displayed on the bugsnag dashboard
  -- when you expand that line.
  -- 
  -- ```
  -- {
  --     "1231": "  def a",
  --     "1232": "",
  --     "1233": "    if problem?",
  --     "1234": "      raise 'something went wrong'",
  --     "1235": "    end"
  --     "1236": "",
  --     "1237": "  end"
  -- }
  -- ```
  , frameAddress :: Maybe Text
  -- ^ The run time memory address of the instruction being executed (for the first
  -- stack frame) or to which control will return after the function call or
  -- subroutine completes.
  , loadAddress :: Maybe Text
  -- ^ The address in memory where the binary has been loaded at run time.
  , isLR :: Maybe Bool
  -- ^ True if `frameAddress` corresponds to value of the Link Register. This is sometimes
  -- the case for the second frame in a stack - e.g. for signals and mach exceptions.
  , isPC :: Maybe Bool
  -- ^ True if `frameAddress` corresponds to the Program Counter.
  , symbolAddress :: Maybe Text
  -- ^ The run time memory address of the symbol that most closely matches `frameAddress`.
  , machoFile :: Maybe Text
  -- ^ The full path of the Mach-O binary (iOS/macOS/tvOS only).
  , machoLoadAddress :: Maybe Text
  -- ^ The address in memory where the Mach-O binary has been loaded at run time.
  -- This may differ from `machoVMAddress` due to Address Space Layout Randomization.
  -- The difference between `machoLoadAddress` and `machoVMAddress` is known as the
  -- "slide" (iOS/macOS/tvOS only).
  , machoUUID :: Maybe Text
  -- ^ A UUID which uniquely identifies this Mach-O binary (iOS/macOS/tvOS only).
  , machoVMAddress :: Maybe Text
  -- ^ The memory address assigned to the Mach-O binary by the linker at build time
  -- (iOS/macOS/tvOS only).
  , codeIdentifier :: Maybe Text
  -- ^ The ID of the executable/library that the frame relates to.
  }
  deriving stock (Eq, Show, Generic)

instance FromJSON Stackframe where
  parseJSON = genericParseJSON aesonOptions

instance ToJSON Stackframe where
  toJSON = genericToJSON aesonOptions
  toEncoding = genericToEncoding aesonOptions

exampleStackframe :: Stackframe
exampleStackframe = Stackframe
  { file = "controllers/auth/session_controller.rb"
  , lineNumber = 1234
  , columnNumber = Just 123
  , method = "create"
  , inProject = Just True
  , code = Just mempty
  , frameAddress = Just "0x000000010d131040"
  , loadAddress = Just "0x000000010d12e000"
  , isLR = Just False
  , isPC = Just True
  , symbolAddress = Just "0x000000010d130fe6"
  , machoFile = Just "/System/Library/Frameworks/Foundation.framework/Foundation"
  , machoLoadAddress = Just "0x000000010d12e000"
  , machoUUID = Just "B3196052-BAF1-3EA5-AD28-F9E6ECCF0B03"
  , machoVMAddress = Just "0x0000000100000000"
  , codeIdentifier = Just "b6b529d5e58421a0fba0fa2c5c2c5f3e"
  }