Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bitfab.ai/llms.txt

Use this file to discover all available pages before exploring further.

Module: github.com/Project-White-Rabbit/bitfab-go. Go ≥ 1.21. Runtime dependencies: github.com/google/uuid.

​
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"

​
Constructor

​
NewClient

func NewClient(apiKey string, opts ...Option) *Client
ParamTypeDescription
apiKeystringEmpty/whitespace disables tracing with log.Println
opts...OptionFunctional 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.

​
type Client

Opaque struct. Construct via NewClient.

​
(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: Returns fmt.Errorf with message bitfab: invalid span type %q, must be one of: llm, agent, function, guardrail, handoff, custom if WithType is given an unknown value. fn’s own error is captured on the span and returned to the caller.

​
(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.

​
(c *Client) FlushTraces

func (c *Client) FlushTraces(timeout time.Duration)
Waits for all pending background span deliveries, up to timeout. Go has no atexit — always defer client.FlushTraces(...) in main().

​
(c *Client) GetFunction

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

​
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.

​
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 CurrentTrace

type CurrentTrace struct { /* ... */ }
Returned by GetCurrentTrace.

​
(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.

​
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
  • Span HTTP sends run in background goroutines. FlushTraces drains them
  • Trace state is stored in a mutex-protected package-level map keyed by traceID

​
Error Behavior Summary

SituationBehavior
Empty apiKeylog.Println warning, enabled forced to false
SpanFunc returns errorCaptured on span, returned to caller
Invalid WithType value(*Client).Span returns an error; Start does not validate
Panic inside user codeNot recovered — your code panics. The SDK only recovers panics on its own send path
Span transport failureSwallowed. User’s return value / error passes through
ActiveSpan methods on nil receiverNo-op
End() called multiple timesOnly the first call has effect (sync.Once)
GetCurrentTrace(ctx) outside a spanReturns nil