Extensions: Health and Geo

View Source

Extensions are pieces of non-critical functionality going over the NervesHub WebSocket. They are separated out under the Extensions mechanism so that the client can happily ignore anything extension-related in service of keeping firmware updates healthy. That is always the top priority.

There are two extensions currently:

  • Health reports device metrics, alarms, metadata and similar.
  • Geo provides GeoIP information and allows slotting in a better source.

Your NervesHub server controls enabling and disabling extensions to allow you to switch them off if they impact operations.

Health

You can add your own metrics, metadata and alarms.

The default set of metrics used by the Health.DefaultReport are:

And one optional metric set:

You can also create your own metric sets by implementing the NervesHubLink.Extensions.Health.MetricSet behaviour.

If a library you are using provides a metric set, you can add it to the list of metrics, but please ensure to include all the metric sets you want to use. If you want to include the full default set, you can use :default or :defaults in your metric set list.

eg.

config :nerves_hub_link,
  health: [
    metric_sets: [
      :defaults,
      MyApp.HealthMetrics,
      ALibrary.BatteryMetrics
    ]
  ]

If you only want to use some of the default metrics, you can specify them explicitly:

config :nerves_hub_link,
  health: [
    metric_sets: [
      NervesHubLink.Extensions.Health.MetricSet.CPU,
      NervesHubLink.Extensions.Health.MetricSet.Memory
      # the disk metrics have been excluded
    ]
  ]

And if you don't want to use any metric sets, you can set the metric_sets option to an empty list.

config :nerves_hub_link,
  health: [
    metric_sets: []
  ]

If you want to add custom metadata to the default health report, you can specify it with:

config :nerves_hub_link,
  health: [
    # metadata is added with a key and MFA
    # the function should return a string
    metadata: %{
      "placement" => {CatCounter, :venue, []}
    }
  ]

Or you can implement a completely custom reporting module by implementing NervesHubLink.Extensions.Health.Report and configuring it:

config :nerves_hub_link,
  health: [
    report: CatCounter.MyHealthReport
  ]

The Health.DefaultReport also sends the current system alarms to the connected NervesHub platform.

A built in default is to filter out the :disk_almost_full alarm for the / mount. This alarm is generated by Erlang upon startup, based on how the read-only root filesystem is sized to fit only whats included in the firmware.

You can customize the mounts ignored with:

config :nerves_hub_link,
  health: [
    alarms: [
      ignore_disk_full_mounts: [
        "/a_different_mount"
      ]
    ]
  ]

Specifying a list of mounts to ignore will override the default /, so make sure to include that in the list if you want to continue ignoring / while also adding other mounts.

Geolocation

It is intended to be easy to replace the default Geo Resolver with your own. Maybe you have a GPS module or can resolve a reasonably precise location via LTE. Just change config:

config :nerves_hub_link,
  geo: [
    resolver: CatCounter.MyResolver
  ]

Your module only needs to implement a single function, see NervesHubLink.Extensions.Geo.Resolver for details.

Alarms

The default health report uses :alarm_handler, but we recommend the alarmist library for improved alarms handling.