ExInsights

Hex.pm

Elixir client library to log telemetry data on Azure Application Insights.

Installation

Install from hex by adding ex_insights to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_insights, "~> 0.8"}
  ]
end

You then need to start the ExInsights.Supervisor in your supervision tree. Example:

# inside the init/1 callback of a supervisor in your supervision tree (or start/2 of application.ex)

children = [
  # ...
  {ExInsights.Supervisor, instrumentation_key: "0000-1111-2222-3333"}
]

Supervisor.init(children, strategy: :one_for_one)

Note

For migrating to 0.8.x and later versions read the migration instructions below

Configuration

ExInsights supports the following configuration options you can set when starting the ExInsights.Supervisor

Example:

options = [
  instrumentation_key: "0000-1111-2222-3333",
  flush_interval_secs: 30
]

children = [
  # ...
  {ExInsights.Supervisor, options}
]

Supervisor.init(children, strategy: :one_for_one)

Usage

Basic Usage

All public tracking methods are under the ExInsights module. Examples:

# will post a click custom_event to azure
ExInsights.track_event("click")

# with custom defined property "type" and measurement "count"
ExInsights.track_event("click", %{type: "button"}, %{count: 2})

# send custom metric data. Does not support aggregated data (count/stdDev, min, max)
ExInsights.track_metric("bananas", 10)

# log arbitrary data
ExInsights.track_trace("1-2-3 boom", :warning)

# log time taken for requests to external resources, eg. database or http service calls
ExInsights.track_dependency("get_user_balance", "http://my.api/get_balance/aviator1", 1500, true, "user", "my.api")

# log telemetry data about the incoming request processed by the application
ExInsights.track_request("homepage", "http://my.site.com/", "HomePageComponent", 85, 200, true)

For more details and optional arguments look at the ExInsights module documentation.

Alternative usage

You can also decorate methods you need to track using decorators.

# Make sure to add the following line before using any decorators
use ExInsights.Decoration.Attributes

# add the @decorate track_xxx() attribute right above each function you need to track

@decorate track_event() # will log the "update_user_email" event in AppInsights on function entry
def update_user_email(email, user) do
  # ...
end

@decorate track_dependency("user-actions") # put under dependency type:user-actions in AppInsights UI
def login_user(user) do
  # ... maybe call external api here
end

@decorate track_exception() # will track errors and exits
def dangerous_stuff do
  # ... do work that may fail
end

Migrating from 0.7.x to 0.8.x

In order to make the library configuration more flexible and in accordance to library development guidelines for configuration, support for configuring the client by setting options directly inside config.exs files was dropped and configuration now needs to happen on supervisor startup.

For example instead of globally configuring ex_insights inside config.exs,

# No longer supported
config :ex_insights,
  instrumentation_key: "0000-1111-2222-3333"

you now need to pass this option to the ExInsights.Supervisor directly instead

children = [
  ...
  {ExInsights.Supervisor, instrumentation_key: "0000-1111-2222-3333"}
]

If you need to keep reading this value from your config files you can still do something like this

# in config.exs
config :my_app, ex_insights_instrumentation_key: "0000-1111-2222-3333"

# in you supervisor.ex file
def read_instrumentation_key_from_config do
  Application.get_env(:my_app, :ex_insights_instrumentation_key)
end

def init(_) do
  ...
  children = [
    # ...
    {ExInsights.Supervisor, instrumentation_key: read_instrumentation_key_from_config()}
  ]
end

Inner workings