Go SDK tutorial

This tutorial takes you from a blank Go module to a working instrumented app. Each step is self-contained — skip ahead if you already know the material.

All examples assume TRULAYER_API_KEY is set in your environment. Install the SDK with go get github.com/trulayer/client-go. Requires Go 1.22 or later.

1. Install the SDK

Add the SDK to your module:

go get github.com/trulayer/client-go

The SDK has zero runtime external dependencies — it uses the Go standard library only.

2. Initialise the client

Construct a *Client once at app startup and defer Shutdown so buffered traces flush before your process exits.

package main

import (
    "context"
    "os"

    "github.com/trulayer/client-go/trulayer"
)

func main() {
    ctx := context.Background()

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

    // your application logic here
}

Client is safe for concurrent use. Construct it once and pass it through your application — do not construct a new client per request.

3. Create a trace

A trace represents one unit of work — for example, answering a user question. Call NewTrace, set the input, run your logic, set the output, then call End.

t, ctx := tl.NewTrace(ctx, "answer-question")
t.SetInput("What is the capital of France?")

// ... your logic here ...

t.SetOutput("Paris.")
t.End(ctx)

End is non-blocking. It enqueues the trace data and returns immediately; the background batch sender handles the network call.

4. Add spans for sub-steps

Spans break a trace into individual steps. Create each span from the trace, do the work, then call End on the span before moving to the next step.

t, ctx := tl.NewTrace(ctx, "rag-pipeline")
t.SetInput("What is the capital of France?")

// Retrieval step
rs, rctx := t.NewSpan(ctx, "vector-retrieval", trulayer.SpanTypeRetrieval)
docs := retrieveDocs(rctx, question)
rs.SetOutput("retrieved 3 documents")
rs.End(rctx)

// LLM step
ls, lctx := t.NewSpan(ctx, "llm-answer", trulayer.SpanTypeLLM,
    trulayer.WithSpanModel("gpt-4o-mini"),
    trulayer.WithSpanInput(question),
)
answer := callLLM(lctx, question, docs)
ls.SetOutput(answer)
ls.SetTokens(120, 8)
ls.End(lctx)

t.SetOutput(answer)
t.End(ctx)

The context returned by NewSpan carries the span, which lets the SDK establish parent-child relationships automatically when you nest spans.

5. Choose the right span type

Use the SpanType constants to classify each span:

Constant	Use for
`trulayer.SpanTypeLLM`	Language model calls
`trulayer.SpanTypeTool`	Tool or function calls
`trulayer.SpanTypeRetrieval`	Vector search, document fetch
`trulayer.SpanTypeOther`	Anything else

6. Run a complete example

Below is a runnable program combining everything above. It mirrors the basic_trace demo in the SDK repository.

package main

import (
    "context"
    "log"
    "os"

    "github.com/trulayer/client-go/trulayer"
)

func main() {
    ctx := context.Background()
    apiKey := os.Getenv("TRULAYER_API_KEY")

    tl := trulayer.NewClient(apiKey)
    defer func() { _ = tl.Shutdown(ctx) }()

    t, ctx := tl.NewTrace(ctx, "basic-example")
    t.SetInput("hello")

    s1, ctx := t.NewSpan(ctx, "step-1", trulayer.SpanTypeOther)
    s1.SetOutput("step-1-done")
    s1.End(ctx)

    s2, ctx := t.NewSpan(ctx, "step-2", trulayer.SpanTypeOther)
    s2.SetOutput("step-2-done")
    s2.End(ctx)

    t.SetOutput("world")
    t.End(ctx)

    if err := tl.Flush(ctx); err != nil {
        log.Printf("flush: %v", err)
    }
    log.Printf("trace %s submitted", t.ID())
}

7. Test offline with dry-run mode

Set TRULAYER_DRY_RUN=true to disable all HTTP calls without changing any application code. No API key is required.

TRULAYER_DRY_RUN=true go run ./main.go

