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

Callbacks

Returns a supervisable connection child_spec.

Returns the connection configuration.

Deletes data from an InfluxDB bucket.

Pings the connection server.

Executes a reading query.

Checks the status of the connection server.

Determines the version of the connection server.

Executes a writing query.

Link to this section Types

@type delete_request() :: %{
  :start => binary(),
  :stop => binary(),
  optional(:predicate) => binary()
}
@type e_version_mismatch() :: {:error, :version_mismatch}
@type precision() ::
  :hour
  | :minute
  | :second
  | :millisecond
  | :microsecond
  | :nanosecond
  | :rfc3339

Link to this section Callbacks

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

Returns a supervisable connection child_spec.

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

Returns the connection configuration.

@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.

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

Pings the connection server.

@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
@callback status(opts :: Keyword.t()) :: :ok | :error | e_version_mismatch()

Checks the status of the connection server.

Only available with InfluxDB v1.x connections.

@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.

@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.