Go SDK reference

This page documents the public surface of github.com/trulayer/client-go. For narrative usage, see the overview and tutorial. For auto-instrumentation, see instruments.

Status: Alpha. APIs are pre-1.0.0 and may change between minor releases. Pin a specific version in production until 1.0.0 ships.

Source and issues

Source: github.com/trulayer/client-go
Issues / bug reports: github.com/trulayer/client-go/issues
Module: github.com/trulayer/client-go on pkg.go.dev

`Client`

The entry point for the SDK. Construct once per process and reuse — Client is safe for concurrent use from multiple goroutines.

`NewClient`

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

Constructs a client. Pass your API key as the first argument. Call Shutdown when the process exits to drain the send queue.

tl := trulayer.NewClient(os.Getenv("TRULAYER_API_KEY"))
defer tl.Shutdown(context.Background())

Pass an empty string for apiKey and set TRULAYER_DRY_RUN=true for offline development or CI.

Client options

Option	Signature	Default	Purpose
`WithBaseURL`	`(u string) ClientOption`	`https://api.trulayer.ai`	Override the API base URL
`WithBatchSize`	`(n int) ClientOption`	`50`	Max traces buffered before a forced flush
`WithFlushInterval`	`(d time.Duration) ClientOption`	`2s`	Periodic flush cadence
`WithHTTPClient`	`(h *http.Client) ClientOption`	stdlib default	Override the HTTP client

`NewTrace`

func (c *Client) NewTrace(ctx context.Context, name string, opts ...TraceOption) (*Trace, context.Context)

Begins a new trace. Returns the *Trace and a child context that carries the trace — pass the child context to downstream calls so spans can link to it.

trace, ctx := tl.NewTrace(ctx, "answer-question")
defer trace.End(ctx)

Trace options

Option	Signature	Purpose
`WithTraceExternalID`	`(id string) TraceOption`	Attach an external identifier (e.g. a request ID)
`WithTags`	`(tags map[string]string) TraceOption`	Structured key-value tags. Max 20 keys, 64 chars per key/value
`WithTraceMetadata`	`(md map[string]interface{}) TraceOption`	Arbitrary metadata map

`Flush`

func (c *Client) Flush(ctx context.Context) error

Blocks until all enqueued traces have been attempted. The context bounds how long Flush waits. Use this at the end of a short-lived process (e.g. a Lambda handler) to ensure all traces ship before the runtime reclaims memory.

`Shutdown`

func (c *Client) Shutdown(ctx context.Context) error

Drains the queue, performs a final flush, and stops the background goroutine. Subsequent NewTrace calls still succeed but the resulting traces will not be sent. Call at process exit — typically via defer. Pass a context with a deadline to cap the drain time:

shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
tl.Shutdown(shutdownCtx)

`SubmitFeedback`

func (c *Client) SubmitFeedback(ctx context.Context, traceID string, f FeedbackData) error

Posts a feedback record for a previously ingested trace. Returns a non-nil error on transport or server failure. In dry-run mode it is a no-op and returns nil.

`Trace`

A unit of work that groups one or more spans. Create via Client.NewTrace.

Methods

Method	Signature	Purpose
`ID`	`() string`	Returns the UUIDv7 trace identifier
`SetInput`	`(s string)`	Record the trace-level input (e.g. the user’s prompt)
`SetOutput`	`(s string)`	Record the trace-level output (e.g. the final response)
`SetModel`	`(m string)`	Record the model identifier
`SetError`	`(msg string)`	Mark the trace as errored; pass an empty string to clear
`SetTag`	`(k, v string)`	Add a single key-value tag. Max 20 keys, 64 chars each
`SetMetadata`	`(md map[string]interface{})`	Merge arbitrary metadata into the trace
`NewSpan`	`(ctx context.Context, name string, spanType SpanType, opts ...SpanOption) (*Span, context.Context)`	Create a child span
`End`	`(ctx context.Context)`	Finalise and queue the trace for sending. Idempotent

`NewSpan`

func (t *Trace) NewSpan(ctx context.Context, name string, spanType SpanType, opts ...SpanOption) (*Span, context.Context)

Creates a new span attached to this trace. The returned context carries the span, so nested spans can find their parent automatically.

span, ctx := trace.NewSpan(ctx, "embed-query", trulayer.SpanTypeRetrieval)
defer span.End(ctx)

Span options

Option	Signature	Purpose
`WithSpanInput`	`(s string) SpanOption`	Initial input string
`WithSpanModel`	`(s string) SpanOption`	Initial model identifier
`WithSpanMetadata`	`(md map[string]interface{}) SpanOption`	Initial metadata map

`Span`

A unit of work inside a trace (e.g. an LLM call, a tool invocation, a retrieval step). Create via Trace.NewSpan.

Methods

Method	Signature	Purpose
`ID`	`() string`	Returns the UUIDv7 span identifier
`SetInput`	`(v string)`	Record the span input (e.g. the prompt)
`SetOutput`	`(v string)`	Record the span output (e.g. the completion)
`SetModel`	`(m string)`	Record the model identifier
`SetTokens`	`(prompt, completion int)`	Record prompt and completion token counts
`SetCost`	`(usd float64)`	Record the USD cost of this span
`SetError`	`(msg string)`	Mark the span as errored
`SetMetadata`	`(md map[string]interface{})`	Merge arbitrary metadata into the span
`End`	`(ctx context.Context)`	Finalise the span and attach it to the parent trace. Idempotent

