Uplink (uplink v0.1.2) View Source

A simple abstraction for standardized observability with telemetry and more.

Uplink provides a simple abstraction for configuring observability for libraries and applications. The heart of Uplink is the Uplink.Monitor which provides a standard template for common observability needs such as creating Telemetry.Metrics definitions, telemetry pollers, or setting up other custom observability requirements.

The most common challenge when getting started with telemetry is understanding where to start, what all the libraries do, and how they all fit together. This creates a high learning curve while leaving a huge gap at organizations where most developers just want a simple "drop-in" solution for observability that meets the org's requirements.

Uplink can be used on its own in simple personal projects or as the basis for a standard "drop-in" library with a simple abstraction containing standard monitors for your organization, such as your Telemetry.Metrics reporter of choice, BEAM VM measurements, or Phoenix measurements, all conforming to your org's metric naming conventions or other standard practices.

Usage

# application supervisor
children = [
  {
    Uplink, [
      monitors: [
        {MyMonitors.Ecto, [:my_repo]},
        Uplink.Monitors.VM
      ],
      pollers: [
        {10, [{TestModule, :test_emitter, []}]}
      ],
      metric_definitions: [
        Telemetry.Metrics.counter("poller.test.event.lasers")
      ],
      reporters: [
        Telemetry.Metrics.ConsoleReporter
      ]
    ]
  }
]

Link to this section Summary

Types

An MFA tuple for the poller to execute.

A list of t:TelemetryMetrics.t/0 definitions.

A module or two-element tuple consisting of a module and arguments to be supplied to the monitor. Any arguments passed are passed to all callbacks in the monitor.

Valid options. No options are required but a monitor and/or monitor are the minimum required to do anything.

Time in ms between poller executions.

A shorthand specification for listing a number of pollers to be executed at a shared interval.

A module or two-element tuple consisting of a reporter and arguments to be passed to the reporter,

Functions

Returns the child spec for running Uplink under a supervisor.

Link to this section Types

Specs

measurement() :: {module :: module(), function :: atom(), args :: keyword()}

An MFA tuple for the poller to execute.

Specs

metric_definitions() :: [Telemetry.Metrics.t()]

A list of t:TelemetryMetrics.t/0 definitions.

Specs

monitor() :: module() | {module :: module(), args :: keyword()}

A module or two-element tuple consisting of a module and arguments to be supplied to the monitor. Any arguments passed are passed to all callbacks in the monitor.

Specs

monitors() :: [monitor()]

Specs

option() ::
  {:metric_definitions, metric_definitions()}
  | {:monitors, monitors()}
  | {:poller_specs, poller_specs()}
  | {:reporters, reporter_specs()}

Specs

options() :: [option()]

Valid options. No options are required but a monitor and/or monitor are the minimum required to do anything.

Specs

period() :: pos_integer()

Time in ms between poller executions.

Example: :timer.seconds(5)

Specs

poller_spec() :: {period(), [measurement()]}

A shorthand specification for listing a number of pollers to be executed at a shared interval.

Example: {:timer.seconds(5), [{MyApp.Telemetry, :emit_stats, []}]}

Specs

poller_specs() :: [poller_spec()]

Specs

reporter_spec() :: module() | {module :: module(), args :: keyword()}

A module or two-element tuple consisting of a reporter and arguments to be passed to the reporter,

Example: {TelemetryMetricsPrometheus, [port: 9568]}

Specs

reporter_specs() :: [reporter_spec()]

Link to this section Functions

Specs

child_spec(options()) :: Supervisor.child_spec()

Returns the child spec for running Uplink under a supervisor.

Example:

children = [
  {Uplink, options}
]

See options/0 for a list of available options.