Instream v1.0.0 Instream.Connection behaviour View Source
Defines a connection to an InfluxDB instance.
Connection Definition
defmodule MyConnection do
use Instream.Connection, otp_app: :my_app
end
This connection will fetch it's configuration from the application environment
as defined by :otp_app
. As an alternative you can define the configuration
in the module definition itself:
defmodule MyConnection do
use Instream.Connection,
config: [
host: "influxdb.example.com",
scheme: "http"
]
end
Both inline and :otp_app
configuration can be mixed. In this case the
application configuration will overwrite any inline values.
For more information on how to configure your connection please refer to
the documentation of Instream.Connection.Config
.
Ping / Status / Version
To validate a connection you can send ping requests to the server:
MyConnection.ping()
The response will be :pong
on success or :error
on any failure.
To ping "a host other than the first in your configuration" you can pass it explicitly:
MyConnection.ping("some.host.name")
All values necessary to ping the host (scheme, port, ...) will be taken from the connection used. It does not matter whether the host is configured in that connection or not.
To get InfluxDB to verify the status of your server you can send a status call:
MyConnection.status()
MyConnection.status("some.host.name")
If you are interested in the version of InfluxDB your server is reporting you can request it:
MyConnection.version()
MyConnection.version("some.host.name")
If the version if undetectable (no header returned) it will be
reported as "unknown"
. If the host is unreachable or an error occurred
the response will be :error
.
Link to this section Summary
Callbacks
Sends a log entry to all configured loggers.
Returns a supervisable connection child_spec.
Returns the connection configuration.
Executes a query.
Pings a server.
Executes a reading query.
Checks the status of a connection.
Determines the version of an InfluxDB host.
Executes a writing query.
Link to this section Types
Specs
log_entry() :: Instream.Log.PingEntry.t() | Instream.Log.QueryEntry.t() | Instream.Log.StatusEntry.t() | Instream.Log.WriteEntry.t()
Specs
precision() :: :hour | :minute | :second | :millisecond | :microsecond | :nanosecond | :rfc3339
Specs
query_type() :: Instream.Query.t() | String.t()
Link to this section Callbacks
Specs
Sends a log entry to all configured loggers.
Specs
child_spec(_ignored :: term()) :: Supervisor.child_spec()
Returns a supervisable connection child_spec.
Specs
Returns the connection configuration.
Specs
execute(query :: query_type(), opts :: Keyword.t()) :: any()
Executes a query.
Specs
Pings a server.
By default the first server in your connection configuration will be pinged.
The server passed does not necessarily need to belong to your connection. Only the connection details (scheme, port, ...) will be used to determine the exact url to send the ping request to.
Specs
Executes a reading query.
Options:
method
: whether to use a "GET" or "POST" request (as atom)precision
: return data with a "precision" other than:rfc3339
Specs
status(opts :: Keyword.t()) :: :ok | :error
Checks the status of a connection.
Specs
Determines the version of an InfluxDB host.
The version will be retrieved using a :ping
query and extract the returned
X-Influxdb-Version
header. If the header is missing the version will be
returned as "unknown"
.
Specs
Executes a writing query.
Options:
async
: passtrue
to execute the write asynchronouslydatabase
: write data to a database differing from the point databaseprecision
: write points with a "precision" other than:nanosecond
retention_policy
: write data to your database with a specific retention policy, only affects writes using the line protocol (Instream.Writer.Line
, default if unconfigured)