`SpanType`

type SpanType string

const (
    SpanTypeLLM       SpanType = "llm"
    SpanTypeTool      SpanType = "tool"
    SpanTypeRetrieval SpanType = "retrieval"
    SpanTypeOther     SpanType = "other"
)

Constant	Wire value	Description
`SpanTypeLLM`	`"llm"`	A language model call
`SpanTypeTool`	`"tool"`	A tool or function call
`SpanTypeRetrieval`	`"retrieval"`	A vector search or document fetch step
`SpanTypeOther`	`"other"`	Any other step; use when no other type fits

Pass one of these constants to Trace.NewSpan. The TruLayer dashboard uses the span type to group and filter spans.

Context helpers

`TraceFromContext`

func TraceFromContext(ctx context.Context) *Trace

Returns the active *Trace stored in ctx by NewTrace, or nil if no trace is present. Use this in middleware or auto-instrumentation code that receives a context from the caller rather than constructing a trace itself.

// In a handler that receives a context already carrying a trace:
if trace := trulayer.TraceFromContext(ctx); trace != nil {
    trace.SetTag("user_id", userID)
}

`SpanFromContext`

func SpanFromContext(ctx context.Context) *Span

Returns the active *Span stored in ctx by NewSpan, or nil if no span is present. Useful for attaching metadata inside deeply nested helpers without threading the span explicitly.

if span := trulayer.SpanFromContext(ctx); span != nil {
    span.SetMetadata(map[string]interface{}{"cache_hit": true})
}

Types

`TraceData`

Wire representation of a trace. Returned when you read traces from the API; also the shape of the payload sent to the ingest endpoint.

type TraceData struct {
    ID         string                 // UUIDv7
    ExternalID string                 // optional; correlate with your own request IDs
    Name       string
    Input      string
    Output     string
    Model      string
    LatencyMs  int64
    Cost       float64
    Error      string                 // empty string means no error
    Tags       map[string]string
    Metadata   map[string]interface{}
    Spans      []SpanData
}

`SpanData`

Wire representation of a span.

type SpanData struct {
    ID               string
    ParentSpanID     string             // empty for root spans
    Name             string
    Type             SpanType           // "llm" | "tool" | "retrieval" | "other"
    Input            string
    Output           string
    Model            string
    LatencyMs        int64
    Cost             float64
    Error            string
    PromptTokens     int
    CompletionTokens int
    Metadata         map[string]interface{}
    StartTime        time.Time
    EndTime          *time.Time         // nil until End() is called
}

`FeedbackData`

Payload for Client.SubmitFeedback.

type FeedbackData struct {
    TraceID  string
    Label    string                 // "good" | "bad" | "neutral"
    Score    *float64               // optional 0–1 score
    Comment  string                 // optional free-text
    Metadata map[string]interface{}
}

Auto-instrumentation

InstrumentOpenAI and InstrumentAnthropic live in optional sub-modules. See auto-instrumentation for full documentation.

import instruments_openai "github.com/trulayer/client-go/instruments/openai"
import instruments_anthropic "github.com/trulayer/client-go/instruments/anthropic"

Environment variables

Variable	Values	Description
`TRULAYER_DRY_RUN`	`true`, `1`, `yes`	Disables all HTTP calls without requiring any code changes. No API key is needed. Use in CI and unit tests.

When dry-run mode is active, NewTrace and NewSpan still return valid objects so your code runs normally — no traces are sent over the network.

Error handling

The SDK never panics and never propagates transport or serialisation errors to your call site. Failed flushes are logged with log.Printf and the traces are dropped. In dry-run mode all network operations are skipped silently.

Batches that fail to send are retried up to three times with exponential backoff.
After retries are exhausted, the batch is dropped and a log.Printf warning is emitted.
NewTrace and NewSpan never return errors — failures are contained inside the SDK.

To detect dropped traces in production, watch for trulayer: prefixed log lines at ERROR level from the SDK’s logger. A future release will expose an OnError hook — track github.com/trulayer/client-go/issues for availability.

Getting started

Core concepts

Python SDK

TypeScript SDK

Go SDK

SDK features

Dashboard

Integrations

Control loop

Guides

Best practices

Reference

Contributing

Source and issues

`Client`

`NewClient`

Client options

`NewTrace`

Trace options

`Flush`

`Shutdown`

`SubmitFeedback`

`Trace`

Methods

`NewSpan`

Span options

`Span`

Methods

`SpanType`

Context helpers

`TraceFromContext`

`SpanFromContext`

Types

`TraceData`

`SpanData`

`FeedbackData`

Auto-instrumentation

Environment variables

Error handling

​Source and issues

​Client

​NewClient

​Client options

​NewTrace

​Trace options

​Flush

​Shutdown

​SubmitFeedback

​Trace

​Methods

​NewSpan

​Span options

​Span

​Methods

​SpanType

​Context helpers

​TraceFromContext

​SpanFromContext

​Types

​TraceData

​SpanData

​FeedbackData

​Auto-instrumentation

​Environment variables

​Error handling

Source and issues

`Client`

`NewClient`

Client options

`NewTrace`

Trace options

`Flush`

`Shutdown`

`SubmitFeedback`

`Trace`

Methods

`NewSpan`

Span options

`Span`

Methods

`SpanType`

Context helpers

`TraceFromContext`

`SpanFromContext`

Types

`TraceData`

`SpanData`

`FeedbackData`

Auto-instrumentation

Environment variables

Error handling