Documentation Index
Fetch the complete documentation index at: https://docs.trulayer.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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
Shutdown when the process exits to drain the send queue.
tl := trulayer.NewClient(os.Getenv("TRULAYER_API_KEY"))
defer tl.Shutdown(context.Background())
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)
*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
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
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
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)
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 |
Trace.NewSpan. The TruLayer dashboard uses the span type to group and filter spans.
Context helpers
TraceFromContext
func TraceFromContext(ctx context.Context) *Trace
*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
*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. |
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.
