Go SDK Reference

Module: github.com/Project-White-Rabbit/bitfab-go. Go ≥ 1.25. Runtime dependencies: github.com/google/uuid, go.opentelemetry.io/otel, go.opentelemetry.io/otel/trace, go.opentelemetry.io/otel/sdk.

Framework Integrations

No framework-native adapters are shipped for Go yet. Instrument Go code manually via client.Span / client.Start - see the Go SDK guide. Framework coverage status: Frameworks overview.

Package Constants

const DefaultServiceURL = "https://bitfab.ai"

type CaptureWhen string

const (
    CaptureWhenAlways CaptureWhen = "always"
    CaptureWhenNested CaptureWhen = "nested"
)

Constructor

`NewClient`

func NewClient(apiKey string, opts ...Option) *Client

Param	Type	Description
`apiKey`	`string`	Empty/whitespace disables tracing with `log.Println`
`opts`	`...Option`	Functional options

`Option`

type Option func(*Client)

`WithServiceURL`

func WithServiceURL(url string) Option

`WithEnabled`

func WithEnabled(enabled bool) Option

When false: Span still executes the callback, Start returns a no-op *ActiveSpan, no data sent.

Transport environment variables

Variable	Default	Description
`BITFAB_OTEL_MAX_REQUEST_BYTES`	`3000000`	Request-size target for OTLP/JSON exports; accepts positive integers up to `3000000`
`BITFAB_OTEL_EXPORT_CONCURRENCY`	`32`	Concurrent direct requests per export window; accepts `1` through `64`

`type Client`

Opaque struct. Construct via NewClient.

Span lookup types

type SpanLookup struct {
    ID         string
    Name       string
    Occurrence SpanOccurrence
}

const FirstSpanOccurrence SpanOccurrence = "first"
const LastSpanOccurrence SpanOccurrence = "last"
func SpanOccurrenceAt(index int) SpanOccurrence

CapturedSpan contains the normalized span identity, parent, name, type, input, output, contexts, prompt, metadata, metrics, errors, and timestamps.

`(c *Client) Span`

func (c *Client) Span(
    ctx context.Context,
    traceFunctionKey string,
    fn SpanFunc,
    opts ...SpanOption,
) (any, error)

Executes fn inside a traced span. fn’s return value is captured as the span output. Returns: fn’s (any, error) return values. Errors: Only fn’s own error, captured on the span and returned to the caller. Tracing never fails the call: an unknown WithType value degrades to custom (with a one-time warning) instead of returning an error, and any internal instrumentation failure runs fn untraced rather than crashing the host.

`(c *Client) Start`

func (c *Client) Start(
    ctx context.Context,
    traceFunctionKey string,
    spanName string,
    opts ...SpanOption,
) (context.Context, *ActiveSpan)

Start/End-style span for instrumenting existing functions. Always call defer span.End(). Returns a child context carrying the span, and an *ActiveSpan for recording data. When enabled == false, returns the original context and a zero *ActiveSpan whose methods are all no-ops. Spans exist only where you create them: nesting is automatic, but only between spans that exist. One wrapper around the outermost function records a single-node trace. See Instrumentation.

`(c *Client) FlushTraces`

func (c *Client) FlushTraces(timeout time.Duration) bool

Drains this client’s pending span deliveries, up to timeout. Returns false when an export failed or the deadline expired. Use it for a mid-run flush, such as before reading a span back with GetTraceSpan.

`(c *Client) Close`

func (c *Client) Close(timeout time.Duration) bool

Flushes pending spans and permanently shuts down this client’s OpenTelemetry worker. Idempotent; returns false when an export failed or the deadline expired. A closed client no longer records spans. Go has no atexit - always defer client.Close(...) in main().

`(c *Client) GetFunction`

func (c *Client) GetFunction(traceFunctionKey string) *Function

`(c *Client) GetTraceSpan`

func (c *Client) GetTraceSpan(
    ctx context.Context,
    traceID string,
    lookup SpanLookup,
) (*CapturedSpan, error)

Fetches one persisted span without loading its trace. traceID is the canonical Bitfab trace ID. Set exactly one of the span’s Bitfab SpanLookup.ID or SpanLookup.Name. Name lookup defaults to the last match; use FirstSpanOccurrence or SpanOccurrenceAt(index) to override it. A miss returns nil, nil.

`type SpanFunc`

type SpanFunc func(ctx context.Context) (any, error)

`type SpanOption`

type SpanOption func(*spanConfig)

`WithName`

func WithName(name string) SpanOption

Defaults to traceFunctionKey for Span, or the spanName arg for Start.

`WithType`

func WithType(spanType string) SpanOption

One of "llm", "agent", "function", "guardrail", "handoff", "custom". Validated at span creation time for Span (returns an error on invalid). Defaults to "custom".

`WithFunctionName`

func WithFunctionName(name string) SpanOption

Recorded as span_data.function_name.

`WithInput`

func WithInput(args ...any) SpanOption

One arg stored directly. Multiple args stored as a slice. Only relevant to Span - for Start, use ActiveSpan.SetInput.

`WithCaptureWhen`

func WithCaptureWhen(captureWhen CaptureWhen) SpanOption

CaptureWhenNested records the span only when ctx contains an active Bitfab parent span. Without a parent, Span runs the callback untraced and Start returns the original context with a no-op ActiveSpan. The default is CaptureWhenAlways; unknown values warn once and use that default.

`type Function`

