TraceStax Docs

Elixir

The TraceStax Elixir SDK supports Oban (Pro and CE) and can be used with any GenServer-based worker via the lower-level client.

Requirements

Elixir 1.14+
Oban 2.x (optional — works without Oban too)

Installation

Add to mix.exs:

def deps do
  [
    {:tracestax, "~> 1.0"}
  ]
end

Then fetch:

mix deps.get

Setup

Oban
GenServer worker

Add the TraceStax plugin to your Oban configuration:

config :my_app, Oban,
  repo: MyApp.Repo,
  plugins: [
    {TraceStax.Oban.Plugin, api_key: System.get_env("TRACESTAX_API_KEY")}
  ],
  queues: [default: 10, critical: 5]

The plugin hooks into Oban’s telemetry events — no changes to your worker modules required.

defmodule MyApp.Workers.SendEmail do
  use Oban.Worker, queue: :default

  @impl Oban.Worker
  def perform(%Oban.Job{args: %{"user_id" => user_id}}) do
    # TraceStax tracks this automatically
    MyApp.Mailer.send_welcome(user_id)
  end
end

For custom GenServer or Task-based workers, use the client directly:

defmodule MyApp.OrderWorker do
  use GenServer
  alias TraceStax.Client

  def handle_cast({:process, order_id}, state) do
    event = Client.start_job("process_order", "default")

    result = process_order(order_id)

    case result do
      {:ok, _} -> Client.succeed(event)
      {:error, reason} -> Client.fail(event, reason)
    end

    {:noreply, state}
  end
end

Configuration

config :tracestax,
  api_key: System.get_env("TRACESTAX_API_KEY"),  # Required
  worker_id: "worker-01",                       # Default: hostname + PID
  enabled: Mix.env() != :test,
  ingest_url: "https://ingest.tracestax.com",
  timeout: 3_000

Key	Env var	Default	Description
`:api_key`	`TRACESTAX_API_KEY`	—	Required
`:worker_id`	`TRACESTAX_WORKER_ID`	hostname + PID	Worker identifier
`:enabled`	`TRACESTAX_ENABLED`	`true`	Set to `false` in tests
`:ingest_url`	`TRACESTAX_INGEST_URL`	`https://ingest.tracestax.com`	Custom endpoint
`:timeout`	—	`3000`	HTTP timeout in ms

Testing

config :tracestax, enabled: false