Go SDK

The Bitfab Go SDK captures your AI function calls to automatically generate evaluations. Re-run your prompts with different models, parameters, and inputs to iterate faster.

Framework-native adapters (LangGraph, OpenAI Agents, BAML, Claude Agent SDK) are not yet available for Go. See Frameworks overview for current coverage. Instrument Go code manually via client.Span or client.Start.

Installation

go get github.com/Project-White-Rabbit/bitfab-go

Quick Start

package main

import (
	"context"
	"os"
	"time"

	bitfab "github.com/Project-White-Rabbit/bitfab-go"
)

func main() {
	client := bitfab.NewClient(os.Getenv("BITFAB_API_KEY"))
	ctx := context.Background()

	client.Span(ctx, "my-service", func(ctx context.Context) (any, error) {
		return map[string]any{"result": "..."}, nil
	})

	client.FlushTraces(5 * time.Second)
}

Need an API key? Get one from the Bitfab dashboard or see the API Keys guide for detailed setup instructions.

Coding Agent Prompt (Cursor, Claude Code)

Copy this prompt into your coding agent (tested with Cursor and Claude Code using Sonnet 4.5):

Modify existing Go code to add Bitfab tracing.
Do NOT browse or web search. Use ONLY the API described below.

Bitfab Go SDK (authoritative excerpt):
- Install: `go get github.com/Project-White-Rabbit/bitfab-go`
- Init:
  import bitfab "github.com/Project-White-Rabbit/bitfab-go"
  client := bitfab.NewClient(os.Getenv("BITFAB_API_KEY"))
- Start/End style (PREFERRED for existing functions):
  func myFunc(ctx context.Context, arg1 string) (Result, error) {
      ctx, span := client.Start(ctx, "<trace_function_key>", "<SpanName>", bitfab.WithType("function"))
      defer span.End()
      span.SetInput(arg1)
      result, err := doWork(ctx, arg1)
      if err != nil {
          span.SetError(err)
          return Result{}, err
      }
      span.SetOutput(result)
      return result, nil
  }
- Closure style (for inline code):
  result, err := client.Span(ctx, "<trace_function_key>", func(ctx context.Context) (any, error) {
      return doWork(ctx), nil
  }, bitfab.WithName("<SpanName>"), bitfab.WithType("function"), bitfab.WithInput(args...))
- Fluent API:
  fn := client.GetFunction("<trace_function_key>")
  ctx, span := fn.Start(ctx, "<SpanName>", bitfab.WithType("function"))
  defer span.End()
- Span types: "llm", "agent", "function", "guardrail", "handoff", "custom"
- Always pass ctx from Start or Span callback into nested calls for parent-child linking.
- Always call client.FlushTraces(5 * time.Second) before program exit.

Task:
1) Ensure the bitfab-go module is added (`go get github.com/Project-White-Rabbit/bitfab-go`).
2) Ensure a client is initialized with the API key.
3) Read the codebase and identify ALL AI workflows (LLM calls, agent runs, AI-driven decisions).
4) Present me with a numbered list of workflows you found. For each, describe:
   - What it does
   - Why it's worth instrumenting - what visibility tracing gives you into each step
5) After I choose which workflow(s) to instrument:
   - Add Start/End at the top of each function (preferred) or wrap in Span closure
   - Use SetInput/SetOutput/SetError to capture data
   - Produce a SPAN TREE, not one span. The workflow root gets a span, and so does every step inside it:
     each model call, each read of external state (DB query, HTTP GET, storage, vector search, cache),
     each transform of the model output (parsing, validation, ranking, formatting), each retry or loop
     iteration, and each external write. A single span around the outer function records one input and
     one output for the whole workflow, which leaves per-step diagnosis with nothing to work on. Do not wrap trivial in-memory helpers or per-item work inside a large loop.
   - Pass `ctx` through for nested span support
6) Do not change function signature, behavior, or return value. Minimal diff.

Output:
- First: your numbered list of workflows with why each is worth instrumenting
- After my selection: minimal diffs for go.mod and the instrumented functions

Basic Configuration

