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

Specs

precision() ::
  :hour
  | :minute
  | :second
  | :millisecond
  | :microsecond
  | :nanosecond
  | :rfc3339

Specs

query_type() :: Instream.Query.t() | String.t()

Link to this section Callbacks

Specs

__log__(log_entry()) :: log_entry()

Sends a log entry to all configured loggers.

Specs

child_spec(_ignored :: term()) :: Supervisor.child_spec()

Returns a supervisable connection child_spec.

Specs

config(keys :: nil | [term(), ...]) :: Keyword.t()

Returns the connection configuration.

Specs

execute(query :: query_type(), opts :: Keyword.t()) :: any()

Executes a query.

Specs

ping(host :: String.t(), opts :: Keyword.t()) :: :pong | :error

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

query(query :: String.t(), opts :: Keyword.t()) :: any()

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

version(host :: String.t(), opts :: Keyword.t()) :: String.t() | :error

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

write(payload :: map() | [map()], opts :: Keyword.t()) :: any()

Executes a writing query.

Options:

  • async: pass true to execute the write asynchronously
  • database: write data to a database differing from the point database
  • precision: 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)