Go

The TraceStax Go SDK provides a lightweight client for sending job lifecycle events from any Go background job system. It integrates with Asynq, River, Machinery, or any custom worker loop.

Requirements

• Go 1.21+

Installation

go get github.com/tracestax/tracestax-go

---

Setup

Asynq

package main

import (
    "os"
    "github.com/hibiken/asynq"
    "github.com/tracestax/tracestax-go"
)

func main() {
    srv := asynq.NewServer(
        asynq.RedisClientOpt{Addr: "localhost:6379"},
        asynq.Config{Concurrency: 10},
    )

    mux := asynq.NewServeMux()
    mux.Use(tracestax.AsynqMiddleware(tracestax.Config{
        APIKey: os.Getenv("TRACESTAX_API_KEY"),
    }))

    mux.HandleFunc("email:welcome", handleWelcomeEmail)

    srv.Run(mux)
}

River

import (
    "github.com/riverqueue/river"
    "github.com/tracestax/tracestax-go"
)

workers := river.NewWorkers()
river.AddWorker(workers, tracestax.RiverWorkerMiddleware(
    &MyWorker{},
    tracestax.Config{APIKey: os.Getenv("TRACESTAX_API_KEY")},
))

Custom worker

For any goroutine-based worker, wrap job execution directly:

import "github.com/tracestax/tracestax-go"

client := tracestax.NewClient(tracestax.Config{
    APIKey:   os.Getenv("TRACESTAX_API_KEY"),
    WorkerID: "orders-worker-01",
})
defer client.Close()

for job := range jobQueue {
    event := client.StartJob(job.Name, job.Queue)

    if err := processJob(ctx, job); err != nil {
        event.Fail(err)
    } else {
        event.Succeed()
    }
}

---

Configuration

tracestax.Config{
    APIKey:    os.Getenv("TRACESTAX_API_KEY"), // Required
    WorkerID:  "worker-01",                  // Default: hostname + PID
    IngestURL: "https://ingest.tracestax.com",  // Optional override
    Timeout:   3 * time.Second,
    BatchSize: 50,
    Enabled:   true,
}

Environment variables (TRACESTAX_API_KEY, TRACESTAX_WORKER_ID, TRACESTAX_ENABLED) are read automatically if the corresponding config field is zero-valued.

---

Graceful shutdown

Call client.Close() to flush any buffered events before your process exits:

client := tracestax.NewClient(cfg)
defer client.Close() // flushes pending events, waits up to 5s

---

Testing

// Use the provided no-op client in unit tests
client := tracestax.NewNoopClient()

Or disable via environment:

client := tracestax.NewClient(tracestax.Config{
    Enabled: os.Getenv("GO_ENV") != "test",
})