type Function struct { /* ... */ }

Obtained via (*Client).GetFunction(key). Fluent wrapper that binds traceFunctionKey.

`(f *Function) Span`

func (f *Function) Span(ctx context.Context, fn SpanFunc, opts ...SpanOption) (any, error)

`(f *Function) Start`

func (f *Function) Start(ctx context.Context, spanName string, opts ...SpanOption) (context.Context, *ActiveSpan)

`type ActiveSpan`

Returned by Start. All methods are safe on nil, safe under recover(), and idempotent where noted.

`(s *ActiveSpan) SetInput`

func (s *ActiveSpan) SetInput(args ...any)

One arg stored directly. Multiple args stored as a slice. No-op on nil receiver.

`(s *ActiveSpan) SetOutput`

func (s *ActiveSpan) SetOutput(output any)

`(s *ActiveSpan) SetError`

func (s *ActiveSpan) SetError(err error)

`(s *ActiveSpan) AddContext`

func (s *ActiveSpan) AddContext(context map[string]any)

Appends the map as one entry on span_data.contexts. No-op when context == nil.

`(s *ActiveSpan) SetPrompt`

func (s *ActiveSpan) SetPrompt(prompt string)

Overwrites span_data.prompt. No-op on empty string.

`(s *ActiveSpan) End`

func (s *ActiveSpan) End()

Idempotent via sync.Once. Sends the span in a background goroutine. Any panic inside the send path is recovered so the host app never crashes.

Trace-Level API

`type ContextEntry`

type ContextEntry = map[string]any

`type CurrentSpan`

type CurrentSpan struct { /* ... */ }
func GetCurrentSpan(ctx context.Context) *CurrentSpan
func (cs *CurrentSpan) ID() string
func (cs *CurrentSpan) TraceID() string

Returns the active span’s canonical Bitfab span and trace IDs. GetCurrentSpan returns nil outside a span; both methods are safe on a nil receiver and return "".

`type CurrentTrace`

type CurrentTrace struct { /* ... */ }

Returned by GetCurrentTrace.

`(ct *CurrentTrace) TraceID`

func (ct *CurrentTrace) TraceID() string

Returns the canonical Bitfab trace ID. Safe on a nil receiver, where it returns "".

`(ct *CurrentTrace) SetSessionID`

func (ct *CurrentTrace) SetSessionID(sessionID string)

`(ct *CurrentTrace) SetMetadata`

func (ct *CurrentTrace) SetMetadata(metadata map[string]any)

Shallow-merges with existing trace metadata. Later keys win.

`(ct *CurrentTrace) AddContext`

func (ct *CurrentTrace) AddContext(context map[string]any)

Appends. Accumulates across calls.

`(ct *CurrentTrace) Drop`

func (ct *CurrentTrace) Drop()

Flags the trace to be dropped. Once flagged, spans that complete afterward are not uploaded at all, and the flag rides out on the completion payload, so at completion 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. Safe on a nil receiver (a no-op, so GetCurrentTrace(ctx).Drop() outside a span does nothing). Never panics.

`GetCurrentTrace`

func GetCurrentTrace(ctx context.Context) *CurrentTrace

Returns nil when ctx carries no active span. Callers must nil-check.

Concurrency Model

Nested span context is carried on context.Context - safe across goroutines that inherit the context
Goroutines that do not inherit the context will not see the parent span
Spans are queued on a private OpenTelemetry batching worker, one per client, started lazily on the first span. Queueing is non-blocking; FlushTraces and Close drain the worker
Trace state is stored in a mutex-protected package-level map keyed by traceID

Error Behavior Summary

Situation	Behavior
Empty `apiKey`	`log.Println` warning, `enabled` forced to `false`
`SpanFunc` returns error	Captured on span with `error_source: "code"`, returned to caller
Invalid `WithType` value	`(*Client).Span` returns an error; `Start` does not validate
Panic inside user code	Not recovered - your code panics. The SDK only recovers panics on its own send path
Span transport failure	Swallowed. User’s return value / error passes through
`ActiveSpan` methods on `nil` receiver	No-op
`End()` called multiple times	Only the first call has effect (`sync.Once`)
`GetCurrentTrace(ctx)` outside a span	Returns `nil`

​Framework Integrations

​Package Constants

​Constructor

​NewClient

​Option

​WithServiceURL

​WithEnabled

​Transport environment variables

​type Client

​Span lookup types

​(c *Client) Span

​(c *Client) Start

​(c *Client) FlushTraces

​(c *Client) Close

​(c *Client) GetFunction

​(c *Client) GetTraceSpan

​type SpanFunc

​type SpanOption

​WithName

​WithType

​WithFunctionName

​WithInput

​WithCaptureWhen

​type Function

​(f *Function) Span

​(f *Function) Start

​type ActiveSpan

​(s *ActiveSpan) SetInput

​(s *ActiveSpan) SetOutput

​(s *ActiveSpan) SetError

​(s *ActiveSpan) AddContext

​(s *ActiveSpan) SetPrompt

​(s *ActiveSpan) End

​Trace-Level API

​type ContextEntry

​type CurrentSpan

​type CurrentTrace

​(ct *CurrentTrace) TraceID

​(ct *CurrentTrace) SetSessionID

​(ct *CurrentTrace) SetMetadata

​(ct *CurrentTrace) AddContext

​(ct *CurrentTrace) Drop

​GetCurrentTrace

​Concurrency Model

​Error Behavior Summary