The SDK still constructs traces and spans normally — your code runs as usual, but nothing is sent over the network. Use this in CI and unit tests. You can also activate dry-run programmatically by passing an empty API key:

tl := trulayer.NewClient("") // activates dry-run automatically

8. Attach metadata and tags

Use SetMetadata on a trace or span to attach arbitrary key-value data visible in the dashboard. Use SetTag for structured string-only key-value pairs (max 20 keys, 64 characters per key and value).

t, ctx := tl.NewTrace(ctx, "answer-question",
    trulayer.WithTags(map[string]string{
        "env":     "production",
        "user_id": "u_42",
    }),
)

span, ctx := t.NewSpan(ctx, "llm-call", trulayer.SpanTypeLLM)
span.SetMetadata(map[string]interface{}{
    "model_version": "2025-04",
    "temperature":   0.7,
})

Avoid putting PII or secrets in metadata — it is visible to all members of your team in the dashboard.

9. Link to an upstream request ID

Pass WithTraceExternalID to correlate the TruLayer trace with your own request ID:

t, ctx := tl.NewTrace(ctx, "answer-question",
    trulayer.WithTraceExternalID(r.Header.Get("X-Request-Id")),
)

10. Submit feedback

After ingestion you can attach user feedback to a trace. You need the trace ID, which you can capture from t.ID() inside your handler and return it alongside your response.

err := tl.SubmitFeedback(ctx, traceID, trulayer.FeedbackData{
    Label:   "good",
    Comment: "Correct and concise answer.",
})
if err != nil {
    log.Printf("feedback: %v", err)
}

Valid Label values are "good", "bad", and "neutral". You can also pass a numeric Score (*float64) and arbitrary Metadata.

11. Flush before exit in short-lived scripts

In short-lived command-line programs, call Flush explicitly after your main logic to ensure buffered traces are sent before the process exits. Shutdown does this automatically, but calling Flush mid-process lets you confirm delivery before continuing.

if err := tl.Flush(ctx); err != nil {
    log.Printf("flush: %v", err)
}

For long-lived services (HTTP servers, gRPC servers), the periodic flush — every two seconds by default — handles most cases. Wire Shutdown into your graceful-shutdown hook to drain the queue cleanly.

12. Cap shutdown time

In production, set a deadline on Shutdown to avoid holding up your process exit:

shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := tl.Shutdown(shutdownCtx); err != nil {
    log.Printf("shutdown: %v", err)
}

Next steps

Read the Go SDK reference for every method and option.
Browse the API reference for the full HTTP API surface.
See traces and spans for conceptual background.
Learn how to submit feedback from your production app.

Getting started

Core concepts

Python SDK

TypeScript SDK

Go SDK

SDK features

Dashboard

Integrations

Control loop

Guides

Best practices

Reference

Contributing

1. Install the SDK

2. Initialise the client

3. Create a trace

4. Add spans for sub-steps

5. Choose the right span type

6. Run a complete example

7. Test offline with dry-run mode

8. Attach metadata and tags

9. Link to an upstream request ID

10. Submit feedback

11. Flush before exit in short-lived scripts

12. Cap shutdown time

Next steps

​1. Install the SDK

​2. Initialise the client

​3. Create a trace

​4. Add spans for sub-steps

​5. Choose the right span type

​6. Run a complete example

​7. Test offline with dry-run mode

​8. Attach metadata and tags

​9. Link to an upstream request ID

​10. Submit feedback

​11. Flush before exit in short-lived scripts

​12. Cap shutdown time

​Next steps

1. Install the SDK

2. Initialise the client

3. Create a trace

4. Add spans for sub-steps

5. Choose the right span type

6. Run a complete example

7. Test offline with dry-run mode

8. Attach metadata and tags

9. Link to an upstream request ID

10. Submit feedback

11. Flush before exit in short-lived scripts

12. Cap shutdown time

Next steps