dp wiz avatar dp wiz committed 76f0641

Write some docs.

Comments (0)

Files changed (1)

lookout/src/System/Log/Lookout.hs

+-- | Lookout is a client for Sentry event server (<https://www.getsentry.com/>).
+--
+--   Start by initializing the lookout 'Service':
+--
+-- > l <- initLookout
+-- >          "https://pub:priv@sentry.hostname.tld:8443/sentry/example_project"
+-- >          id
+-- >          sendRecord
+-- >          stderrFallback
+--
+--   Send events using 'register' function:
+--
+-- > register l "my.logger.name" Debug "Hi there!" id
+--
+--   Tags and stuff can be added using register update functions.
+--
+-- > import Data.HashMap.Strict as HM
+-- > let tags r = r { srTags = HM.insert "spam" "sausage"
+-- >                         . HM.insert "eggs" "bacon"
+-- >                         . srTags r }
+-- > lt <- initLookout dsn tags sendRecord stderrFallback
+-- >
+-- > let culprit r = r { srCulprit = "my.module.function.name" }
+-- > register lt "test.culprit" Error "It's a trap!" culprit
+-- > let extra r = r { srExtra = HM.insert "fnord" "42" $ srExtra r }
+-- > register lt "test.extra" Info "Test with tags and extra, please ignore."
+--
+--   The core package provides only general interface for sending events which
+--   could be wrapped to adapt it to your needs.
+--
+-- > let debug msg = forkIO $ register l "my.logger.name" Debug msg (culprit . extra)
+-- > debug "Async stuff too."
+
 module System.Log.Lookout
-    ( record, recordLBS
+    ( -- * Event service
+      initLookout, disabledLookout
+    , register
+      -- * Fallback handlers
     , stderrFallback, errorFallback, silentFallback
-    , initLookout, disabledLookout
-    , register
+      -- * Lower level helpers
+    , record, recordLBS
     ) where
 
 import Data.Aeson (encode)
 
 import System.Log.Lookout.Types
 
+-- | Record an event using logging service.
 record :: String                         -- ^ Logger name.
        -> SentryLevel                    -- ^ Level
        -> String                         -- ^ Message
     ts <- formatTime defaultTimeLocale "%Y-%m-%dT%H:%M:%S%Q" `fmap` getCurrentTime
     return $! upd (newRecord eid msg ts lvl logger)
 
+-- | JSON-encode record data.
 recordLBS :: SentryRecord -> ByteString
 recordLBS = encode
 
+-- | Show basic message on stderr.
 stderrFallback :: SentryRecord -> IO ()
 stderrFallback rec =
     hPutStrLn stderr $ concat
         , srMessage rec
         ]
 
+-- | Crash and burn with record data.
 errorFallback :: SentryRecord -> IO ()
 errorFallback rec = error $ "Error sending record: " ++ show rec
 
+-- | Ignore recording errors.
 silentFallback :: SentryRecord -> IO ()
 silentFallback _ = return ()
 
-disabledLookout :: IO SentryService
-disabledLookout = initLookout "" id undefined undefined
-
-initLookout :: String
-            -> (SentryRecord -> SentryRecord)
-            -> (SentrySettings -> SentryRecord -> IO ())
-            -> (SentryRecord -> IO ())
-            -> IO SentryService
+-- | Initialize event service.
+initLookout :: String                                    -- ^ Sentry DSN
+            -> (SentryRecord -> SentryRecord)            -- ^ Default fields updater. Use 'id' if not needed.
+            -> (SentrySettings -> SentryRecord -> IO ()) -- ^ Event transport from Looklout.Transport.*
+            -> (SentryRecord -> IO ())                   -- ^ Fallback handler.
+            -> IO SentryService                          -- ^ Event service to use in 'register'.
 initLookout dsn d t fb = return
     SentryService { serviceSettings = fromDSN dsn
                   , serviceDefaults = d
                   , serviceFallback = fb
                   }
 
+-- | Disabled service that ignores incoming events.
+disabledLookout :: IO SentryService
+disabledLookout = initLookout "" id undefined undefined
+
+-- | Ask service to store an event.
 register :: SentryService
          -> String
          -> SentryLevel
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.