// Default (production URL)
client := bitfab.NewClient(apiKey)

// Omit the key: NewClient reads BITFAB_API_KEY from the environment
client := bitfab.NewClient("")

// Set the key via an option instead of the positional argument
client := bitfab.NewClient("", bitfab.WithAPIKey(apiKey))

// Custom service URL
client := bitfab.NewClient(apiKey, bitfab.WithServiceURL("http://localhost:4000"))

// Disable tracing (functions still execute, but no spans are sent)
client := bitfab.NewClient(apiKey, bitfab.WithEnabled(false))

Missing API key doesn’t crash. If the API key is missing, empty, or whitespace-only, the SDK automatically disables tracing and logs a warning. All instrumented functions still execute normally - no spans are sent, no errors are thrown. You don’t need any conditional logic around the API key.

When no key is passed (empty argument and no WithAPIKey), the SDK reads BITFAB_API_KEY from the environment. Unlike the JS and Python SDKs, Go resolves the key eagerly in NewClient: clients are constructed explicitly (normally in main, after env has loaded), so there is no import-time construction-before-env trap to defer around. For standalone programs where a run that emits no traces should be a hard failure, use WithStrict:

// Panics in NewClient if no key resolves, instead of disabling quietly
client := bitfab.NewClient(apiKey, bitfab.WithStrict(true))

Tracing

Trace the whole workflow, not just its entrypoint. A single Start/End around the outer function records one input and one output for everything inside it, which leaves per-step diagnosis and prompt iteration with nothing to work on. Spans exist only where you create them: nesting is automatic, but only between spans that exist.

Give a step its own span when any of these is true:

It calls a model. Always. This is the span you iterate on, compare across experiments, and attach graders to.
It reads external mutable state (DB query, HTTP GET, object storage, vector search, cache). These are the spans you will want to mock on replay.
It writes external state (DB write, queue publish, email, charge, file write). Mark these to mock on replay so a replayed trace does not repeat the side effect.
It transforms the model output (parsing, validation, ranking, formatting), so a quality regression points at the model or at your post-processing.
It retries or loops, one span per attempt or iteration, so a trace shows how many attempts it really took.

Skip trivial in-memory helpers, per-item work inside a large loop (wrap the loop or the batch), and internals a framework integration already captures.

Go replay defaults to MockMarked: closure-style child spans tagged with WithMockOnReplay(true) reuse their recorded output. Untagged child code still runs, so mark or override unsafe side effects before replaying a workflow. Manual Start/End spans cannot skip caller-owned code; use closure-style Client.Span for mockable boundaries.

Worked examples, replay-mocking decisions, and common pitfalls: Instrumentation.

Replay Historical Traces

Client.Replay fetches historical root inputs, decodes them into your current Go function’s parameter types, runs the items concurrently, and creates an experiment in Bitfab. Pass the same top-level function production uses. Replay accepts typed functions with an optional leading context.Context and an optional final error return.

result, err := client.Replay(
    context.Background(),
    "document-pipeline",
    processDocument,
    &bitfab.ReplayOptions{
        Limit:          10,
        MaxConcurrency: 4,
        OnItemStart: func(progress bitfab.ReplayItemStartProgress) {
            bitfab.ReportReplayProgress(progress)
        },
        OnItemFinish: func(progress bitfab.ReplayItemFinishProgress) {
            bitfab.ReportReplayProgress(progress)
        },
    },
)
if err != nil {
    var replayErr *bitfab.ReplayError
    if errors.As(err, &replayErr) {
        log.Printf("replay failed after %d items: %v", len(replayErr.Items), replayErr.Cause)
    }
    log.Fatal(err)
}

encoded, err := bitfab.SerializeReplayResult(result)
if err != nil {
    log.Fatal(err)
}
fmt.Println(encoded)

Replay wraps each invocation in a root span under the supplied trace function key. If the production function also uses Start/End, those spans nest beneath the replay root and retain the same key. The replay context is passed as the function’s leading context.Context, so continue passing the returned context through nested work. ReplayOptions supports:

