Hooks carried within an Env, allowing ad-hoc injection of different behaviour during Amazonka's request/response cycle. Hooks are currently experimental, but Amazonka uses the Hooks API to implement its default logging, and you can add your own behaviour here as well. Some examples of things hooks can do:

• Log all requests Amazonka makes to a separate log, in order to audit which IAM permissions your program actually needs (see requestHook);

  {-# LANGAUGE OverloadedLabels #-}
  import Amazonka
  import Amazonka.Env.Hooks
  import Data.Generics.Labels ()

  main :: IO ()
  main = do
    env <- newEnv discover
      <&> #hooks %~ requestHook (addAWSRequestHook $ \_env req -> req <$ logRequest req)
    ...

  logRequest :: AWSRequest a => a -> IO ()
  logRequest = ...
  

• Inject a Trace ID for AWS X-Ray, into each request before it is signed and sent (see configuredRequestHook); and

  {-# LANGAUGE OverloadedLabels #-}
  import Amazonka
  import Amazonka.Env.Hooks
  import Data.Generics.Labels ()

  main :: IO ()
  main = do
    env <- newEnv discover
      <&> #hooks %~ configuredRequestHook (addHook $ \_env req -> req & #headers %~ addXRayIdHeader)
    ...

  -- The actual header would normally come from whatever calls into your program,
  -- or you would randomly generate one yourself (hooks run in IO).
  addXRayIdHeader :: [Header] -> [Header]
  addXRayIdHeader = ...
  

• Selectively silence certain expected errors, such as DynamoDB's ConditionalCheckFailedException (errorHook and silenceError)

  {-# LANGAUGE OverloadedLabels #-}
  import Amazonka
  import Amazonka.Env.Hooks
  import qualified Amazonka.DynamoDB as DynamoDB
  import Data.Generics.Labels ()

  main :: IO ()
  main = do
    env <- newEnv discover
    putItemResponse <- runResourceT $
      send
        (env & #hooks %~ errorHook (silenceError DynamoDB._ConditionalCheckFailedException))
        (DynamoDB.newPutItem ...)
    ...
  

Most functions with names ending in Hook (requestHook, etc.) are intended for use with lenses: partially apply them to get a function Hook a -> Hook a that can go on the RHS of (%~) (the lens modify function). You then use functions like addHookFor to selectively extend the hooks used at any particular time.

Names ending in _ (Hook_, addHookFor_, etc.) concern hooks that return () instead of the hook's input type. These hooks respond to some event but lack the ability to change Amazonka's behaviour; either because it is unsafe to do so, or because it is difficult to do anything meaningful with the updated value.

The request/response flow for a standard send looks like this:

    send (req :: AWSRequest a => a)
                 |
                 V
        Run Hook: request
                 |
                 V
Amazonka: configure req into "Request a"
 (Amazonka-specific HTTP request type)
                 |
                 V
    Run Hook: configuredRequest
                 |
                 V
Amazonka: sign request, turn into standard
    Network.HTTP.Client.Request
                 |
                 +-<---------------------------------.
                 V                                   |
    Run Hook: signedRequest                          |
                 |                                   |
                 V                                   |
    Run Hook: clientRequest                          |
                 |                                   |
                 V                                   |
    Amazonka: send request to AWS           Run Hook: requestRetry
                 |                                   ^
                 V                                   |
    Run Hook: clientResponse                         |
                 |                                   |
                 V                                   |
    Run Hook: rawResponseBody                        |
                 |                                   |
                 V                                   |
    Amazonka: was error? ------------------.         |
                 |            Yes          |         |
                 |                         V         |
                 | No               Run Hook: error  |
                 |                    (NotFinal)     |
                 |                         |         |
                 +-<-----------------------'         |
                 V                                   |
    Amazonka: should retry? -------------------------'
                 |            Yes
                 | No
                 V
    Amazonka: was error? ------------------.
                 |            Yes          |
                 |                         V
                 | No                      |
                 |                         |
    Run Hook: response              Run Hook: error
                 |                     (Final)
                 |                         |
                 V                         |
    Amazonka: parse response               |
                 |                         |
                 +-<-----------------------'
                 V
    Amazonka: return result