Instream v2.2.1

View Source Instream.Connection behaviour (Instream v2.2.1)

Defines a connection to an InfluxDB instance.

connection-definition

 Connection Definition 

defmodule MyConnection do
  use Instream.Connection, otp_app: :my_app
end

This connection will fetch its 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: [
      version: :v1,
      host: "my.influxdb.host",
      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.

connection-configuration

 Connection Configuration

There are some configuration values that should be checked/changed to get your connection up and running:

  • :auth: the authentication method and credentials
  • :host: the hostname of the server (defaults to "localhost")
  • :port: the port of the server (defaults to 8086)
  • :version: the InfluxDB server version you are using (:v1 or :v2)

Some additional configuration options/requirements depend on the used version:

  • :org: InfluxDB v2.x organization
  • :bucket: InfluxDB v2.x bucket
  • :database: InfluxDB v1.x database

influxdb-v2-x-compatibility-endpoint-influxql-queries

 InfluxDB v2.x Compatibility Endpoint (InfluxQL Queries)

If you are using InfluxQL queries with a :v2 connection you need to set the :database configuration to a pre-mapped database.

Please refer to the official InfluxDB DBRP mapping documentation for details.

Link to this section Summary

Types

delete_request()
e_version_mismatch()
log_entry()
precision()

Callbacks

child_spec(_ignored)

Returns a supervisable connection child_spec.

config(key)

Returns the connection configuration.

delete(payload, opts)

Deletes data from an InfluxDB bucket.

ping(opts)

Pings the connection server.

query(query, opts)

Executes a reading query.

status(opts)

Checks the status of the connection server.

version(opts)

Determines the version of the connection server.

write(payload, opts)

Executes a writing query.

Link to this section Types

Link to this type

delete_request()

View Source 
@type delete_request() :: %{
  :start => binary(),
  :stop => binary(),
  optional(:predicate) => binary()
}
Link to this type

e_version_mismatch()

View Source 
@type e_version_mismatch() :: {:error, :version_mismatch}
Link to this type

log_entry()

View Source 
@type log_entry() ::
  Instream.Log.PingEntry.t()
  | Instream.Log.QueryEntry.t()
  | Instream.Log.StatusEntry.t()
  | Instream.Log.WriteEntry.t()
Link to this type

precision()

View Source 
@type precision() ::
  :hour
  | :minute
  | :second
  | :millisecond
  | :microsecond
  | :nanosecond
  | :rfc3339

Link to this section Callbacks

Link to this callback

child_spec(_ignored)

View Source 
@callback child_spec(_ignored :: term()) :: Supervisor.child_spec()

Returns a supervisable connection child_spec.

Link to this callback

config(key)

View Source 
@callback config(key :: atom() | nil) :: Keyword.t() | term()

Returns the connection configuration.

Link to this callback

delete(payload, opts)

View Source 
@callback delete(payload :: delete_request(), opts :: Keyword.t()) :: any()

Deletes data from an InfluxDB bucket.

Options:

  • bucket: use a bucket differing from the connection config for deleting
  • org: use an organization differing from the connection config for deleting

Only available with InfluxDB v2.x connections.

Link to this callback

ping(opts)

View Source 
@callback ping(opts :: Keyword.t()) :: :pong | :error

Pings the connection server.

Link to this callback

query(query, opts)

View Source 
@callback query(query :: String.t(), opts :: Keyword.t()) :: any()

Executes a reading query.

Options:

  • database: use a database differing from the connection config for reading
  • method: whether to use a :get or :post request
  • org: use an organization differing from the connection config for reading
  • precision: return data with a "precision" other than :rfc3339
Link to this callback

status(opts)

View Source 
@callback status(opts :: Keyword.t()) :: :ok | :error | e_version_mismatch()

Checks the status of the connection server.

Only available with InfluxDB v1.x connections.

Link to this callback

version(opts)

View Source 
@callback version(opts :: Keyword.t()) :: String.t() | :error

Determines the version of the connection server.

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 callback

write(payload, opts)

View Source 
@callback write(
  payload :: Instream.Encoder.Line.point() | [Instream.Encoder.Line.point()],
  opts :: Keyword.t()
) :: any()

Executes a writing query.

Usable options depend on the writer module configured.