Limit - recent traces to replay (default 5, maximum 5000). Omitted from the request when TraceIDs is set.
TraceIDs - explicit historical trace IDs (maximum 100). Passed alongside DatasetID or DatasetIDs they pin which members of that selection replay, and the server rejects any ID none of those datasets contains.
Name, ExperimentGroupID, and DatasetID / DatasetIDs - experiment organization and attribution. DatasetIDs runs against several datasets at once, replaying the union of their traces.
GraderIDs - graders attached directly to this experiment.
MaxConcurrency - bounded worker count (default 10).
CodeChangeDescription and CodeChangeFiles - explicit code-change context. When files are omitted, Go checks BITFAB_CODE_CHANGE_PATH and then captures the rename-aware working-tree diff against trunk. DisableCodeChangeCapture opts one replay out.
Mock and MockOverrides - recorded-output strategy and selective substitutions for closure-style child spans.
DBBranch - non-nil enables a trace-time database branch; MinCU, MaxCU, and WarmupSQL tune it.
AdaptInputs - reshape historical positional inputs before type decoding.
OnItemStart and OnItemFinish - lifecycle callbacks with running totals. The finish callback normally includes the new server trace ID after a per-item flush; the final result is the fallback when that delivery cannot be confirmed. Callback panics are isolated from the replay.

When a signature changes, adapt the recorded values into the new positional shape:

type DocumentRequest struct {
    Text  string
    Limit int
}

options := &bitfab.ReplayOptions{
    AdaptInputs: func(inputs []any, ctx bitfab.AdaptContext) ([]any, error) {
        return []any{DocumentRequest{Text: inputs[0].(string), Limit: 20}}, nil
    },
}

result, err := client.Replay(ctx, "document-pipeline", processDocumentV2, options)

Mock child spans

Mark an expensive or unsafe closure-style child span once in production code:

value, err := client.Span(
    ctx,
    "call-model",
    func(ctx context.Context) (any, error) {
        return callModel(ctx, prompt)
    },
    bitfab.WithName("CallModel"),
    bitfab.WithInput(prompt),
    bitfab.WithMockOnReplay(true),
    bitfab.WithMockOutputType[ModelResponse](),
)

The default MockMarked strategy reuses that occurrence’s historical output during replay. Repeated same-name calls are matched in call order; the SDK uses strictly increasing microsecond timestamps so rapid sibling calls remain distinguishable. WithMockOutputType[T]() decodes recorded JSON into the concrete Go type the caller expects; it is unnecessary for primitive or deliberately dynamic any/map outputs. MockNone runs real child code unless an override matches it; MockAll substitutes every recorded child occurrence. A selected occurrence that is missing fails the item closed. Overrides run before the base strategy, with per-call overrides before client-registered overrides:

options := &bitfab.ReplayOptions{
    Mock: bitfab.MockNone,
    MockOverrides: []bitfab.MockOverride{{
        Match: func(node bitfab.SpanNodeMeta) bool {
            return node.TraceFunctionKey == "call-model"
        },
        Resolve: func(ctx bitfab.MockOverrideContext) (any, error) {
            original, err := ctx.GetOriginalOutput()
            if err != nil {
                return nil, err
            }
            return improveRecordedAnswer(original), nil
        },
    }},
}

GetOriginalOutput fetches lazily and is memoized per item. Mocked uploads record whether the output came from recorded history or an override.

Replay against trace-time database state

Every Go root trace now carries a no-I/O wall-clock snapshot reference. To request a historical branch, pass a non-nil DBBranch and read it inside the replayed function:

func processDocument(ctx context.Context, input Document) (Result, error) {
    databaseURL := os.Getenv("DATABASE_URL")
    if branch := bitfab.GetCurrentReplayBranch(ctx); branch != nil {
        databaseURL = branch.DatabaseURL()
    }
    return runWithDatabase(ctx, databaseURL, input)
}

result, err := client.Replay(ctx, "document-pipeline", processDocument, &bitfab.ReplayOptions{
    DBBranch: &bitfab.DBBranchOptions{
        MinCU:     1,
        MaxCU:     1,
        WarmupSQL: "SELECT count(*) FROM documents",
    },
})

