diff --git a/.travis.yml b/.travis.yml index 609c217..437a17d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,6 @@ # This Travis job script has been generated by a script via # -# haskell-ci '--output=.travis.yml' '--branches=master' 'cabal.project' +# haskell-ci '--output=.travis.yml' '--config=cabal.haskell-ci' 'cabal.project' # # For more information, see https://github.com/haskell-CI/haskell-ci # @@ -115,5 +115,15 @@ script: # Build without installed constraints for packages in global-db - rm -f cabal.project.local; ${CABAL} new-build -w ${HC} --disable-tests --disable-benchmarks all; -# REGENDATA ["--output=.travis.yml","--branches=master","cabal.project"] + # Constraint sets + - rm -rf cabal.project.local + + # Constraint set servant-0.15 + - ${CABAL} new-build -w ${HC} --disable-tests --disable-benchmarks --constraint='servant ==0.15.*' all + + # Constraint set servant-0.16 + - ${CABAL} new-build -w ${HC} --disable-tests --disable-benchmarks --constraint='servant ==0.16.*' all + + +# REGENDATA ["--output=.travis.yml","--config=cabal.haskell-ci","cabal.project"] # EOF diff --git a/README.md b/README.md new file mode 100644 index 0000000..03d6bc7 --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# servant-ekg + +[![Build Status](https://travis-ci.org/haskell-servant/servant-ekg.png)](https://travis-ci.org/haskell-servant/servant-ekg) + +# Servant Performance Counters + +This package lets you track peformance counters for each of your Servant endpoints using EKG. + +# Usage + +Servant-EKG knows how to handle all official Servant combinators out of the box. + +## Instrumenting your API +To use Servant-EKG, you'll need to wrap your WAI application with the Servant-EKG middleware. + +``` +import Network.Wai.Handler.Warp +import System.Metrics +import Servant.Ekg + +wrapWithEkg :: Proxy api -> Server api -> IO Application +wrapWithEkg api server = do + store <- newStore + metrics <- newMVar mempty + + return $ monitorEndpoints api store metrics (serve api server) + +main :: IO () +main = do + let api = ... + server = ... + + app <- wrapWithEkg api server + + run 8080 app +``` + +## Runtime overhead +Instrumenting your API introduces a non-zero runtime overhead, on the order of 200 - 600 µsec depending upon your machine. It's a good idea to run the benchmarks on your intended production platform to get an idea of how large the overhead will be. You'll need to have `wrk` installed to run the benchmarks. + +In general, the runtime overhead should be effectively negligible if your handlers are issuing network requests, such as to databases. If you have handlers that are small, CPU-only, and requested frequently, you will see a performance hit from Servant-EKG. diff --git a/cabal.haskell-ci b/cabal.haskell-ci new file mode 100644 index 0000000..3fd5349 --- /dev/null +++ b/cabal.haskell-ci @@ -0,0 +1,9 @@ +branches: master + +constraint-set servant-0.15 + ghc: >= 8.0 && <8.8 + constraints: servant ==0.15.* + +constraint-set servant-0.16 + ghc: >= 8.0 && <8.8 + constraints: servant ==0.16.* diff --git a/lib/Servant/Ekg.hs b/lib/Servant/Ekg.hs index e8c19f4..bda2d65 100644 --- a/lib/Servant/Ekg.hs +++ b/lib/Servant/Ekg.hs @@ -4,10 +4,10 @@ {-# LANGUAGE FlexibleInstances #-} {-# LANGUAGE KindSignatures #-} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE PolyKinds #-} {-# LANGUAGE RecordWildCards #-} {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeOperators #-} -{-# LANGUAGE PolyKinds #-} module Servant.Ekg where import Control.Concurrent.MVar @@ -116,6 +116,7 @@ instance (KnownSymbol (path :: Symbol), HasEndpoint (sub :: *)) return (p:end, method) _ -> Nothing + instance (KnownSymbol (capture :: Symbol), HasEndpoint (sub :: *)) => HasEndpoint (Capture' mods capture a :> sub) where getEndpoint _ req = @@ -147,8 +148,10 @@ instance HasEndpoint (sub :: *) => HasEndpoint (QueryFlag h :> sub) where instance HasEndpoint (sub :: *) => HasEndpoint (ReqBody' mods cts a :> sub) where getEndpoint _ = getEndpoint (Proxy :: Proxy sub) +#if MIN_VERSION_servant(0,15,0) instance HasEndpoint (sub :: *) => HasEndpoint (StreamBody' mods framing ct a :> sub) where getEndpoint _ = getEndpoint (Proxy :: Proxy sub) +#endif instance HasEndpoint (sub :: *) => HasEndpoint (RemoteHost :> sub) where getEndpoint _ = getEndpoint (Proxy :: Proxy sub) @@ -168,19 +171,17 @@ instance HasEndpoint (sub :: *) => HasEndpoint (WithNamedContext x y sub) where instance ReflectMethod method => HasEndpoint (Verb method status cts a) where getEndpoint _ req = case pathInfo req of [] | requestMethod req == method -> Just ([], method) - _ -> Nothing + _ -> Nothing where method = reflectMethod (Proxy :: Proxy method) instance ReflectMethod method => HasEndpoint (Stream method status framing ct a) where getEndpoint _ req = case pathInfo req of [] | requestMethod req == method -> Just ([], method) - _ -> Nothing + _ -> Nothing where method = reflectMethod (Proxy :: Proxy method) -instance HasEndpoint (Raw) where +instance HasEndpoint Raw where getEndpoint _ _ = Just ([],"RAW") -#if MIN_VERSION_servant(0,8,1) instance HasEndpoint (sub :: *) => HasEndpoint (CaptureAll (h :: Symbol) a :> sub) where getEndpoint _ = getEndpoint (Proxy :: Proxy sub) -#endif diff --git a/servant-ekg.cabal b/servant-ekg.cabal index 76bfac3..6db4619 100644 --- a/servant-ekg.cabal +++ b/servant-ekg.cabal @@ -1,6 +1,6 @@ cabal-version: >=1.10 name: servant-ekg -version: 0.2.1.0 +version: 0.2.2.0 synopsis: Helpers for using ekg with servant description: Helpers for using ekg with servant, e.g.. counters per endpoint. license: BSD3 @@ -24,13 +24,13 @@ library hs-source-dirs: lib build-depends: base >=4.9 && <4.13 - , ekg-core >=0.1.1.6 && <0.2 + , ekg-core >=0.1.1.4 && <0.2 , http-types >=0.12.2 && <0.13 - , servant >=0.15 && <0.17 + , servant >=0.14 && <0.17 , text >=1.2.3.0 && <1.3 , time >=1.6.0.1 && <1.9 , unordered-containers >=0.2.9.0 && <0.3 - , wai >=3.2.2 && <3.3 + , wai >=3.2.0 && <3.3 default-language: Haskell2010 diff --git a/test/Servant/EkgSpec.hs b/test/Servant/EkgSpec.hs index 86848c8..b7d9d0d 100644 --- a/test/Servant/EkgSpec.hs +++ b/test/Servant/EkgSpec.hs @@ -1,28 +1,34 @@ -{-# LANGUAGE CPP #-} -{-# LANGUAGE DataKinds #-} -{-# LANGUAGE DeriveGeneric #-} -{-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE PolyKinds #-} -{-# LANGUAGE TypeFamilies #-} -{-# LANGUAGE TypeOperators #-} +{-# LANGUAGE CPP #-} +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE DeriveGeneric #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE PolyKinds #-} +{-# LANGUAGE RankNTypes #-} +{-# LANGUAGE TypeFamilies #-} +{-# LANGUAGE TypeOperators #-} module Servant.EkgSpec (spec) where import Control.Concurrent import Data.Aeson -import Data.Monoid +import qualified Data.HashMap.Strict as H +import Data.Monoid ((<>)) import Data.Proxy -import qualified Data.HashMap.Strict as H import Data.Text import GHC.Generics -import Network.HTTP.Client (defaultManagerSettings, newManager) +import Network.HTTP.Client (defaultManagerSettings, + newManager) import Network.Wai import Network.Wai.Handler.Warp import Servant import Servant.Client -import Servant.Test.ComprehensiveAPI (comprehensiveAPI) +#if MIN_VERSION_servant(0,15,0) +import Servant.Test.ComprehensiveAPI (comprehensiveAPI) +#else +import Servant.API.Internal.Test.ComprehensiveAPI (comprehensiveAPI) +#endif import System.Metrics -import qualified System.Metrics.Counter as Counter +import qualified System.Metrics.Counter as Counter import Test.Hspec import Servant.Ekg @@ -38,7 +44,7 @@ spec = describe "servant-ekg" $ do let getEp :<|> postEp :<|> deleteEp = client testApi - it "collects number of request" $ do + it "collects number of request" $ withApp $ \port mvar -> do mgr <- newManager defaultManagerSettings let runFn :: ClientM a -> IO (Either ClientError a) @@ -101,11 +107,7 @@ server = helloH :<|> postGreetH :<|> deleteGreetH postGreetH = return -#if MIN_VERSION_servant(0,8,0) deleteGreetH _ = return NoContent -#else - deleteGreetH _ = return () -#endif -- Turn the server into a WAI app. 'serve' is provided by servant, -- more precisely by the Servant.Server module.