View Source LogsnagEx
An Elixir client for LogSnag - The event tracking platform for monitoring your products, services, and user behavior.
Installation
Add logsnag_ex
to your list of dependencies in mix.exs
:
def deps do
[
{:logsnag_ex, "~> 1.0.0"}
]
end
Configuration
Configure LogSnag in your config/config.exs
(or environment-specific config file):
config :logsnag_ex,
default: [
token: System.get_env("LOGSNAG_TOKEN"),
project: System.get_env("LOGSNAG_PROJECT"),
disabled: Mix.env() != :prod # optional, defaults to false
]
Multiple Clients
You can configure multiple LogSnag clients for different purposes:
config :logsnag_ex,
default: [
token: System.get_env("LOGSNAG_TOKEN"),
project: System.get_env("LOGSNAG_PROJECT")
],
analytics: [
token: System.get_env("LOGSNAG_TOKEN"),
project: System.get_env("LOGSNAG_PROJECT_2"),
name: MyApp.AnalyticsLogSnag
]
Then in your application supervision tree:
children = [
{LogsnagEx.Client, Application.get_env(:logsnag_ex, :default, [])},
{LogsnagEx.Client, Application.get_env(:logsnag_ex, :analytics, [])}
]
Setup
The library is an OTP application, so it will automatically start its supervision tree. You don't need to add anything to your supervision tree unless you're using multiple clients.
Single Client (Default)
Just add the configuration to your config/config.exs
:
config :logsnag_ex,
default: [
token: System.get_env("LOGSNAG_TOKEN"),
project: System.get_env("LOGSNAG_PROJECT")
]
Multiple Clients
For multiple clients, configure them in your config:
config :logsnag_ex,
default: [
token: System.get_env("LOGSNAG_TOKEN"),
project: System.get_env("LOGSNAG_PROJECT")
],
analytics: [
token: System.get_env("LOGSNAG_TOKEN"),
project: System.get_env("LOGSNAG_PROJECT_2"),
client: MyApp.AnalyticsLogSnag
]
Then add the additional clients to your supervision tree:
# lib/your_app/application.ex
def start(_type, _args) do
children = [
# ... your other children ...
{LogsnagEx.Client, Application.get_env(:logsnag_ex, :analytics, [])}
]
opts = [strategy: :one_for_one, name: YourApp.Supervisor]
Supervisor.start_link(children, opts)
end
Usage
Tracking Events
# Simple event
LogsnagEx.track("user-signup", "New User Registered")
# Event with all options
LogsnagEx.track("payments", "Payment Received",
description: "User completed payment for premium plan",
icon: "💰",
tags: %{
order_id: "12345",
amount: "$99.99"
},
notify: true,
user_id: "user-123", # Optional user association
parser: "markdown", # Optional: "markdown" or "text"
date: DateTime.utc_now() # Optional timestamp
)
Using Insights
Insights help you track metrics and KPIs:
# Track a metric
LogsnagEx.Insight.track("Active Users", 100, icon: "👥")
# Increment a metric
LogsnagEx.Insight.increment("Total Sales", 99.99)
# Using custom client
LogsnagEx.Insight.track("Daily Revenue", 10_000,
client: MyApp.AnalyticsLogSnag
)
User Identification
Track user properties:
LogsnagEx.identify("user-123",
%{
email: "user@example.com",
name: "John Doe",
plan: "premium"
}
)
Group Tracking
Track organization or group properties:
LogsnagEx.group("user-123", "org-456",
%{
name: "Acme Corp",
plan: "enterprise",
employees: 50
}
)
Options
Event Tracking Options
:description
- Additional details about the event:icon
- Single emoji to represent the event:tags
- Map of key-value pairs for additional data:notify
- Boolean to enable push notifications:parser
- String "markdown" or "text" for description parsing:date
- DateTime for historical events:client
- Atom name of custom client to use
Insight Options
:icon
- Single emoji to represent the insight:client
- Atom name of custom client to use
Development Environment
For development or testing, you can disable tracking:
config :logsnag_ex,
default: [
token: "test-token",
project: "test-project",
disabled: true
]
Testing
The package uses Mox for testing. In your test_helper.exs
:
Mox.defmock(LogsnagEx.MockClient, for: LogsnagEx.Client.Behaviour)
Application.put_env(:logsnag_ex, :client_module, LogsnagEx.MockClient)
Example test:
test "track/3 sends a log event" do
expect(LogsnagEx.MockClient, :request, fn :post, "/log", body, _name ->
assert body["channel"] == "test-channel"
assert body["event"] == "test-event"
{:ok, body}
end)
assert {:ok, response} = LogsnagEx.track("test-channel", "test-event")
end
Error Handling
All functions return {:ok, result}
or {:error, error}
:
case LogsnagEx.track("channel", "event") do
{:ok, response} ->
# Handle success
{:error, %LogsnagEx.Error{message: message, data: data}} ->
# Handle error
end
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
License
MIT License. See LICENSE for details.