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

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

MIT License. See LICENSE for details.