Branch resolution runs inside the bounded replay workers, so MaxConcurrency also bounds live branches. A requested branch that cannot be resolved fails that item instead of silently using the live database. The SDK reports whether DatabaseURL() was obtained, includes provisioning timings on the trace and replay item, and releases every branch after the item; the connection string is excluded from branch JSON and formatting.

Bound replay keys

Plain Go function values carry no tracing metadata, so explicit-key replay remains valid. When code wants a declared-key guard, bind the callable:

target := bitfab.BindReplayFunction("document-pipeline", processDocument)
result, err := client.Replay(ctx, "document-pipeline", target, options)

// Or bind once through the fluent API:
result, err = client.GetFunction("document-pipeline").Replay(ctx, processDocument, options)

Passing a bound target to Client.Replay under a different key fails before Bitfab selects any historical traces. An item failure does not stop the batch. ReplayItem.TraceError retains an error or panic from the replayed function, ReplayItem.ReplayError retains setup/adaptation failures, and ReplayItem.Error is the compatible message. A persistence or finalization failure returns *bitfab.ReplayError, whose Items, TestRunID, TestRunURL, and Cause preserve the partial run. Before finalizing, replay flushes the normal OpenTelemetry pipeline. Every carrier keeps a private delivery reference that never goes on the wire; successful ingestion acknowledges those references and returns each server TraceID. Replay finishes immediately when all carriers are acknowledged, and polls final trace status plus expected persisted span counts only when delivery is ambiguous. The final items include both the original trace lineage (OriginalTraceID, OriginalSpanID) and the new server TraceID, plus original duration/token/model measurements, replay duration, and replay token usage. When BITFAB_REPLAY_RESULT_PATH is set, the SDK writes the same structured result JSON there automatically. This is how the Bitfab plugin captures results without parsing stdout.

Custom (Recommended)

Using `Start`/`End` to Instrument Existing Functions

The recommended way to add tracing to existing functions without restructuring them:

func processOrder(ctx context.Context, orderID string, amount float64) (Order, error) {
	ctx, span := client.Start(ctx, "order-processing", "ProcessOrder",
		bitfab.WithType("agent"))
	defer span.End()
	span.SetInput(orderID, amount)

	// Pass the returned ctx down so each step records as a child of this span
	order, err := classifyOrder(ctx, orderID, amount)
	if err != nil {
		span.SetError(err)
		return Order{}, err
	}
	span.SetOutput(order)
	return order, nil
}

func classifyOrder(ctx context.Context, orderID string, amount float64) (Order, error) {
	ctx, span := client.Start(ctx, "order-processing", "ClassifyOrder",
		bitfab.WithType("llm"))
	defer span.End()
	span.SetInput(orderID, amount)

	order, err := callModel(ctx, orderID, amount)
	if err != nil {
		span.SetError(err)
		return Order{}, err
	}
	span.SetOutput(order)
	return order, nil
}

Calling processOrder records one trace with two spans:

ProcessOrder
└── ClassifyOrder

Instrumenting only processOrder would record the same work as a single node. The nesting comes from passing the ctx that Start returns into the next step: hand a step the original ctx and its span becomes a separate root.

Start returns an updated context.Context (for nested span propagation) and an ActiveSpan
defer span.End() ensures the span is always completed and sent
SetInput / SetOutput / SetError record data on the span
End is idempotent - calling it multiple times is safe

Multi-File Projects

For projects with instrumented functions spread across multiple files, create a dedicated package that initializes the client and exposes a function handle. Import it wherever you need to instrument.

// pkg/tracing/tracing.go - single source of truth
package tracing

import (
	"os"
	bitfab "github.com/Project-White-Rabbit/bitfab-go"
)

var Client = bitfab.NewClient(os.Getenv("BITFAB_API_KEY"))
var OrderService = Client.GetFunction("order-processing")

// services/process_order.go
package services

import (
	"context"
	"myapp/pkg/tracing"
	bitfab "github.com/Project-White-Rabbit/bitfab-go"
)

