@@ -3,6 +3,24 @@
33{-# LANGUAGE RankNTypes #-}
44{-# LANGUAGE RecordWildCards #-}
55{-# LANGUAGE ScopedTypeVariables #-}
6+-- | Includes a scribe that can be used to log structured, JSON log
7+-- messages to ElasticSearch. These logs can be explored easily using
8+-- <https://www.elastic.co/products/kibana kibana> or your tool of
9+-- choice.
10+--
11+-- == __Important Note on Index Settings__
12+--
13+-- 'defaultEsScribeCfg' inherits a set of default index settings from
14+-- the @bloodhound@ package. These settings at this time of writing
15+-- set the indices up to have 3 shards and 2 replicas. This is an
16+-- arguably reasonable default setting for production but may cause
17+-- problems for development. In development, your cluster may be
18+-- configured to seek a write quorum greater than 1. If you're running
19+-- ElasticSearch on a single node, this could cause your writes to
20+-- wait for a bit and then fail due to a lack of quorum. __For development, we recommend setting your replica count to 0 or modifying your write quorum settings__. For production, we recommend reading the
21+-- <https://www.elastic.co/guide/en/elasticsearch/guide/current/scale.html ElasticSearch Scaling Guide> and choosing the appropriate settings,
22+-- keeping in mind that you can chage replica counts on a live index
23+-- but that changing shard counts requires recreating the index.
624module Katip.Scribes.ElasticSearch
725 (-- * Building a scribe
826 mkEsScribe