Go

Instrument Go services with traces, logs, errors, and request-scoped customer identity.

Use the Go SDK for server-side traces, metrics, structured logs, errors, diagnostic events, and customer identity.

Install and start

go get github.com/getteml/teml/sdks/go@main

ctx := context.Background()
client, err := teml.New(
	teml.WithAPIKey(os.Getenv("TEML_API_KEY")),
	teml.WithServiceName("orders-api"),
	teml.WithEnvironment("production"),
)
if err != nil {
	return err
}
if err := client.Start(ctx); err != nil {
	return err
}

defer func() {
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	_ = client.Stop(shutdownCtx)
}()

Keep one client for the application. A client per request prevents batching and correlation.

Use a project-scoped key with ingest:write. Add analytics:write when calling Identify, Group, or diagnostic-event methods, as this guide does. Do not give an application key read or management scopes.

Trace work and capture errors

requestCtx := teml.ContextWithDistinctID(ctx, userID)
traceCtx, span := client.StartSpan(requestCtx, "process-order")
defer span.End()

if err := processOrder(traceCtx); err != nil {
	client.CaptureError(traceCtx, err, teml.WithTag("component", "checkout"))
	return err
}

Pass the returned context through downstream calls. Request-scoped identity is concurrency-safe and takes precedence over process identity. Use client.Identify only for a single-user process or an explicit identity merge, and reset identity on logout in stateful client applications.

HTTP and gRPC propagation

Use the SDK’s HTTP transport or gRPC interceptors with the request context so W3C traceparent and the teml.distinct_id baggage member continue to trusted downstream services. At inbound public boundaries, do not accept customer identity baggage unless a trusted gateway has removed and recreated client-supplied headers.

For net/http, derive the Teml request context from r.Context() and pass it through handlers, database operations, and outbound requests. Equivalent instrumentation packages are available for gRPC and supported framework adapters.

Structured logs

The client exposes an slog logger and the process-level LogEvent convenience method. Use the logger’s context-aware methods for request work so records inherit the active trace and customer identity.

client.Logger().LogAttrs(
	traceCtx,
	slog.LevelInfo,
	"order processed",
	slog.String("order_id", orderID),
)

LogEvent uses a background context and therefore cannot inherit request-scoped correlation.

Keep secrets, authorization headers, and unfiltered request bodies out of attributes.

Record AI calls

Optional OpenAI and Anthropic instrumentation packages wrap non-streaming client calls and record model, tokens, latency, and calculated cost. Content capture is off by default; enabling it can send prompt and completion text as span events.

Verify and recover

Send one request with ContextWithDistinctID, then open Customers and confirm the trace, log, and test error appear under the same customer. If they do not, enable SDK debug logging, check the key, endpoint, and project, and confirm Stop completes before the shutdown deadline.