3.0.0 Release (#314)

* Prepare 3.0 development

This commit is designed to prepare for 3.0+ development. In Timber
Elixir 3.0+, integration with other libraries will be done through
additional libraries in order to allow for better dependency management
and compilation guarantees. Timber Elixir 3.0+ will be required for
Elixir 1.7+ support.

All of the integration-specific code has been removed except for the
installer code. The installer code needs to be updated to appropriately
update the mix.exs files with the relevant integration libraries and
use the updated module names.

The weird dependency listing logic has been removed from mix.exs.

The README has also been fixed so that the markdown now renders
correctly.

This fixes the .formatter.exs file to look at the root `lib` folder.

This change adds Elixir 1.7.2 to the list of versions that Travis tests
for.

Addresses #298, fixes #209, fixes #162

* Change supported Elixir versions to ~> 1.4

The Timber library will now only support Elixir versions 1.4 and higher. To use
Timber with Elixir 1.3 (which support was removed for), please use a release
from the 2.x branch.

Supporting only Elixir 1.4+ will allow us to take advantage of the new Jason
library which is easier to maintain support for.

* Remove installer

This removes the installer. This decision was made because the
installer, while valuable, is difficult to maintain and has introduced a
number of bugs for end-users. Manual installation is now the preferred
method.

* Clean up and organize documentation

This organizes the documentation by providing groupings for the events and
contexts so they appear under headers in the ExDoc rendering. It also moves some
of the internal helper modules to not expose any documentation.

* Remove Timber.CurrentContext module

The Timber.CurrentContext module is deprecated and was slated for removal in the
3.x line. Its usecase is now handled by Timber.LocalContext.

* Provide InMemory Logger backend for testing

This provides the InMemory Logger backend for testing purposes. The InMemory
backend was previously only available as the TestLoggerBackend as a test support
module. This moves the module to the library code (instead of test support code)
so any code dependent on the library can utilize the InMemory logger.

The InMemory logger is only intended to be used for testing dependent libraries,
not for production use.

* Remove unused macro skip_min_elixir_version/1

This removes the unused macro skip_min_elixir_version/1 which was only used for
testing the exceptions integration. This has now been moved to the exceptions
integration library.

* Remove unused helper function parse_log_line/1

This removes the unused test helper function `parse_log_line/1`.

* Move FakeHTTPClient to Timber.HTTPClients.Fake

This makes the FakeHTTPClient, which was a testing support module, to
Timber.HTTPClients.Fake so that it can be utilized by dependent code for
testing.

* Add Test Helpers documentation group

This adds the Test Helpers documentation group to properly contain the
Timber.HTTPClients.Fake and Timber.LoggerBackends.InMemory modules which are
designed for dependent code to test with and not for use with production code.

* Prepare 3.0.0-alpha.2 release

This increments the version of the library to prepare the 3.0.0-alpha.2 release
which is needed by the new exceptions library. It fixes some inconsistencies in
the available test helpers for code dependent on the library.

* Clean up configuration files

This cleans up the config.exs to consolidate configuration blocks and remove
unused keys.

* Use the Jason library for JSON encoding

This changes the JSON encoding paths to use Jason instead of Poison. Like
Poison, Jason is a pure Elixir JSON library, but it has a focus on standards
compliance and speed. It is intended to become the default JSON library on a
number of large Elixir projects including Phoenix. Although Poison 4 was
recently released, Poison lingered for nearly a year without critical bug fixes
being addressed. Poison's interface was also inconsistent and poorly documented
for error cases.

With the switch to Jason, Elixir 1.3 and below can no longer be supported since
Jason relies on Elixir 1.4 and above.

This also removes the ability for the end-developer to inject the JSON library
via configuration. While this is a nice concept in theory, it also introduced
the strong chance the library would not correspond to the expected behavior of
the Timber library logic. Removing this ability ensures we know what is
happening in critical code paths.

As part of this change, I had to address the fact that some tests hard-coded
expected JSON output. Poison output small maps as JSON with a deterministic key
order, so tests passed when using Poison, but the library did not publicize this
as a guarantee. Jason does not have the same determinism for small maps. I
changed these tests to decode the JSON payload and test membership and content.

* Remove support for msgpax 1.x

This removes support for msgpax 1.x. The 2.x line introduces a number of
benefits including better error messaging and optimized packing. Continuing to
support the 1.x line introduces too much complexity and variation in what can go
wrong with such a critical dependency.

* Format changelog

This updates the changelog to break some run-on lines

* Prepare v3.0.0-alpha.3 release

* Remove unused configuration functions

This removes configuration functions that were previously used for integrations
and thus are no longer required in the core library.

* Automatically post test coverage results to Coveralls

This uses `mix coveralls.travis` to automatically post test coverage information
to Coveralls using Travis' built-in authentication mechanism.

* Fix automatic posting of Coveralls report

This fixes an error where the incorrect command to generate the
coveralls report was called.

* Reduce max buffer size to 1000

This reduces the max buffer size to 1000 from 5000 to adhere to the
Timber library specification.

* Updates the user-agent field for HTTP requests

This updates the user-agent field for HTTP requests to comply with the
Timber library specification. So the user-agent field will now appear as
`timber-elixir/3.0.0-alpha.3` instead of `Timber Elixir/3.0.0-alpha.3
(HTTP)`.

* Add InchEx for documentation analysis

This adds InchEx for documentation analysis. This is used to check
compliance with the Timber library specification.

* Fix Credo errors

This fixes files to bring them inline with Credo expectations. It also adds
Credo to the Travis runs.

Additionally, the exception module
`Timber.LoggerBackends.HTTP.TimberAPIKeyInvalid` is renamed to
`Timber.InvalidAPIKeyError` in order to comply with Elixir module naming rules
for exception modules (i.e., they need to end in `Error`). It is also
appropriate that it is its own module rather than being nested inside the HTTP
backend.

* Add adherence document for the Timber library specification

This adds the adherence document for the Timber library specification which is a
checklist based on the specification.

* Make Timber.LocalContext public again

The Timber.LocalContext module is actually supposed to be public and it was my
mistake to make it ostensibly private by removing the @moduledoc. Users are
expected to use the get/0 and save/1 functions to transfer context across
process boundaries.

* update for 3.0.0 release

* restrict inch_ex version

* format file

Author: mitchellhenke

.formatter.exs

@@ -1,3 +1,3 @@
 [
-  inputs: ["mix.exs", "apps/*/{config,lib,test}/**/*.{ex,exs}"]
-]
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

.gitignore

@@ -12,6 +12,9 @@
 # Where 3rd-party dependencies like ExDoc output generated docs.
 /doc
 
+# Inchex stores some metadata here
+/docs
+
 # If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
 
@@ -22,4 +25,4 @@ erl_crash.dump
 /logs
 
 config/*.secret.exs
-mix.lock
+mix.lock

.tool-versions

@@ -1,2 +1,2 @@
-elixir 1.3.3
+elixir 1.6.6
 erlang 19.1

.travis.yml

@@ -1,26 +1,18 @@
 ---
 language: elixir
 elixir:
+  - 1.7.2
   - 1.6.6
   - 1.5
   - 1.4
-  - 1.3
 otp_release:
   - 21.0
   - 20.3
   - 19.3
   - 18.3
-env:
-  matrix:
-    - NO_THIRD_PARTY_INTEGRATION_TEST=true
-    - NO_THIRD_PARTY_INTEGRATION_TEST=false
 
 matrix:
   exclude:
-    - elixir: 1.3
-      otp_release: 20.3
-    - elixir: 1.3
-      otp_release: 21.0
     - elixir: 1.4
       otp_release: 21.0
     - elixir: 1.5
@@ -34,6 +26,8 @@ script:
   - if [ "$TRAVIS_ELIXIR_VERSION" = "1.6.6" ]; then mix format --check-formatted --dry-run; fi
   - MIX_ENV=test mix compile && mix test
   - if [ "$TRAVIS_ELIXIR_VERSION" = "1.6.6" ] && [ "$TRAVIS_OTP_RELEASE" = "21.0" ]; then mix dialyzer; fi
+  - if [ "$TRAVIS_ELIXIR_VERSION" = "1.6.6" ] && [ "$TRAVIS_OTP_RELEASE" = "21.0" ]; then mix coveralls.travis; fi
+  - if [ "$TRAVIS_ELIXIR_VERSION" = "1.6.6" ] && [ "$TRAVIS_OTP_RELEASE" = "21.0" ]; then mix credo; fi
 
 cache:
   directories:

ADHERENCE.md

@@ -0,0 +1,108 @@
+# Timber Specification Adherence
+
+Audits adherence to the [Timber library specification](timber_library_specification).
+
+* Version: 3.0.0-alpha.3
+* Last checked: 2018-10-16
+* Checked by: David Antaramian
+
+## Caveats
+
+### Styling
+
+The official `mix format` tool is used for formatting code. All other styling
+should follow the `mix credo` guidelines which are controlled by `.credo.exs`.
+
+### Documentation Coverage
+
+Documentation coverage is determined using the `mix inch` tool which reports on
+documentation coverage and quality.
+
+## v1.0.0 - Basic Logging
+
+|     Sec | Requirement                                                       |     |
+|--------:|:------------------------------------------------------------------|:----|
+|  **2.** | **Library, Code, and Language Convention**                        |     |
+|     2.1 | Library is named `timber`                                         | [x] |
+|     2.2 | Follows recommended language conventions                          | [x] |
+|     2.3 | Implements an official styling standard                           | [x] |
+|     2.4 | All public classes and/or modules are documented properly         | [ ] |
+|     2.4 | All public methods are documented properly                        | [ ] |
+|     2.4 | Method arguments are documented, including options                | [ ] |
+|     2.4 | Examples are provided in documentation where relevant             | [ ] |
+|     2.5 | Is semantically versioned                                         | [x] |
+|     2.6 | Includes a properly formatted CHANGELOG                           | [x] |
+|     2.7 | Has been made available on the proper package manager             | [x] |
+|  **3.** | **Logging Pipeline**                                              |     |
+|     3.1 | Properly integrates within the context of the language            | [x] |
+|     3.1 | Provides separate libraries if integrating with 3rd party loggers | N/A |
+|     3.1 | Can be easily swapped into existing applications                  | [x] |
+|   3.2.1 | Exposes leveled methods (info, warn, etc)                         | N/A |
+|   3.2.2 | Accepts generic string log messages                               | [x] |
+|   3.3.2 | Can write logs to any IO device                                   | N/A |
+|   3.3.3 | Provides a generic HTTP writer that transmits logs                | [x] |
+| 3.3.3.1 | Sends logs in batches to the Timber service                       | [x] |
+| 3.3.3.1 | The maxmimum batch flush size default is 1000                     | [x] |
+| 3.3.3.1 | The maxmimum batch flush size is configurable                     | [x] |
+| 3.3.3.1 | The maxmimum batch flush age default is 1 second                  | [x] |
+| 3.3.3.1 | The maxmimum batch flush age is configurable                      | [x] |
+| 3.3.3.1 | Log lines can be buffered after a flush starts                    | [x] |
+| 3.3.3.1 | Flush errors do not affect the stability of the system            | [x] |
+| 3.3.3.1 | Flush errors do not pause or stop the process in any way          | [x] |
+| 3.3.3.1 | Request that results in 5XX responses are retried up to 3 times   | [ ] |
+| 3.3.3.1 | Retries utilize an exponential backoff with jitter                | [ ] |
+| 3.3.3.1 | Will recover after a sustained Timber service outage              | [x] |
+| 3.3.3.2 | `Authorization` header is properly set                            | [x] |
+| 3.3.3.3 | Payload is `UTF-8` encoded                                        | [x] |
+| 3.3.3.4 | Payload uses a supported content type                             | [x] |
+| 3.3.3.4 | The `Content-Type` header is properly set                         | [x] |
+| 3.3.3.5 | The `User-Agent` header is properly set                           | [x] |
+
+## v1.1.0 - Structured Logging
+
+|     Sec | Requirement                                                                |     |
+|--------:|:---------------------------------------------------------------------------|:---:|
+|   **3** | **Logging Pipeline**                                                       |     |
+|     3.1 | Additionally integrates with popular logging libraries                     | [x] |
+|   3.2.3 | Accepts structured data as the message                                     | N/A |
+|   3.2.4 | Accepts supplemental structured data                                       | [x] |
+|   3.3.1 | Defines a log event data structure                                         | [x] |
+| 3.3.1.1 | The JSON encoded log event properly adopts a versioned Timber event schema | [x] |
+| 3.3.1.2 | Normalizes strings into Timber events                                      | [x] |
+| 3.3.1.3 | Normalizes structured data into Timber events                              | [x] |
+|   3.3.2 | Provides an IO device formatter that preserves structured data             | [x] |
+|   3.3.2 | IO device formatter uses the proper `@metadata` delimiter                  | [x] |
+|   3.3.2 | New line characters within the metadata are escaped                        | [x] |
+|   3.3.2 | Formats logs before being sent to the IO device                            | [x] |
+
+## v1.2.0 - Events
+
+|     Sec | Requirement                                                      |     |
+|--------:|:-----------------------------------------------------------------|:---:|
+|   **3** | **Logging Pipeline**                                             |     |
+|   3.2.5 | Accepts events as structured data                                | [x] |
+| 3.3.1.3 | Normalizes Timber official events                                | [x] |
+| 3.3.1.4 | Normalizes custom events                                         | [x] |
+|   **4** | **Events**                                                       |     |
+|     4.1 | Defines a base event data structure                              | [x] |
+|     4.2 | Defines events for all Timber official events                    | [x] |
+|     4.3 | Allows users to define custom events by extending the base event | [x] |
+
+## v1.3.0 - Context
+
+|     Sec | Requirement                                             |     |
+|--------:|:--------------------------------------------------------|:---:|
+|   **3** | **Logging Pipeline**                                    |     |
+| 3.3.1.4 | Injects context into the final log event                | [x] |
+|   **5** | **Context**                                             |     |
+|     5.4 | Context data structure is a map or hash like structure  | [x] |
+|     5.5 | Context can be JSON encoded                             | [x] |
+|     5.6 | Adding context performs a shallow merge                 | [x] |
+|     5.7 | Context can be removed on a key basis                   | [ ] |
+|     5.8 | Context can be added and removed within a lexical scope | N/A |
+|   5.9.1 | Runtime context is captured by default (if possible)    | [x] |
+|   5.9.2 | Host context is captured by default                     | [x] |
+|   5.9.3 | EC2 context is captured by default                      | [ ] |
+|   5.9.4 | Heroku context is captured by default                   | [ ] |
+
+[timber_library_specification]: https://github.com/timberio/library-specification

CHANGELOG.md

@@ -1,156 +1,39 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+This covers changes for versions 3.0 and higher. The changelog for 2.x releases
+can be found in the [v2.x
+branch](https://github.com/timberio/timber-elixir/blob/v2.x/CHANGELOG.md).
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+and this project adheres to [Semantic
+Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [2.8.3] - 2018-08-13
+## [3.0.0] - 2018-12-20
 
 ### Changed
 
-  - The system hostname is now cached after it is fetched the first time.
-    Previously, the hostname was fetched every time a log line was formatted for
-    output (whether by formatting occured in the console formatter or during
-    HTTP transport). This reduces the overhead caused by fetching the hostname.
-
-## [2.8.2] - 2018-07-01
-
-### Changed
-
-  - Allow `~> 2.0` for the `:msgpax` dependency.
-
-## [2.8.1] - 2018-06-07
-
-### Added
-
-  - Add support for inline context via the `:context` `Logger` metadata key.
-  - Add `Timber.remove_context_key` for removing an individual keys off of context structures.
-
-### Changed
-
-  - Relax the `:plug` dependency to allow for more plug versions.
-
-## [2.8.0] - 2018-04-16
-
-### Added
-
-  - `Timber.Integrations.ErrorLogger` allows you to include a new OTP
-    `:error\_logger` handler to better maintain the structure of errors and
-    stacktraces. It also collapses many cases of multi-line logs into a single
-    line.
-
-### Fixed
-
-  - Fixed Logger metadata to use the pid from the Logger event and fall back
-    to `self()`.
-
-  - Fix an issue with the regular expression that detects the Router during
-    installation.
-
-  - Fix an issue with being able to skip files during installation when multiple
-    files match.
-
-## [2.7.0] - 2018-03-22
-
-### Added
-
-  - `Timber.add_context/2` now allows you to set context either locally or globally;
-    `Timber.add_context/1` will default to storing the context locally (consistent
-    with previous versions of the library)
-  - The `Timber.LocalContext` now manages setting and updating the Timber context
-    maintained in the Elixir Logger metadata. This replaces the `Timber.CurrentContext`
-    module. `Timber.LocalContext.get/0` should be used where
-    `Timber.CurrentContext.load/0` was used before, and `Timber.LocalContext.put/1`
-    should be used where `Timber.CurrentContext.save/1` was used.
-
-### Changed
-
-  - `Timber.LogEntry.new/4` will fetch the global context and merge it into the
-    local metadata context. The local context will override the global context
-    based on the rules for `Timber.Context.merge/2`
-  - Phoenix Channels integration will now accept _any_ channel message payload.
-    (Previously, non-map types were dropped and replaced with an empty map.)
-
-### Deprecated
-
-  - `Timber.CurrentContext` has been deprecated in favor of `Timber.LocalContext`;
-    the new name better reflects the purpose of the module. Use of
-    `Timber.CurrentContext` will still be supported for the lifetime of v2
-
-### Fixed
-
-  - Phoenix Channels integration with Phoneix 1.3+ will no longer fail if the
-    payload of a channel message is a list
-
-## [2.6.1] - 2017-10-02
-
-### Fixed
-
-  - Fixed an error where `Timber.Integrations.PhoenixInstrumenter` would fail
-    on versions of Phoenix prior to 1.3 that do not pass a `:conn` key with the
-    `phoenix_controller_render/3` `:start` event.
-
-  - Fixed `Timber.Integrations.PhoenixInstrumenter` did not define a
-    fall-through for `phoenix_controller_render/3` during the `:start` event for
-    when the third-parameter is in a different format than expected.
-
-  - Fixed `Timber.Integrations.PhoenixInstrumenter` did not define a
-    fall-through when the instrumentation system sends a default state value for
-    the `:stop` event on `phoenix_controller_render/3`.
-
-## [2.6.0] - 2017-09-28
-
-### Changed
-
-  - Logger backends now conform to the `:gen_event` behaviour rather than calling
-    the `GenEvent.__using__/1` macro which is deprecated in Elixir 1.5.0 and
-    above. The change is backwards compatible since `:gen_event` is provided by
-    all supported versions of Erlang.
-
-## [2.5.6] - 2017-09-28
-
-### Fixed
-
-  - Fixed an error where `Timber.Integrations.PhoenixInstrumenter` would cause
-    an error during blacklist checks if the blacklist had not been set up.
-
-  - Fixed an error where `Timber.Integrations.PhoenixInstrumenter` would fail on render
-    events for `conn` structs that did not have a controller or action set. For
-    example, when a `conn` did not match listed routes, a `404.html` template
-    would be rendered that did not have a controller or action. The render event
-    would still be triggered though.
-
-## [2.5.5] - 2017-09-21
-
-### Fixed
-
-  - `Timber.Events.HTTPRepsonseEvent` no longer enforces the `:time_ms` key on
-    the struct. This brings it in line with the specification
-
-## [2.5.4] - 2017-09-18
-
-### Fixed
-
-  - Fixed a bug within the installer where HTTP log delivery was being used on platforms that
-    should use STDOUT / :console.
-
-### Added
-
-  - Support for blacklisting controller actions with
-    `Timber.Integrations.PhoenixInstrumenter`. This will suppress log lines
-    from being written for any controller/action pair.
-
-[Unreleased]: https://github.com/timberio/timber-elixir/compare/v2.8.3...HEAD
-[2.8.3]: https://github.com/timberio/timber-elixir/compare/v2.8.2...v2.8.3
-[2.8.2]: https://github.com/timberio/timber-elixir/compare/v2.8.1...v2.8.2
-[2.8.1]: https://github.com/timberio/timber-elixir/compare/v2.8.0...v2.8.1
-[2.8.0]: https://github.com/timberio/timber-elixir/compare/v2.7.0...v2.8.0
-[2.7.0]: https://github.com/timberio/timber-elixir/compare/v2.6.1...v2.7.0
-[2.6.1]: https://github.com/timberio/timber-elixir/compare/v2.6.0...v2.6.1
-[2.6.0]: https://github.com/timberio/timber-elixir/compare/v2.5.6...v2.6.0
-[2.5.6]: https://github.com/timberio/timber-elixir/compare/v2.5.5...v2.5.6
-[2.5.5]: https://github.com/timberio/timber-elixir/compare/v2.5.4...v2.5.5
-[2.5.4]: https://github.com/timberio/timber-elixir/compare/v2.5.3...v2.5.4
+  - [Jason](https://hex.pm/packages/jason) is now used for JSON encoding. The
+    JSON library can no longer be injected via configuration.
+  - [`msgpax`](https://hex.pm/packages/msgpax) 1.x is no longer supported
+  - Logs are now sent in batches of 1000 instead of 5000 to comply with the
+  Timber library specification
+  - `Timber.LoggerBackends.HTTP.TimberAPIKeyInvalid` is now `Timber.InvalidAPIKeyError`
+
+### Removed
+
+  - Removed support for Elixir 1.3 and lower
+  - Removed integration with Phoenix; use the
+    [`:timber_phoenix`](https://hex.pm/packages/timber_phoenix) package instead
+  - Removed integration with Plug; use the
+    [`:timber_plug`](https://hex.pm/packages/timber_plug) package instead
+  - Removed integration with Ecto; use the
+    [`:timber_ecto`](https://hex.pm/packages/timber_ecto) package instead
+  - Removed integration with ExAws
+  - Removed integration with `:error_logger`; use the
+    [`:timber_exceptions`](https://hex.pm/packages/timber_exceptions) package
+    instead
+  - Removed the installer (`mix timber.install`); manual installation is now
+    expected
+  - Removed the test event Mix task