Log messages to an ETS table

[changelog]
added: ability to log messages to ETS
added: tests
added: README with examples
added: missing dev config file
added: travis config
added: travis status badge to README
added: MIT licence
added: mix.exs settings for publishing

.formatter.exs

@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

.gitignore

@@ -0,0 +1,117 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Ignore package tarball (built via "mix hex.build").
+logger_ets_backend-*.tar
+
+### https://raw.github.com/github/gitignore/ec246076319913acee4aaeef8caf86b78e586e7a/Global/macOS.gitignore
+
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+
+### https://raw.github.com/github/gitignore/ec246076319913acee4aaeef8caf86b78e586e7a/Global/Emacs.gitignore
+
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+
+# directory configuration
+.dir-locals.el
+
+
+### https://raw.github.com/github/gitignore/ec246076319913acee4aaeef8caf86b78e586e7a/Erlang.gitignore
+
+.eunit
+deps
+*.o
+*.beam
+*.plt
+erl_crash.dump
+ebin/*.beam
+rel/example_project
+.concrete/DEV_MODE
+.rebar
+
+

.travis.yml

@@ -0,0 +1,5 @@
+language: elixir
+elixir:
+  - '1.8.1'
+otp_release:
+  - '21.1.1'

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented on this page.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2019-06-16
+### Added
+- Initial project release

LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2019 @OldhamMade
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice (including the
+next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,119 @@
+# LoggerEtsBackend
+
+[![current build status on Travis-CI.org][build_status]][1]
+
+A simple `Logger` backend which writes logs to an ETS table.
+It does not create or manage the table for you; you must do
+this external to the logging app.
+
+`LoggerEtsBackend` borrows heavily from [`LoggerFileBackend`][2], and
+therefore acts much the same way.
+
+## Rationale
+
+The primary use-case for this backend is _not_ for persistent logs,
+but for temporary logs that may need to be inspected at run-time by
+the system itself. By pushing log messages to an ETS table, data
+can be quickly searched using `match_spec`s based on message contents
+or the metadata stored along with the entry.
+
+## Configuration
+
+`LoggerEtsBackend` is a custom backend for the elixir `:logger`
+application. This backend can only log to a single ETS table, so there
+must be one `:logger` backend configured for each log file we need. Each
+backend has a name like `{LoggerEtsBackend, id}`, where `id` is any
+elixir term (usually an atom).
+
+**Note:** tables use for logging are recommented to be configured with the
+`:ordered_set` and `:public` options.
+
+### Configuration Example
+
+```elixir
+config :logger,
+  backends: [{LoggerEtsBackend, :inspection_log}]
+
+# configuration for the {LoggerEtsBackend, :critical_log} backend
+config :logger, :critical_log,
+  table: :critical_table,
+  level: :error
+```
+
+## Usage
+
+`LoggerEtsBackend` supports the following configuration values:
+
+* `table` - the table name to push log tuples to
+* `level` - the logging level for the backend
+* `metadata` - the metadata to include
+* `metadata_filter` - metadata terms which must be present in order to log
+
+**Note:** It is recommended that `metadata_filter` is set for this
+backend, to ensure only a small subset of log entries are captured.
+
+### Examples
+
+#### Runtime configuration
+
+```elixir
+# some process starts an ets table
+:ets.new(:debug_messages, [:ordered_set, :public, :named_table])
+...
+Logger.add_backend {LoggerFileBackend, :debug}
+Logger.configure_backend {LoggerFileBackend, :debug},
+  table: :debug_messages,
+  metadata: ...,
+  metadata_filter: ...
+```
+
+#### Application config for multiple log files
+
+```elixir
+config :logger,
+  backends: [{LoggerEtsBackend, :info},
+             {LoggerEtsBackend, :error}]
+
+config :logger, :info,
+  table: :info_messages,
+  level: :info
+
+config :logger, :error,
+  table: :error_messages,
+  level: :error
+```
+
+#### Filter out metadata
+
+This example removes all the default metadata and only keeps the
+`:module` name which issued the log message.
+
+```elixir
+config :logger,
+  backends: [{LoggerEtsBackend, :info}]
+
+config :logger, :info,
+  table: :info_messages,
+  level: :info,
+  metadata: [application: :ui]
+```
+
+#### Filtering logging by specifying metadata terms
+
+This example only logs `:info` statements originating from the `:ui`
+OTP app. The `:application` metadata key is auto-populated by `Logger`.
+
+```elixir
+config :logger,
+  backends: [{LoggerEtsBackend, :ui}]
+
+config :logger, :ui,
+  table: :ui_messages,
+  level: :info,
+  metadata_filter: [application: :ui]
+```
+
+
+[1]: https://travis-ci.org/OldhamMade/logger_ets_backend
+[2]: https://github.com/onkel-dirtus/logger_file_backend
+[build_status]: https://travis-ci.org/OldhamMade/logger_ets_backend.svg?branch=master

config/config.exs

@@ -0,0 +1,30 @@
+# This file is responsible for configuring your application
+# and its dependencies with the aid of the Mix.Config module.
+use Mix.Config
+
+# This configuration is loaded before any dependency and is restricted
+# to this project. If another project depends on this project, this
+# file won't be loaded nor affect the parent project. For this reason,
+# if you want to provide default values for your application for
+# third-party users, it should be done in your "mix.exs" file.
+
+# You can configure your application as:
+#
+#     config :logger_ets_backend, key: :value
+#
+# and access this configuration in your application as:
+#
+#     Application.get_env(:logger_ets_backend, :key)
+#
+# You can also configure a third-party app:
+#
+#     config :logger, level: :info
+#
+
+# It is also possible to import configuration files, relative to this
+# directory. For example, you can emulate configuration per environment
+# by uncommenting the line below and defining dev.exs, test.exs and such.
+# Configuration from the imported file will override the ones defined
+# here (which is why it is important to import them last).
+#
+import_config "#{Mix.env()}.exs"

config/dev.exs

@@ -0,0 +1,3 @@
+use Mix.Config
+
+config :logger, backends: []

config/test.exs

@@ -0,0 +1,3 @@
+use Mix.Config
+
+config :logger, backends: []