func ProcessOrder(ctx context.Context, orderID string) (Order, error) {
	ctx, span := tracing.OrderService.Start(ctx, "ProcessOrder", bitfab.WithType("agent"))
	defer span.End()
	span.SetInput(orderID)

	// Pass the ctx from Start so ValidateOrder nests under this span
	order, err := ValidateOrder(ctx, orderID)
	if err != nil {
		span.SetError(err)
		return Order{}, err
	}
	span.SetOutput(order)
	return order, nil
}

// services/validate_order.go
package services

import (
	"context"
	"myapp/pkg/tracing"
	bitfab "github.com/Project-White-Rabbit/bitfab-go"
)

func ValidateOrder(ctx context.Context, orderID string) (Order, error) {
	ctx, span := tracing.OrderService.Start(ctx, "ValidateOrder", bitfab.WithType("guardrail"))
	defer span.End()
	span.SetInput(orderID)

	order, err := doWork(ctx, orderID)
	if err != nil {
		span.SetError(err)
		return Order{}, err
	}
	span.SetOutput(order)
	return order, nil
}

// main.go
package main

import (
	"context"
	"myapp/pkg/tracing"
	"myapp/services"
	"time"
)

func main() {
	defer tracing.Client.FlushTraces(5 * time.Second)
	ctx := context.Background()
	services.ProcessOrder(ctx, "order-123")
}

Spans from different files are automatically linked as parent-child when you pass ctx between instrumented functions.

Using `client.Span` (Closure Style)

Wrap inline code in a closure. Output is captured automatically from the return value. Use WithInput to record inputs:

result, err := client.Span(ctx, "order-processing", func(ctx context.Context) (any, error) {
	return map[string]any{"order_id": "123", "total": 100}, nil
}, bitfab.WithName("ProcessOrder"), bitfab.WithType("function"),
   bitfab.WithInput("order-123", 100))

Using `GetFunction` for a Static Trace Key

Bind a trace function key once, then create multiple spans without repeating it:

orderService := client.GetFunction("order-processing")

result, err := orderService.Span(ctx, func(ctx context.Context) (any, error) {
	return map[string]any{"order_id": "123"}, nil
}, bitfab.WithName("ProcessOrder"), bitfab.WithType("function"))

result, err = orderService.Span(ctx, func(ctx context.Context) (any, error) {
	return map[string]any{"valid": true}, nil
}, bitfab.WithName("ValidateOrder"), bitfab.WithType("guardrail"))

Automatic Nesting

Spans nest automatically when you pass ctx from the outer span callback:

client.Span(ctx, "pipeline", func(ctx context.Context) (any, error) {
	// This span becomes a child of the outer span
	client.Span(ctx, "pipeline", func(ctx context.Context) (any, error) {
		// This span becomes a grandchild
		return client.Span(ctx, "pipeline", func(ctx context.Context) (any, error) {
			return map[string]any{"safe": true}, nil
		}, bitfab.WithName("CheckFraud"), bitfab.WithType("guardrail"))
	}, bitfab.WithName("Validate"), bitfab.WithType("guardrail"))

	return map[string]any{"status": "done"}, nil
}, bitfab.WithName("Process"), bitfab.WithType("agent"))

For reusable helpers that should appear only inside an existing trace, pass bitfab.WithCaptureWhen(bitfab.CaptureWhenNested):

helper := func(ctx context.Context) (any, error) {
	return transform(ctx), nil
}
result, err := client.Span(
	ctx,
	"pipeline",
	helper,
	bitfab.WithName("Helper"),
	bitfab.WithCaptureWhen(bitfab.CaptureWhenNested),
)

With no parent span in ctx, helper runs normally without creating a trace. Pass the child context from Span or Start to capture it as a nested span.

Span Options

Parameters:

