@@ -0,0 +1,116 @@
1+# Error logging with Sentry
3+In this recipe we will use [Sentry](https://sentry.io) to collect the runtime exceptions generated by our application. We will use the [raven-haskell](https://hackage.haskell.org/package/raven-haskell) package, which is a client for a Sentry event server. Mind that this package is not present on [Stackage](https://www.stackage.org/), so if we are using [Stack](https://docs.haskellstack.org) we’ll need to add it to our `extra-deps` section in the `stack.yaml` file.
5+To exemplify this we will need the following imports
8+{-# LANGUAGE DataKinds #-}
9+{-# LANGUAGE TypeOperators #-}
11+import Control.Exception (Exception,
12+ SomeException, throw)
13+import Data.ByteString.Char8 (unpack)
14+import Network.Wai (Request, rawPathInfo,
16+import Network.Wai.Handler.Warp (defaultOnException,
22+import System.Log.Raven (initRaven, register,
24+import System.Log.Raven.Transport.HttpConduit (sendRecord)
25+import System.Log.Raven.Types (SentryLevel (Error),
29+Just for the sake of the example we will use the following API which will throw an exception
32+type API = "break" :> Get '[JSON] ()
34+data MyException = MyException deriving (Show)
36+instance Exception MyException
39+ where breakHandler :: Handler ()
45+First thing we need to do if we want to intercept and log this exception, we need to look in the section of our code where we run the `warp` application, and instead of using the simple `run` function from `warp`, we use the `runSettings` functions which allows to customise the handling of requests
53+ setOnException sentryOnException $
56+ runSettings settings $ serve (Proxy :: Proxy API) server
59+The definition of the `sentryOnException` function could look as follows
62+sentryOnException :: Maybe Request -> SomeException -> IO ()
63+sentryOnException mRequest exception = do
64+ sentryService <- initRaven
65+ "https://username:password@senty.host/id"
73+ (formatMessage mRequest exception)
74+ (recordUpdate mRequest exception)
75+ defaultOnException mRequest exception
78+It does three things. First it initializes the service which will communicate with Sentry. The parameters it receives are:
80+- the Sentry `DSN`, which is obtained when creating a new project on Sentry
81+- a default way to update sentry fields, where we use the identity function
82+- an event trasport, which generally would be `sendRecord`, an HTTPS capable trasport which uses http-conduit
83+- a fallback handler, which we choose to be `silentFallback` since later we are logging to the console anyway.
85+In the second step it actually sends our message to Sentry with the `register` function. Its arguments are:
87+- the configured Sentry service which we just created
88+- the name of the logger
89+- the error level (see [SentryLevel](https://hackage.haskell.org/package/raven-haskell-0.1.2.0/docs/System-Log-Raven-Types.html#t:SentryLevel) for the possible options)
90+- the message we want to send
91+- an update function to handle the specific `SentryRecord`
93+Eventually it just delegates the error handling to the default warp mechanism.
95+The function `formatMessage` simply uses the request and the exception to return a string with the error message.
98+formatMessage :: Maybe Request -> SomeException -> String
99+formatMessage Nothing exception = "Exception before request could be parsed: " ++ show exception
100+formatMessage (Just request) exception = "Exception " ++ show exception ++ " while handling request " ++ request
103+The only piece left now is the `recordUpdate` function which allows to decorate with other [attributes](https://docs.sentry.io/clientdev/attributes/) the default `SentryRecord`.
106+recordUpdate :: Maybe Request -> SomeException -> SentryRecord -> SentryRecord
107+recordUpdate Nothing exception record = record
108+recordUpdate (Just request) exception record = record
109+ { srCulprit = Just $ unpack $ rawPathInfo request
110+ , srServerName = fmap unpack $ requestHeaderHost request
114+In this examples we set the raw path as the culprit and we use the `Host` header to populate the server name field.
116+You can try to run this code using the `cookbook-sentry` executable. You should obtain a `MyException` error in the console and, if you provided a valid Sentry DSN, you should also find your error in the Sentry interface.