Honeylixir (honeylixir v0.4.0) View Source
Used to interact with honeycomb.io's API for tracing and other data.
Installation
Adding Honeylixir to your mix.exs as a dependency should suffice for installation:
def deps() do
[
{:honeylixir, "~> 0.4.0"}
]
end
Configuration
You can configure any of the following variables via Config:
Name | Type | Description | Default |
---|---|---|---|
:api_host | string | API to send events to | https://api.honeycomb.io |
:sample_rate | integer | Rate at which events will be sampled represented as a percented. e.g., use 10 to send 10% of events | 1 |
:team_writekey | string | API key used to send events | nil |
:dataset | string /atom | Dataset to send the events to | nil |
:service_name | string /atom | Name of your service which will be added as a field on all events at the key "service_name" | nil |
:max_queue_size | integer | How large the transmission queue can grow before events are dropped | 10_000 |
:batch_size | integer | How many events to send per batch | 50 |
:batch_timing | integer | Time in milliseconds to try sending events from the queue in a batch | 100 |
:max_send_processes | integer | How many Processes to use for sending events in the background | 30 |
It is required that you set :team_writekey
and :dataset
for events to be sent. Otherwise,
they will return non-200 responses from Honeycomb resulting in the events being dropped. An
example config may look like so (whether distillery or compile time Mix):
config :honeylixir,
dataset: :"my-company",
team_writekey: System.get_env("HONEYLIXIR_WRITEKEY"),
service_name: :my_application
Additionally, many are defined on the Honeylixir.Event
struct and can be overridden
on a per-event basis. Please check its typspec for a complete list of what you can
modify.
event = Honeylixir.Event.create()
event = %{event | api_host: "https://some-other-valid-host.com"}
Usage
Sending events
Honeylixir
provides the ability to make a Honeylixir.Event
, add fields to it, then send it off asynchronously.
Honeylixir.Event.create()
|> Honeylixir.Event.add_field("a_field", "my_value")
|> Honeylixir.Event.add_field("something-else", %{"nested" => "value"})
|> Honeylixir.Event.send()
Any value can be used but fields are REQUIRED to be strings. Non-string fields will result in a no matching function clause error.
Global field configuration
Honeylixir
supports adding global fields which will be added to all events on
event creation. You can add, remove, or view the fields configured at any time.
Honeylixir.GlobalFields.add_field("my-thing", "special")
event = Honeylixir.Event.create()
IO.inspect(event.fields)
# => %{"my-thing" => "special"}
IO.inspect Honeylixir.GlobalFields.fields
# => %{"my-thing", "special"}
Honeylixir.GlobalFields.remove_field("my-thing")
IO.inspect Honeylixir.GlobalFields.fields
# => %{}
Builder pattern
Currently, the Builder pattern is supported insomuch as Elixir's syntax allows it. That is to say, you can create your own function that acts as a Builder.
defmodule MyHoneylixirBuilders do
def http_event do
Honeylixir.Event.create()
|> Honeylixir.add_field("foo", "bar")
end
def different_dataset_event do
%{Honeylixir.Event.create() | dataset: "my-other-dataset"}
|> Honeylixir.add_field("something", "great")
|> Honeylixir.add_field("another", "thing")
end
end
Checking responses
By attaching metadata to your events, you can pull Honeylixir.Response
s to see what happened
to your event. These are sent along via :telemetry
for getting events as part of the metadata
object at the :response
field. Current eventNames:
[:honeylixir, :event, :send]
- Used for the response around any event sent, even if that event is sampled or rejected for queue overflow. Metadata is set to%{response: %Honeylixir.Response}
which contains the data.
# Note: as stated in the `:telemetry` docs, you should use function capture rather than anonymous functions.
:telemetry.attach(
"test-attachment",
[:honeylixir, :event, :send],
fn _event_name, _measurements, %{response: response}, _config ->
IO.inspect response
end,
nil
)
Honeylixir.Event.create() |> Honeylixir.Event.send()
# wait for event to async send off and the associated Response will be output
You can also attach to the function used for key creation:
:telemetry.attach(
"my-listener",
Honeylixir.event_send_telemetry_key(),
fn _, _, _, _ -> nil end,
nil
)
Link to this section Summary
Functions
Key used for all event send telemetry executions.
Generates a random string of 16 bytes encoded in base 16.
Generates a random string of 8 bytes encoded in base 16.