traceFunctionKey (required): Groups spans under a function key in Bitfab
WithName(name) (optional): Display name. Defaults to the trace function key
WithType(spanType) (optional): Span type. Defaults to "custom". A label only, used to organize and filter spans in the dashboard; it does not change how the span is traced, replayed, or evaluated
WithFunctionName(name) (optional): Override the function name in span data
WithInput(args...) (optional, closure style only): Record input data. A single arg is stored directly; multiple args as a slice
WithCaptureWhen(CaptureWhenNested) (optional): Capture only with an active parent span; otherwise run untraced. Defaults to CaptureWhenAlways; unknown values warn once and use that default

Span Types:

// Valid span types
"llm"       // LLM calls
"agent"     // Agent workflows
"function"  // Function calls
"guardrail" // Safety checks
"handoff"   // Human handoffs
"custom"    // Default

Examples:

// LLM call
client.Span(ctx, "chat-service", func(ctx context.Context) (any, error) {
	return callOpenAI(prompt), nil
}, bitfab.WithName("ChatCompletion"), bitfab.WithType("llm"))

// Safety check
client.Span(ctx, "safety-service", func(ctx context.Context) (any, error) {
	return map[string]any{"safe": true}, nil
}, bitfab.WithName("ContentFilter"), bitfab.WithType("guardrail"))

Span Context

Use span.AddContext() on an ActiveSpan (Start/End style) to attach contextual key-value pairs at runtime - useful when context depends on computed values:

ctx, span := client.Start(ctx, "order-processing", "ProcessOrder",
	bitfab.WithType("function"))
defer span.End()

requestID := generateRequestID()
span.AddContext(map[string]any{"request_id": requestID, "user_id": "u-123"})

Each AddContext call pushes the entire map as one entry. Multiple calls accumulate entries:

span.AddContext(map[string]any{"user_id": "u-123"})
span.AddContext(map[string]any{"request_id": "req-789"})
// Result: contexts: [{"user_id": "u-123"}, {"request_id": "req-789"}]

Span Prompt

Use span.SetPrompt() on an ActiveSpan (Start/End style) to set the prompt string on the current span. This is stored in span_data.prompt and is useful for capturing the exact prompt text sent to an LLM:

func classifyText(ctx context.Context, text string) (string, error) {
	ctx, span := client.Start(ctx, "classification", "ClassifyText",
		bitfab.WithType("llm"))
	defer span.End()
	span.SetInput(text)

	prompt := fmt.Sprintf("Classify the following text: %s", text)
	span.SetPrompt(prompt)
	result, err := llm.Complete(prompt)
	if err != nil {
		span.SetError(err)
		return "", err
	}

	span.SetOutput(result)
	return result, nil
}

The prompt is metadata only. It records the prompt text for display and reference in the dashboard; it does not send the prompt to any model or change what the span executes. The last SetPrompt call wins — it overwrites any previously set prompt on the span. Calling SetPrompt outside a span context is a no-op (it never crashes).

Trace Context

Use bitfab.GetCurrentTrace(ctx) to set context that applies to the entire trace (all spans within a single execution). This is useful for grouping traces by session or attaching trace-level metadata:

result, err := client.Span(ctx, "order-processing", func(ctx context.Context) (any, error) {
	trace := bitfab.GetCurrentTrace(ctx)

	// Set session ID (stored as database column, filterable in dashboard)
	trace.SetSessionID("session-123")

	// Name the trace (its title in Bitfab, searchable and filterable)
	trace.SetName("Order 8f21")

	// Set trace metadata (stored in raw trace data)
	trace.SetMetadata(map[string]any{"region": "us-west-2", "environment": "production"})

	// Add context entries (stored as key-value pairs, accumulates across calls)
	trace.AddContext(map[string]any{"workflow": "checkout-flow", "batch_id": "batch-2024-01"})

	return map[string]any{"status": "completed"}, nil
}, bitfab.WithName("ProcessOrder"), bitfab.WithType("function"))

SetSessionID(id) - Groups traces by user session. Stored as a database column for efficient filtering.
SetName(name) - The trace’s title in Bitfab, and a field you can search and filter on. Use it for the case, ticket, or record the run is about. Unset, the trace is titled by its trace function key.
SetMetadata(map) - Arbitrary key-value metadata on the trace. Merges with existing metadata.
AddContext(map) - Key-value context entries. Accumulates across multiple calls.
TraceID() - Returns the canonical Bitfab trace ID used for persisted lookups.

