Go SDK auto-instrumentation

The Go SDK ships two optional auto-instrumentation sub-modules. Each wraps a provider client so every completion call becomes a TruLayer span automatically — no manual NewSpan / End calls required. The sub-modules are separate Go modules so you only pull in the provider SDK you actually use.

Install

# OpenAI auto-instrumentation
go get github.com/trulayer/client-go/instruments/openai

# Anthropic auto-instrumentation
go get github.com/trulayer/client-go/instruments/anthropic

How context-based trace-carrying works

Both instruments read the active trace from the context.Context you pass to each call. tl.NewTrace stores the trace in the context it returns. You pass that context down through your call stack — including to the instrumented client — and the instrument picks up the trace automatically.

tl.NewTrace(ctx, "op")
    └── returns (trace, ctx)  ← trace is stored in ctx
         └── client.Chat.Completions.New(ctx, req)
              └── instrument reads trace from ctx, opens a span

If no trace is found in the context, the instrument is a passthrough — it calls the underlying provider method unchanged and records nothing.

`InstrumentOpenAI`

import (
    "github.com/openai/openai-go"
    instruments_openai "github.com/trulayer/client-go/instruments/openai"
)

func InstrumentOpenAI(client *openai.Client, tl *trulayer.Client) *InstrumentedOpenAIClient

Wraps an *openai.Client. The returned *InstrumentedOpenAIClient intercepts Chat.Completions.New and records each call as a SpanTypeLLM span on the active trace.

What is recorded automatically

Field	Source
`span.name`	`"openai.chat.completions"`
`span.type`	`"llm"`
`span.model`	`params.Model`
`span.input`	Last user message from `params.Messages`
`span.output`	`response.Choices[0].Message.Content`
`span.prompt_tokens`	`response.Usage.PromptTokens`
`span.completion_tokens`	`response.Usage.CompletionTokens`
`span.error`	Error message if `Chat.Completions.New` returns a non-nil error

Full example

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/openai/openai-go"
    "github.com/trulayer/client-go/trulayer"
    instruments_openai "github.com/trulayer/client-go/instruments/openai"
)

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

    oai := openai.NewClient()
    client := instruments_openai.InstrumentOpenAI(&oai, tl)

    ctx := context.Background()
    trace, ctx := tl.NewTrace(ctx, "summarise-article")
    defer trace.End(ctx)

    trace.SetInput("Summarise the history of the internet.")

    resp, err := client.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{
        Model: openai.ChatModelGPT4oMini,
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("Summarise the history of the internet."),
        },
    })
    if err != nil {
        trace.SetError(err.Error())
        return
    }

    answer := resp.Choices[0].Message.Content
    trace.SetOutput(answer)
    fmt.Println(answer)
}

The Chat.Completions.New call is traced as a child span of "summarise-article" automatically. You do not need to open or close the span manually.

`InstrumentAnthropic`

import (
    anthropic "github.com/anthropics/anthropic-sdk-go"
    instruments_anthropic "github.com/trulayer/client-go/instruments/anthropic"
)

func InstrumentAnthropic(client *anthropic.Client, tl *trulayer.Client) *InstrumentedAnthropicClient

Wraps an *anthropic.Client. The returned *InstrumentedAnthropicClient intercepts Messages.New and records each call as a SpanTypeLLM span on the active trace.

What is recorded automatically

Field	Source
`span.name`	`"anthropic.messages"`
`span.type`	`"llm"`
`span.model`	`params.Model`
`span.input`	Serialised `params.Messages`
`span.output`	First text block in `response.Content`
`span.prompt_tokens`	`response.Usage.InputTokens`
`span.completion_tokens`	`response.Usage.OutputTokens`
`span.error`	Error message if `Messages.New` returns a non-nil error

Full example

package main

import (
    "context"
    "fmt"
    "os"

    anthropic "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
    "github.com/trulayer/client-go/trulayer"
    instruments_anthropic "github.com/trulayer/client-go/instruments/anthropic"
)

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

    ac := anthropic.NewClient(option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")))
    client := instruments_anthropic.InstrumentAnthropic(ac, tl)

    ctx := context.Background()
    trace, ctx := tl.NewTrace(ctx, "classify-sentiment")
    defer trace.End(ctx)

    trace.SetInput("Classify the sentiment of: 'The product is amazing!'")

    msg, err := client.Messages.New(ctx, anthropic.MessageNewParams{
        Model:     anthropic.ModelClaude4Sonnet,
        MaxTokens: 256,
        Messages: []anthropic.MessageParam{
            anthropic.NewUserTextMessage("Classify the sentiment of: 'The product is amazing!'"),
        },
    })
    if err != nil {
        trace.SetError(err.Error())
        return
    }

    answer := msg.Content[0].Text
    trace.SetOutput(answer)
    fmt.Println(answer)
}

Nil-trace passthrough behaviour

Both instruments check for an active trace in the context before opening a span. If the context carries no trace — for example, because a code path calls the provider client outside a NewTrace block — the instrument calls the underlying provider method directly and returns its result unchanged. No span is recorded and no error is returned. This means you can safely instrument a shared client instance that is called from both traced and untraced code paths.

Combining auto-instrumentation with manual spans

Auto-instrumented spans are children of the active trace, at the same level as any manual spans you open. You can mix both styles freely:

trace, ctx := tl.NewTrace(ctx, "rag-pipeline")
defer trace.End(ctx)

// Manual retrieval span
retrievalSpan, ctx := trace.NewSpan(ctx, "vector-search", trulayer.SpanTypeRetrieval)
docs := vectorDB.Search(ctx, query)
retrievalSpan.SetOutput(fmt.Sprintf("%d documents", len(docs)))
retrievalSpan.End(ctx)

// Auto-instrumented LLM span — no manual span needed
resp, err := openaiClient.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{
    Model:    openai.ChatModelGPT4oMini,
    Messages: buildMessages(query, docs),
})

In the TruLayer dashboard the trace shows both spans in timeline order: your manual "vector-search" retrieval span followed by the auto-recorded "openai.chat" LLM span.

Accessing the active trace in other helpers

If you need to annotate the trace from inside a helper that only receives a context, use trulayer.TraceFromContext:

func recordUserID(ctx context.Context, userID string) {
    if trace := trulayer.TraceFromContext(ctx); trace != nil {
        trace.SetTag("user_id", userID)
    }
}

Similarly, use trulayer.SpanFromContext to access the innermost active span:

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

Getting started

Core concepts

Python SDK

TypeScript SDK

Go SDK

SDK features

Dashboard

Integrations

Control loop

Guides

Best practices

Reference

Contributing

Go SDK auto-instrumentation

Install

How context-based trace-carrying works

`InstrumentOpenAI`

What is recorded automatically

Full example

`InstrumentAnthropic`

What is recorded automatically

Full example

Nil-trace passthrough behaviour

Combining auto-instrumentation with manual spans

Accessing the active trace in other helpers

​Install

​How context-based trace-carrying works

​InstrumentOpenAI

​What is recorded automatically

​Full example

​InstrumentAnthropic

​What is recorded automatically

​Full example

​Nil-trace passthrough behaviour

​Combining auto-instrumentation with manual spans

​Accessing the active trace in other helpers

Install

How context-based trace-carrying works

`InstrumentOpenAI`

What is recorded automatically

Full example

`InstrumentAnthropic`

What is recorded automatically

Full example

Nil-trace passthrough behaviour

Combining auto-instrumentation with manual spans

Accessing the active trace in other helpers