InfluxElixir.Telemetry (InfluxElixir v0.1.21)

Copy Markdown View Source

Telemetry event emission for write and query operations.

InfluxElixir.Write.Writer.write/3 (and therefore InfluxElixir.write/3 and every BatchWriter flush) emits the write span; InfluxElixir.query_sql/3, execute_sql/3, query_influxql/3 and query_flux/3 emit the query span. Streaming queries are not spanned.

Events

Write Events

  • [:influx_elixir, :write, :start] — emitted before a write

    • Measurements: %{system_time: integer(), monotonic_time: integer()}

    • Metadata: %{database: binary() | nil, point_count: integer(), bytes: integer()} (bytes is the uncompressed payload size)

  • [:influx_elixir, :write, :stop] — emitted after the client returned

    • Measurements: %{duration: integer(), monotonic_time: integer()}

    • Metadata: start metadata plus result: :ok | :error. A client error tuple is a :stop with result: :error, not an :exception.

  • [:influx_elixir, :write, :exception] — emitted when the client raised

    • Measurements: %{duration: integer(), monotonic_time: integer()}
    • Metadata: start metadata plus kind: atom(), reason: term(), stacktrace: list()

Query Events

  • [:influx_elixir, :query, :start] — emitted before a query

  • [:influx_elixir, :query, :stop] — emitted after the client returned

    • Measurements: %{duration: integer(), monotonic_time: integer()}

    • Metadata: start metadata plus result: :ok | :error and, for list results, row_count: integer()

  • [:influx_elixir, :query, :exception] — emitted when the client raised

    • Measurements: %{duration: integer(), monotonic_time: integer()}
    • Metadata: start metadata plus kind: atom(), reason: term(), stacktrace: list()

Usage

Attach handlers using :telemetry.attach/4 or :telemetry.attach_many/4:

:telemetry.attach(
  "my-handler",
  [:influx_elixir, :write, :stop],
  fn _event, measurements, metadata, _config ->
    Logger.info("Write completed in #{measurements.duration}ns",
      database: metadata.database
    )
  end,
  nil
)

To wrap operations automatically, use the span helpers:

InfluxElixir.Telemetry.span_write(%{database: "mydb", point_count: 1, bytes: 42},
  fn -> do_write() end
)

Summary

Functions

query_exception(duration, metadata)

Emits the [:influx_elixir, :query, :exception] telemetry event.

query_start(metadata)

Emits the [:influx_elixir, :query, :start] telemetry event.

query_stop(duration, metadata)

Emits the [:influx_elixir, :query, :stop] telemetry event.

span_query(metadata, fun)

Wraps a query operation with telemetry start, stop, and exception events.

span_write(metadata, fun)

Wraps a write operation with telemetry start, stop, and exception events.

write_exception(duration, metadata)

Emits the [:influx_elixir, :write, :exception] telemetry event.

write_start(metadata)

Emits the [:influx_elixir, :write, :start] telemetry event.

write_stop(duration, metadata)

Emits the [:influx_elixir, :write, :stop] telemetry event.

Functions

query_exception(duration, metadata)

@spec query_exception(integer(), map()) :: :ok

Emits the [:influx_elixir, :query, :exception] telemetry event.

Parameters

  • duration - elapsed time in native units (from System.monotonic_time/0)
  • metadata - map with :database, :transport, :kind, :reason, and :stacktrace keys

Examples

start = System.monotonic_time()
try do
  SQL.query(conn, sql)
rescue
  e ->
    InfluxElixir.Telemetry.query_exception(
      System.monotonic_time() - start,
      %{database: "mydb", transport: :http, kind: :error,
        reason: e, stacktrace: __STACKTRACE__}
    )
    reraise e, __STACKTRACE__
end

query_start(metadata)

@spec query_start(map()) :: :ok

Emits the [:influx_elixir, :query, :start] telemetry event.

Parameters

  • metadata - map with :database and :transport keys

Examples

InfluxElixir.Telemetry.query_start(%{database: "mydb", transport: :http})

query_stop(duration, metadata)

@spec query_stop(integer(), map()) :: :ok

Emits the [:influx_elixir, :query, :stop] telemetry event.

Parameters

  • duration - elapsed time in native units (from System.monotonic_time/0)
  • metadata - map with :database, :transport, and :row_count keys

Examples

start = System.monotonic_time()
# ... perform query ...
InfluxElixir.Telemetry.query_stop(System.monotonic_time() - start,
  %{database: "mydb", transport: :http, row_count: 42}
)

span_query(metadata, fun)

@spec span_query(map(), (-> result)) :: result when result: term()

Wraps a query operation with telemetry start, stop, and exception events.

Emits [:influx_elixir, :query, :start] before calling fun, then either [:influx_elixir, :query, :stop] on success or [:influx_elixir, :query, :exception] on failure. Re-raises any exception after emitting the exception event.

Parameters

  • metadata - map with at minimum :database and :transport keys
  • fun - zero-arity function that performs the query

Examples

InfluxElixir.Telemetry.span_query(
  %{database: "mydb", transport: :http},
  fn -> SQL.query(conn, "SELECT * FROM cpu") end
)

span_write(metadata, fun)

@spec span_write(map(), (-> result)) :: result when result: term()

Wraps a write operation with telemetry start, stop, and exception events.

Emits [:influx_elixir, :write, :start] before calling fun, then either [:influx_elixir, :write, :stop] on success or [:influx_elixir, :write, :exception] on failure. Re-raises any exception after emitting the exception event.

Parameters

  • metadata - map with at minimum :database, :point_count, and :bytes keys
  • fun - zero-arity function that performs the write

Examples

InfluxElixir.Telemetry.span_write(
  %{database: "mydb", point_count: 3, bytes: 128},
  fn -> Writer.write(conn, line_protocol) end
)

write_exception(duration, metadata)

@spec write_exception(integer(), map()) :: :ok

Emits the [:influx_elixir, :write, :exception] telemetry event.

Parameters

  • duration - elapsed time in native units (from System.monotonic_time/0)
  • metadata - map with :database, :kind, :reason, and :stacktrace keys

Examples

start = System.monotonic_time()
try do
  Writer.write(conn, data)
rescue
  e ->
    InfluxElixir.Telemetry.write_exception(
      System.monotonic_time() - start,
      %{database: "mydb", kind: :error, reason: e, stacktrace: __STACKTRACE__}
    )
    reraise e, __STACKTRACE__
end

write_start(metadata)

@spec write_start(map()) :: :ok

Emits the [:influx_elixir, :write, :start] telemetry event.

Parameters

  • metadata - map with :database, :point_count, and :bytes keys

Examples

InfluxElixir.Telemetry.write_start(%{database: "mydb", point_count: 1, bytes: 42})

write_stop(duration, metadata)

@spec write_stop(integer(), map()) :: :ok

Emits the [:influx_elixir, :write, :stop] telemetry event.

Parameters

  • duration - elapsed time in native units (from System.monotonic_time/0)
  • metadata - map with :database, :point_count, :bytes, and :compressed_bytes keys

Examples

start = System.monotonic_time()
# ... perform write ...
InfluxElixir.Telemetry.write_stop(System.monotonic_time() - start,
  %{database: "mydb", point_count: 1, bytes: 42, compressed_bytes: 30}
)