Read One Persisted Span

Fetch one span without loading the full trace. Repeated name matches default to the last span.

span, err := client.GetTraceSpan(ctx, traceID, bitfab.SpanLookup{
	Name: "GenerateAnswer",
})
first, err := client.GetTraceSpan(ctx, traceID, bitfab.SpanLookup{
	Name: "GenerateAnswer",
	Occurrence: bitfab.FirstSpanOccurrence,
})
exact, err := client.GetTraceSpan(ctx, traceID, bitfab.SpanLookup{ID: spanID})

Both IDs are canonical Bitfab IDs; ingestion source IDs are not accepted. Use bitfab.SpanOccurrenceAt(index) for a zero-based occurrence. A missing trace or span returns nil, nil.

Dropping a Trace

Use bitfab.GetCurrentTrace(ctx).Drop() to discard the in-flight trace. Once flagged, spans that complete afterward are not uploaded at all, and the flag rides out on the completion payload, so when the trace completes the server scrubs any payloads that already raced out (the trace, its external trace, and sibling spans), deletes the archived S3 objects, and marks it dropped instead of completed, keeping only a skeleton audit row. Use it to discard runs you never want stored (health checks, test traffic) or a run you know carries sensitive data.

result, err := client.Span(ctx, "order-processing", func(ctx context.Context) (any, error) {
	if isHealthCheck(ctx) {
		bitfab.GetCurrentTrace(ctx).Drop()
	}

	return map[string]any{"status": "completed"}, nil
}, bitfab.WithName("ProcessOrder"), bitfab.WithType("function"))

Safe to call outside a span (GetCurrentTrace returns nil, and Drop() is a no-op on a nil receiver), and never panics into your application.

Error Handling

Errors are captured in the span and returned to the caller:

result, err := client.Span(ctx, "risky-service", func(ctx context.Context) (any, error) {
	return nil, errors.New("something went wrong")
}, bitfab.WithName("RiskyOperation"), bitfab.WithType("function"))

// err contains "something went wrong"
// The span records the error message and timing

Each error is classified by source. Errors returned by your function are recorded with error_source: "code". SDK-internal errors are recorded with source: "sdk". Both appear in the span’s errors array in the Bitfab dashboard.

Flushing Traces

if !client.FlushTraces(5 * time.Second) { // Wait up to 5s for pending spans
	log.Println("some spans were not delivered")
}

FlushTraces returns false when an export failed or the deadline expired. Go does not have an automatic atexit hook. You must call FlushTraces before your program exits to ensure all pending spans are sent.

Closing a Client

client := bitfab.NewClient(os.Getenv("BITFAB_API_KEY"))
defer client.Close(5 * time.Second)

Close flushes and permanently shuts down the client’s background delivery worker. It is idempotent, and returns false when an export failed or the deadline expired. A closed client no longer records spans, so prefer it over FlushTraces for the final flush in main.

OpenTelemetry Transport

Span delivery runs on OpenTelemetry. This is an internal transport detail: Span, Start/End, and GetFunction still produce Bitfab spans with Bitfab trace IDs, and no OTel type appears in the Bitfab API. The SDK owns a private tracer provider per client and never touches your application’s global OTel provider. Each client lazily starts one bounded batching worker on its first span, so a client that never traces starts no worker. Replay carriers use this same worker. A private carrier reference follows each queued OTel span through batching and trimming but is excluded from the request body. A successful ingestion response returns the server trace IDs and acknowledges the references in that request. Replay polls the status endpoint only as a fallback when the flush leaves delivery unconfirmed.

Variable	Default	Purpose
`BITFAB_OTEL_EXPORT_CONCURRENCY`	`32`	Concurrent direct requests, `1` through `64`.
`BITFAB_OTEL_MAX_REQUEST_BYTES`	`3000000`	Request-size target. Can only be lowered.

