update docs

Author: mitchellhenke

README.md

@@ -21,16 +21,51 @@ defp deps do
 end
 ```
 
-Setup the application environment in your `config/prod.exs`
+An example production config might look like this:
 
 ```elixir
 config :sentry,
   dsn: "https://public:[email protected]/1",
+  environment_name: :prod,
+  included_environments: [:prod],
   tags: %{
     env: "production"
   }
 ```
 
+The environment
+
+The `environment_name` and `included_environments` work together to determine
+if and when Sentry should record exceptions. The `environment_name` is the
+name of the current environment. In the example above, we have explicitly set
+the environment to `:prod` which works well if you are inside an environment
+specific configuration like `config/prod.exs`.
+
+Alternatively, you could use Mix.env in your general configuration file:
+
+```elixir
+config :sentry, dsn: "https://public:[email protected]/1"
+  included_environments: [:prod],
+  environment_name: Mix.env
+```
+
+You can even rely on more custom determinations of the environment name. It's
+not uncommmon for most applications to have a "staging" environment. In order
+to handle this without adding an additional Mix environment, you can set an
+environment variable that determines the release level.
+
+```elixir
+config :sentry, dsn: "https://public:[email protected]/1"
+  included_environments: ~w(production staging),
+  environment_name: System.get_env("RELEASE_LEVEL") || "development"
+```
+
+In this example, we are getting the environment name from the `RELEASE_LEVEL`
+environment variable. If that variable does not exist, we default to `"development"`.
+Now, on our servers, we can set the environment variable appropriately. On
+our local development machines, exceptions will never be sent, because the
+default value is not in the list of `included_environments`.
+
 ### Capture Exceptions
 
 Sometimes you want to capture specific exceptions, to do so use the `Sentry.capture_exception/3`.

docs/index.rst

@@ -36,10 +36,47 @@ Setup the application production environment in your ``config/prod.exs``
 
   config :sentry,
     dsn: "https://public:[email protected]/1",
+    environment_name: :prod
     tags: %{
       env: "production"
     },
-    included_environments: ~w(prod)a
+    included_environments: [:prod]
+
+
+The ``environment_name`` and ``included_environments`` work together to determine
+if and when Sentry should record exceptions. The ``environment_name`` is the
+name of the current environment. In the example above, we have explicitly set
+the environment to ``:prod`` which works well if you are inside an environment
+specific configuration like ``config/prod.exs``.
+
+An alternative is to use ``Mix.env`` in your general configuration file:
+
+.. code-block:: elixir
+
+  config :sentry, dsn: "https://public:[email protected]/1"
+     included_environments: [:prod],
+     environment_name: Mix.env
+
+This will set the environment name to whatever the current Mix environment
+atom is, but it will only send events if the current environment is ``:prod``,
+since that is the only entry in the ``included_environments`` key.
+
+You can even rely on more custom determinations of the environment name. It's
+not uncommmon for most applications to have a "staging" environment. In order
+to handle this without adding an additional Mix environment, you can set an
+environment variable that determines the release level.
+
+.. code-block:: elixir
+
+  config :sentry, dsn: "https://public:[email protected]/1"
+    included_environments: ~w(production staging),
+    environment_name: System.get_env("RELEASE_LEVEL") || "development"
+
+In this example, we are getting the environment name from the ``RELEASE_LEVEL``
+environment variable. If that variable does not exist, we default to ``"development"``.
+Now, on our servers, we can set the environment variable appropriately. On
+our local development machines, exceptions will never be sent, because the
+default value is not in the list of ``included_environments``.
 
 If using an environment with Plug or Phoenix add the following to your router:
 

lib/sentry.ex

@@ -49,7 +49,7 @@ defmodule Sentry do
   environment variable. If that variable does not exist, we default to `"development"`.
   Now, on our servers, we can set the environment variable appropriately. On
   our local development machines, exceptions will never be sent, because the
-  default value is not in the list of `include_environments`.
+  default value is not in the list of `included_environments`.
 
   ## Capturing Exceptions