added a flush to batcher and some doc changes

Author: Stuart Eccles

README.md

@@ -23,7 +23,7 @@ Documentation can be be found at [https://hexdocs.pm/segment](https://hexdocs.pm
 ## Usage
 
 Start the Segment agent with your write_key from Segment for a HTTP API Server Source
-```
+```elixir
 Segment.start_link("YOUR_WRITE_KEY")
 ```
 There are then two ways to call the different methods on the API.
@@ -36,11 +36,11 @@ queue and batch events to Segment.
 The other way is to drop down lower and use `Segment.Http` `send` and `batch` directly. This will require first creating a `client` with `Segment.Http.client/1`/`Segment.Http.client/2`
 
 ### Track
-```
+```elixir
 Segment.Analytics.track(user_id, event, %{property1: "", property2: ""})
 ```
 or the full way using a struct with all the possible options for the track call
-```
+```elixir
 %Segment.Analytics.Track{ userId: "sdsds",
                           event: "eventname",
                           properties: %{property1: "", property2: ""}
@@ -49,59 +49,59 @@ or the full way using a struct with all the possible options for the track call
 ```
 
 ### Identify
-```
+```elixir
 Segment.Analytics.identify(user_id, %{trait1: "", trait2: ""})
 ```
 or the full way using a struct with all the possible options for the identify call
-```
+```elixir
 %Segment.Analytics.Identify{ userId: "sdsds",
                              traits: %{trait1: "", trait2: ""}
                            }
   |> Segment.Analytics.identify
 ```
 
 ### Screen
-```
+```elixir
 Segment.Analytics.screen(user_id, name)
 ```
 or the full way using a struct with all the possible options for the screen call
-```
+```elixir
 %Segment.Analytics.Screen{ userId: "sdsds",
                            name: "dssd"
                          }
   |> Segment.Analytics.screen
 ```
 
 ### Alias
-```
+```elixir
 Segment.Analytics.alias(user_id, previous_id)
 ```
 or the full way using a struct with all the possible options for the alias call
-```
+```elixir
 %Segment.Analytics.Alias{ userId: "sdsds",
                           previousId: "dssd"
                          }
   |> Segment.Analytics.alias
 ```
 
 ### Group
-```
+```elixir
 Segment.Analytics.group(user_id, group_id)
 ```
 or the full way using a struct with all the possible options for the group call
-```
+```elixir
 %Segment.Analytics.Group{ userId: "sdsds",
                           groupId: "dssd"
                          }
   |> Segment.Analytics.group
 ```
 
 ### Page
-```
+```elixir
 Segment.Analytics.page(user_id, name)
 ```
 or the full way using a struct with all the possible options for the page call
-```
+```elixir
 %Segment.Analytics.Page{ userId: "sdsds",
                          name:   "dssd"
                        }
@@ -113,7 +113,7 @@ or the full way using a struct with all the possible options for the page call
 
 If you want to set the Context manually you should create a `Segment.Analytics.Context` struct with `Segment.Analytics.Context.new/1` 
 
-```
+```elixir
 context = Segment.Analytics.Context.new(%{active: false})
 
 Segment.Analytics.track(user_id, event, %{property1: "", property2: ""}, context)
@@ -138,25 +138,15 @@ This is how I add to a Phoenix project (may not be your preferred way)
 
 1. Add the following to deps section of your mix.exs: `{:segment, "~> 0.2.0"}`
    and then `mix deps.get`
-2. Add segment to applications list in the Phoenix project mix.exs
-ie.
-```
-def application do
-  [mod: {FormAndThread, []},
-   applications: [:phoenix, :phoenix_html, :cowboy, :logger,
-                  :phoenix_ecto, :postgrex, :segment]]
-end
-```
-3. Add a config variable for your write_key (you may want to make this load from ENV)
+2. Add a config variable for your write_key (you may want to make this load from ENV)
 ie.
-```
+```elixir
 config :segment,
   write_key: "2iFFnRsCfi"
 ```
-4. Start the segment agent as a child of the application in the application file under
-the lib directory. In the children list add:
-```
-worker(Segment, [Application.get_env(:segment, :write_key)])
+3. Start the Segment GenServer in the supervised children list. In `application.ex` add to the children list:
+```elixir
+{Segment, Application.get_env(:segment, :write_key)}
 ```
 
 ## Running tests

lib/segment.ex

@@ -22,7 +22,7 @@ defmodule Segment do
   ## Usage
 
   Start the Segment agent with your write_key from Segment for a HTTP API Server Source
-  ```
+  ```elixir
   Segment.start_link("YOUR_WRITE_KEY")
   ```
   There are then two ways to call the different methods on the API.
@@ -35,11 +35,11 @@ defmodule Segment do
   The other way is to drop down lower and use `Segment.Http` `send` and `batch` directly. This will require first creating a `client` with `Segment.Http.client/1`/`Segment.Http.client/2`
 
   ### Track
-  ```
+  ```elixir
   Segment.Analytics.track(user_id, event, %{property1: "", property2: ""})
   ```
   or the full way using a struct with all the possible options for the track call
-  ```
+  ```elixir
   %Segment.Analytics.Track{ userId: "sdsds",
                           event: "eventname",
                           properties: %{property1: "", property2: ""}
@@ -48,59 +48,59 @@ defmodule Segment do
   ```
 
   ### Identify
-  ```
+  ```elixir
   Segment.Analytics.identify(user_id, %{trait1: "", trait2: ""})
   ```
   or the full way using a struct with all the possible options for the identify call
-  ```
+  ```elixir
   %Segment.Analytics.Identify{ userId: "sdsds",
                              traits: %{trait1: "", trait2: ""}
                            }
   |> Segment.Analytics.identify
   ```
 
   ### Screen
-  ```
+  ```elixir
   Segment.Analytics.screen(user_id, name)
   ```
   or the full way using a struct with all the possible options for the screen call
-  ```
+  ```elixir
   %Segment.Analytics.Screen{ userId: "sdsds",
                            name: "dssd"
                          }
   |> Segment.Analytics.screen
   ```
 
   ### Alias
-  ```
+  ```elixir
   Segment.Analytics.alias(user_id, previous_id)
   ```
   or the full way using a struct with all the possible options for the alias call
-  ```
+  ```elixir
   %Segment.Analytics.Alias{ userId: "sdsds",
                           previousId: "dssd"
                          }
   |> Segment.Analytics.alias
   ```
 
   ### Group
-  ```
+  ```elixir
   Segment.Analytics.group(user_id, group_id)
   ```
   or the full way using a struct with all the possible options for the group call
-  ```
+  ```elixir
   %Segment.Analytics.Group{ userId: "sdsds",
                           groupId: "dssd"
                          }
   |> Segment.Analytics.group
   ```
 
   ### Page
-  ```
+  ```elixir
   Segment.Analytics.page(user_id, name)
   ```
   or the full way using a struct with all the possible options for the page call
-  ```
+  ```elixir
   %Segment.Analytics.Page{ userId: "sdsds",
                          name:   "dssd"
                        }
@@ -112,7 +112,7 @@ defmodule Segment do
 
   If you want to set the Context manually you should create a `Segment.Analytics.Context` struct with `Segment.Analytics.Context.new/1`
 
-  ```
+  ```elixir
   context = Segment.Analytics.Context.new(%{active: false})
 
   Segment.Analytics.track(user_id, event, %{property1: "", property2: ""}, context)
@@ -137,25 +137,15 @@ defmodule Segment do
 
   1. Add the following to deps section of your mix.exs: `{:segment, "~> 0.2.0"}`
    and then `mix deps.get`
-  2. Add segment to applications list in the Phoenix project mix.exs
-  ie.
-  ```
-  def application do
-  [mod: {FormAndThread, []},
-   applications: [:phoenix, :phoenix_html, :cowboy, :logger,
-                  :phoenix_ecto, :postgrex, :segment]]
-  end
-  ```
-  3. Add a config variable for your write_key (you may want to make this load from ENV)
+  2. Add a config variable for your write_key (you may want to make this load from ENV)
   ie.
-  ```
+  ```elixir
   config :segment,
   write_key: "2iFFnRsCfi"
   ```
-  4. Start the segment agent as a child of the application in the application file under
-  the lib directory. In the children list add:
-  ```
-  worker(Segment, [Application.get_env(:segment, :write_key)])
+  3. Start the Segment GenServer in the supervised children list. In `application.ex` add to the children list:
+  ```elixir
+  {Segment, Application.get_env(:segment, :write_key)}
   ```
   """
   @type segment_event ::

lib/segment/analytics.ex

@@ -3,7 +3,7 @@ defmodule Segment.Analytics do
     The `Segment.Analytics` module is the easiest way to send Segment events and provides convenience methods for `track`, `identify,` `screen`, `alias`, `group`, and `page` calls
 
     The functions will then delegate the call to the configured service implementation which can be changed with:
-    ```
+    ```elixir
     config :segment, sender_impl: Segment.Analytics.Batcher,
     ```
     By default (if no configuration is given) it will use `Segment.Analytics.Batcher` to send events in a batch periodically

lib/segment/batcher.ex

@@ -5,7 +5,7 @@ defmodule Segment.Analytics.Batcher do
     send on a regular basis.
 
     The `Segment.Analytics.Batcher` can be configured with
-    ```
+    ```elixir
     config :segment,
       max_batch_size: 100,
       batch_every_ms: 5000
@@ -55,6 +55,14 @@ defmodule Segment.Analytics.Batcher do
     enqueue(event)
   end
 
+  @doc """
+    Force the batcher to flush the queue and send all the events as a big batch (warning could exceed batch size)
+  """
+  @spec flush() :: :ok
+  def flush() do
+    GenServer.call(__MODULE__, :flush)
+  end
+
   # GenServer Callbacks
 
   @impl true
@@ -68,6 +76,13 @@ defmodule Segment.Analytics.Batcher do
     {:noreply, {client, :queue.in(event, queue)}}
   end
 
+  @impl true
+  def handle_call(:flush, _from, {client, queue}) do
+    items = :queue.to_list(queue)
+    if length(items) > 0, do: Segment.Http.batch(client, items)
+    {:reply, :ok, {client, :queue.new()}}
+  end
+
   @impl true
   def handle_info(:process_batch, {client, queue}) do
     length = :queue.len(queue)

lib/segment/client/http.ex

@@ -15,7 +15,7 @@ defmodule Segment.Http do
   `Segment.Http` is the underlying implementation for making calls to the Segment HTTP API.
 
   The `send/2` and `batch/4` methods can be used for sending events or batches of events to the API.  The sending can be configured with
-  ```
+  ```elixir
   config :segment,
   send_to_http: true
   retry_attempts: 3,

test/segment_test.exs

@@ -32,8 +32,7 @@ defmodule SegmentTest do
 
     Segment.Analytics.page("user1", "page debugging #{elem(:os.timestamp(), 2)}")
 
-    # wait 5 seconds for batcher
-    Process.sleep(5000)
+    Segment.Analytics.Batcher.flush()
   end
 
   defp wait_random(n \\ 1000), do: Process.sleep(:rand.uniform(n))