A single span may use up to 7,800,000 carrier bytes when its dedicated request gzips below the 3,000,000-byte wire target and remains below the 8,000,000-byte decompressed ingress limit. The carrier is the payload re-escaped into the OTLP attribute. If it does not compress enough, compression is unavailable, or it exceeds the raw ceiling, the SDK replaces its largest fields with <unserializable: too_large_N_bytes> placeholders until it fits the 2,800,000-byte fallback budget. The trim is recorded on the span’s errors so the trace is flagged as incomplete. Adopting OpenTelemetry raises the SDK’s minimum Go version to 1.25. The SDK links only the OpenTelemetry trace SDK, so protobuf and gRPC stay out of your build. See OpenTelemetry Transport Architecture for the full design.

Datasets

client.Datasets creates, reads, and modifies datasets programmatically, with the same operations your coding agent reaches through the Bitfab MCP tools. A dataset is a named bucket of traces under one trace function. Experiments replay against it and its graders score its members.

saved, err := client.Datasets.Save(ctx, bitfab.SaveDatasetParams{
    TraceFunctionKey: "checkout-agent",
    Name:             "Refund failures",
    Description:      "Checkout runs where the refund was declined",
})
if err != nil {
    return err
}
datasetID := saved.Dataset.ID

added, err := client.Datasets.AddTraces(ctx, datasetID, []string{traceID})
if err != nil {
    return err
}
if len(added.SkippedTraceIDs) > 0 {
    log.Println("not in this trace function:", added.SkippedTraceIDs)
}

membership, _ := client.Datasets.ListTraces(ctx, datasetID)
client.Datasets.AddGraders(ctx, datasetID, []string{graderID})
rerun, err := client.Datasets.RerunGraders(ctx, datasetID, bitfab.RerunGradersOptions{})
fmt.Println(rerun.Run.Status, rerun.Run.Result)

Save is an upsert on the dataset name within its trace function, so re-running a program does not accumulate duplicates. Membership and grader calls accept up to 100 ids and report ids they skipped rather than failing the whole call. RemoveTraces only drops membership. Traces are never deleted. RerunGraders waits for the run by default (90 seconds, configurable through Timeout) and returns whatever state it last saw. Set NoWait to return immediately and poll with GetGraderRerun. See the reference for every method and result type.

Getting Started

Primitives

Account

SDKs

Framework Integrations

Integrations

Web Portal

Reference

Changelog

Installation

Quick Start

Basic Configuration

Tracing

Replay Historical Traces

Mock child spans

Replay against trace-time database state

Bound replay keys

Custom (Recommended)

Using `Start`/`End` to Instrument Existing Functions

Multi-File Projects

Using `client.Span` (Closure Style)

Using `GetFunction` for a Static Trace Key

Automatic Nesting

Span Options

Span Context

Span Prompt

Trace Context

Read One Persisted Span

Dropping a Trace

Error Handling

Flushing Traces

Closing a Client

OpenTelemetry Transport

Datasets

​Installation

​Quick Start

​Basic Configuration

​Tracing

​Replay Historical Traces

​Mock child spans

​Replay against trace-time database state

​Bound replay keys

​Custom (Recommended)

​Using Start/End to Instrument Existing Functions

​Multi-File Projects

​Using client.Span (Closure Style)

​Using GetFunction for a Static Trace Key

​Automatic Nesting

​Span Options

​Span Context

​Span Prompt

​Trace Context

​Read One Persisted Span

​Dropping a Trace

​Error Handling

​Flushing Traces

​Closing a Client

​OpenTelemetry Transport

​Datasets

Installation

Quick Start

Basic Configuration

Tracing

Replay Historical Traces

Mock child spans

Replay against trace-time database state

Bound replay keys

Custom (Recommended)

Using `Start`/`End` to Instrument Existing Functions

Multi-File Projects

Using `client.Span` (Closure Style)

Using `GetFunction` for a Static Trace Key

Automatic Nesting

Span Options

Span Context

Span Prompt

Trace Context

Read One Persisted Span

Dropping a Trace

Error Handling

Flushing Traces

Closing a Client

OpenTelemetry Transport

Datasets