View Source Snap (Snap v0.9.0)
Snap is split into a few key modules:
Snap.Cluster
- clusters are wrappers around the Elasticsearch HTTP API. We use these to perform low-level HTTP requests.Snap.Indexes
- a convenience wrapper around the Elasticsearch indexes APIs, allowing the creation, deleting and aliasing of indexes, along with hotswap functionality to bulk load documents into an aliased index, switching to it atomically.Snap.Document
- a convenience wrapper around the Document APIs, allowing the creating, updating and deleting individual documents.Snap.Search
- for performing searchesSnap.Multi
- for performing multiple searches in a single querySnap.Bulk
- a convenience wrapper around bulk operations, usingStream
to stream actions (such asSnap.Bulk.Action.Create
) to be performed against theSnap.Cluster
.
Additionally, there are other supporting modules:
Snap.HTTPClient
- defines how to send HTTP requests. Comes with a built in adapter forFinch
(Snap.HTTPClient.Adapters.Finch
)Snap.Auth
- defines how an HTTP request is modified to include authentication headers.Snap.Auth.Plain
implements HTTP Basic Auth.Snap.Cluster.Namespace
- for isolating cluster and processes to work on separate indexes
Set up
Snap.Cluster
is a wrapped around an Elasticsearch cluster. We can define
it like so:
defmodule MyApp.Cluster do
use Snap.Cluster, otp_app: :my_app
end
The configuration for the cluster can be defined in your config:
config :my_app, MyApp.Cluster,
url: "http://localhost:9200",
username: "username",
password: "password"
Or you can load it dynamically by implementing Snap.Cluster.init/1
.
Each cluster defines start_link/1
which must be invoked before using the
cluster and optionally accepts an explicit config. It creates the
supervision tree, including the connection pool.
Include it in your application:
def start(_type, _args) do
children = [
{MyApp.Cluster, []}
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
Config
The following configuration options are supported:
url
- the URL of the Elasticsearch HTTP endpoint (required)username
- the username used to access the clusterpassword
- the password used to access the clusterauth
- the auth module used to configure the HTTP authentication headers (defaults toSnap.Auth.Plain
)http_client_adapter
- the adapter that will be used to send HTTP requests. CheckSnap.HTTPClient
for more information. (defaults toSnap.HTTPClient.Adapters.Finch
)telemetry_prefix
- the prefix of the telemetry events (defaults to[:my_app, :snap]
)index_namespace
- seeSnap.Cluster.Namespace
for details (defaults tonil
)
Telemetry
Snap supports sending Telemetry
events on each HTTP request. It sends one
event per query, of the name [:my_app, :snap, :request]
.
The telemetry event has the following measurements:
response_time
- how long the request took to returndecode_time
- how long the response took to decode into a map or exceptiontotal_time
- how long everything took in total
In addition, the metadata contains a map of:
method
- the HTTP method usedpath
- the path requestedport
- the port requestedhost
- the host requestedheaders
- a list of the headers sentbody
- the body sentresult
- the result returned to the user
Testing
See Snap.Test
for details.