Browse documentation

Reference

Go SDK API

Interfaces, functions, options, parameters, return values, and helpers for the Anectico Go SDK.

This is the application-developer API for github.com/anectico/anectico/sdks/go. The SDK is safe for concurrent use and follows Go/OpenTelemetry context conventions.

Use ingest:write for traces, metrics, logs, and errors. Add analytics:write for identity, groups, events, and flag exposures; add flags:read for decisions.

Construct and run a client

client, err := anectico.New(
	 anectico.WithAPIKey(os.Getenv("ANECTICO_API_KEY")),
	 anectico.WithServiceName("orders-api"),
)
if err != nil {
	return err
}
if err := client.Start(ctx); err != nil {
	return err
}
defer client.Stop(shutdownCtx)

API	Parameters	Returns	Behavior
`New(opts ...Option)`	functional options	`(Client, error)`	Creates an unstarted client or returns a configuration or transport-initialization error.
`Start(ctx)`	lifecycle context	`error`	Validates config and starts enabled transports.
`Stop(ctx)`	deadline/cancellation context	`error`	Marks the client non-running, flushes, and releases client-owned providers. Final trace, metric, or log upload failures are returned. Concurrent calls share one terminal result.
`IsRunning()`	—	`bool`	Whether the client accepts telemetry.
`Health()`	—	`HealthStatus`	State, recent errors, uptime, and per-signal counters.
`Stats()`	—	`ClientStats`	Processed/dropped/export-failure counters and timestamps.

The first Stop caller owns the transport shutdown, bounded by the earlier of its context deadline and ShutdownTimeout. Other callers wait for that operation and receive the identical completed error or nil. If a waiter’s context ends first, only that wait returns ctx.Err(); the owner continues the shared shutdown. Calls made after completion return the cached terminal result. Start waits for an in-flight stop before beginning a fresh lifecycle, at which point the next Stop creates a new operation.

For signal-driven or fatal shutdown, catch SIGTERM or os.Interrupt, call Stop with a bounded context, and inspect its error before exiting. Deferred calls do not run after os.Exit. SIGKILL is not catchable and therefore has no final-flush guarantee; configure the process supervisor’s termination grace period to cover the shutdown deadline.

Keep one client per service. Pass request contexts through all instrumentation so trace and person correlation remain intact.

Core `Client` methods

Method	Parameters	Returns	Behavior
`Tracer()`	—	OTel `trace.Tracer`	Underlying tracer for advanced instrumentation.
`Meter()`	—	OTel `metric.Meter`	Underlying meter for advanced instrumentation.
`Logger()`	—	`*slog.Logger`	Structured logger backed by the Anectico log provider. Use context-aware methods for request work.
`StartSpan(ctx, name, opts...)`	context; name; OTel options	`(context.Context, trace.Span)`	Starts a span and returns the child context. Caller must end the span.
`RecordMetric(name, value, labels)`	name; float; string map	—	Records one gauge value and caches the instrument by name. It has no context parameter.
`LogEvent(level, message, attrs...)`	`slog.Level`; message; attributes	—	Convenience log using a background context. Use `Logger().LogAttrs(ctx, ...)` for correlation.
`RecordLLMCall(ctx, opts)`	context; `LLMCallOptions`	—	Records one completed model call as a `gen_ai` span and directly attaches the resolved `anectico.distinct_id`, including with a caller-supplied tracer provider.
`RecordToolCall(ctx, name, opts)`	context; tool name/options	—	Records one completed tool execution.
`StartAgentRun(ctx, agent, opts)`	context; agent name/options	`(context.Context, AgentRun)`	Starts an agent span and returns its child context plus a safe handle. Call `run.End(status, reasonCode)`; the first valid terminal outcome wins.
`WrapHTTPClient(client)`	`*http.Client`	`*http.Client`	Returns a client that propagates trace and Anectico identity context. Its generated transport spans are Issue-suppressed; restrict its destinations.
`WrapHTTPTransport(base)`	`http.RoundTripper`	`http.RoundTripper`	Wraps a transport for outbound propagation/instrumentation and Issue-suppresses its generated client spans.
`GRPCDialOptions()`	—	`[]grpc.DialOption`	Installs the client stats handler for gRPC tracing and propagation.

LLMCallOptions.Model is required. Other fields are ResponseModel, Provider, Operation, token counts, CostUSD, FinishReason, IsError, StartTime, and EndTime. Messages and Output are opt-in content. ToolCallOptions provides Type, CallID, ConversationID, AgentName, IsError, and opt-in Arguments/Result. AgentRunOptions provides AgentID and ConversationID. Agent-run status is completed, failed, timed_out, cancelled, or max_steps. The optional reason is normalized to a lowercase code matching [a-z][a-z0-9_]{0,63}; free text is rejected. Calling run.Span().End() directly bypasses this contract and produces only the legacy inferred status, so use run.End(...) for normal completion.

Package-level WrapHTTPClient, WrapHTTPTransport, GRPCDialOptions, and GRPCClientStatsHandler provide the same integration helpers when a Client reference is not available.

Errors, messages, users, and breadcrumbs

Method	Parameters	Returns	Behavior
`CaptureError(ctx, err, opts...)`	context; error; `ErrorOption`s	`string`	Captures an error and returns its generated ID; returns empty when capture is unavailable/sampled out.
`CaptureMessage(ctx, message, level, opts...)`	context; text; `ErrorLevel`; options	`string`	Captures a diagnostic message.
`AddBreadcrumb(category, message, opts...)`	category/message; breadcrumb options	—	Buffers trail context for the next captured error.
`SetUser(user)`	`*User`	—	Sets process-global error user context.
`GetUser(ctx)`	request context	`*User`	Returns context-local user first, then global user.
`ClearUser()`	—	—	Clears global error user context.

User contains ID, Email, Username, IPAddress, Segment, and Data. Use ContextWithUser(ctx, user) for concurrent request-local error context.

Error option	Purpose
`WithLevel`	Override `debug`, `info`, `warning`, `error`, or `fatal`.
`WithTag`	Add one indexed tag.
`WithTags`	Add multiple indexed tags.
`WithExtra(key, value)`	Add one unindexed context value.
`WithErrorExtra(map)`	Add several unindexed context values in one option.
`WithUser`	Override user for one capture.
`WithFingerprint(parts...)`	Override grouping; comma separates components and `{{default}}` includes automatic grouping.
`WithStackTrace(pcs)`	Supply program counters rather than capture the current stack.
`WithErrorTimestamp(time)`	Supply the event timestamp.

WithTag and WithTags keys are encoded as indexed anectico.tag.* telemetry attributes automatically. Capture severity is also indexed as error.level for Issue filtering and context.

WithBreadcrumbLevel(level) sets severity and WithBreadcrumbData(map) attaches structured breadcrumb context.

Identity and groups

API	Parameters	Returns	Behavior
`client.Identify(ctx, distinctID, props)`	context; stable ID; person properties	`error`	Sets shared identity and synchronously sends the identity event.
`client.Group(ctx, groupType, groupKey, props)`	context; account type/key; properties	`error`	Records membership and `$groupidentify`.
`client.Reset(ctx)`	context	`error`	Logout: rotates anonymous identity and clears groups, global error-user context, and uncaptured breadcrumbs. Already-captured telemetry remains queued with its original attribution.
`ContextWithDistinctID(ctx, id)`	context; stable ID	`context.Context`	Sets request-local identity for concurrency-safe server work.
`DistinctIDFromContext(ctx)`	context	`(string, bool)`	Reads request-local identity.
`AdoptDistinctIDFromBaggage(ctx)`	context	context	Promotes trusted inbound baggage into request scope.
`DiscardDistinctIDFromBaggage(ctx)`	context	context	Removes untrusted Anectico identity baggage while preserving other context.

Never adopt a public client’s identity baggage until a trusted gateway has authenticated the request and recreated that baggage.

Diagnostic events: `Analytics`

events := anectico.NewAnalytics(anectico.AnalyticsConfig{
	Endpoint: "https://api.anectico.com",
	APIKey:   os.Getenv("ANECTICO_API_KEY"),
})
defer events.Stop(ctx)

AnalyticsConfig fields are Endpoint, APIKey, FlushAt (default 20), Interval (zero means 5 seconds; negative disables the timer), and optional HTTPClient (default timeout 10 seconds).

API	Parameters	Returns	Behavior
`NewAnalytics(config)`	`AnalyticsConfig`	`*Analytics`	Starts a background flusher using a background lifecycle context.
`NewAnalyticsWithContext(ctx, config)`	lifecycle context/config	`*Analytics`	Stops the background flusher when context is canceled; still call `Stop` to flush.
`Capture(ctx, event, props, opts...)`	context; name; properties; capture options	`error`	Queues an event using shared identity unless overridden.
`Identify(ctx, distinctID, props, opts...)`	context; ID; properties; options	`error`	Queues an identity merge without changing process-global identity; safe for multi-person server batches.
`Group(ctx, type, key, props, opts...)`	context; group; properties; options	`error`	Queues membership and switches shared group state.
`Flush(ctx)`	deadline context	`error`	Sends queued events in chunks, requeuing retryable failures.
`Reset(ctx)`	context	`error`	Rotates shared anonymous identity.
`Stop(ctx)`	deadline context	`error`	Stops the flusher and sends the remaining queue. Capture after stop returns `ErrAnalyticsClosed`.

Per-call options are WithDistinctID, WithAnonDistinctID, and WithSessionID. Use WithAnonDistinctID when each server-side merge has its own anonymous alias. For a stateful single-user/client application that should switch the shared identity used by later signals, call client.Identify instead.

Feature flags: `Flags`

FlagsConfig fields are Endpoint, APIKey, optional HTTPClient, optional Bootstrap, and an optional Capture(ctx, event, props, distinctID) callback for exposures. The key needs flags:read; the exposure callback usually calls Analytics.Capture and therefore needs analytics:write.

Method	Parameters	Returns	Behavior
`NewFlags(config)`	`FlagsConfig`	`*Flags`	Builds a concurrency-safe in-memory decision client.
`Reload(ctx, distinctID, personProperties, groups)`	targeting context	`error`	Calls `/api/v1/decide`; nil groups use shared memberships.
`GetFeatureFlag(ctx, key, distinctID)`	context; key; ID	`any`	Returns bool/variant/nil and emits one deduplicated exposure.
`IsFeatureEnabled(ctx, key, distinctID)`	context; key; ID	`bool`	True for `true` or a non-empty string variant.
`GetFeatureFlagPayload(key)`	key	`json.RawMessage`	Returns a copy of the payload or nil.
`GetAllFlags()`	—	`map[string]any`	Returns a copy of cached decisions.
`HadEvaluationErrors()`	—	`bool`	Whether the last decision used a fallback.
`Reset()`	—	—	Clears exposure dedup after identity changes.
`NewLocalFlagsClient(config)`	`LocalFlagsConfig{Endpoint, APIKey, ProjectID, HTTPClient?, Capture?, Now?}`	`(*LocalFlagsClient, error)`	Creates one exact-project cache; snapshot reads require `flags:read`, and an Anectico-backed `Capture` requires `analytics:write`.
`LocalFlagsClient.Refresh(ctx)`	context	`(LocalRefreshStatus, error)`	Fetches or conditionally revalidates a strict, bounded snapshot while retaining the last-known-good cache on failure.
`LocalFlagsClient.Evaluate(ctx, key, distinctID, personProperties)`	context, flag key, exact identity, person properties	`LocalEvaluationResult`	Evaluates only a fresh snapshot and emits a successful exposure through optional `Capture`.
`LocalFlagsClient.Reset()`	—	—	Clears local `(identity,key,value)` exposure deduplication; preserves the snapshot.

NewLocalFlagsClient(LocalFlagsConfig) creates the project-bound server-side evaluator; ProjectID must be one exact canonical UUID. Refresh(ctx) uses strong conditional validators and serializes concurrent refreshes. Evaluate(ctx, key, distinctID, personProperties) returns a LocalEvaluationResult and fails closed when the snapshot is missing/stale, the identity is empty, or the rule requires authoritative cohort/group data. LocalFlagsConfig.Capture mirrors FlagsConfig.Capture: successful matched/default decisions emit $feature_flag_called once per identity/key/value, and Reset() reopens the dedup set without dropping the snapshot. A callback wired to Analytics.Capture also requires analytics:write.

Configuration options

Options apply in order. WithConfig(config) is normally first; later options override its fields.

Option family	Functions and effect
Identity	`WithServiceName`, `WithServiceVersion`, `WithEnvironment`, `WithProjectID`.
Authentication	`WithAPIKey` selects API-key auth; `WithJWTToken` selects JWT auth. Application integrations should use a project API key.
Endpoint/transport	`WithEndpoint`, `WithProtocol("grpc"\|"http")`, `WithInsecure`, `WithHeaders`, `WithHeader`.
TLS	`WithTLS`, `WithTLSCerts(cert,key,ca)`, `WithTLSCA`, `WithTLSServerName`; `WithInsecureTLS` skips verification and is development-only.
Batching	`WithBatchTimeout`, `WithBatchSize`, `WithMaxQueueSize`, `WithExportTimeout`, `WithShutdownTimeout`, `WithRetryConfig`.
Signals/sampling	`WithTraceSampleRate`, `WithTraces`, `WithMetrics`, `WithLogs`, `WithAllTelemetry`.
Diagnostics	`WithDebug`, `WithLogLevel`, `WithLogOutput`.
Resources	`WithResourceAttribute`, `WithResourceAttributes`.
Errors	`WithErrorCapture`, `WithErrorSampleRate`, `WithMaxStackTraceFrames`, `WithAttachStackTrace`, `WithErrorEnvironment`, `WithErrorRelease`.
Providers	`WithTracerProvider` uses a caller-owned OTel provider and enables traces; the caller shuts it down after the Anectico client.
Presets	`WithProductionDefaults`, `WithDevelopmentDefaults`, `WithTestingDefaults`, `WithKubernetesDefaults`, `WithDockerDefaults`. Apply a preset before options that should override it.

Defaults include gRPC, a 10% trace sample rate, 100% captured errors, batch size 512, queue size 2048, 5-second batch/shutdown timeouts, 30-second exports, and three retry attempts. DefaultConfig() reads the equivalent ANECTICO_* and OTEL_* environment variables; Config.Validate() checks required values and bounds.

Managed Go providers attach the standard OpenTelemetry SDK resource identity to every trace, metric, and log: telemetry.sdk.language=go, telemetry.sdk.name=opentelemetry, and the active OpenTelemetry Go SDK version in telemetry.sdk.version. These reserved attributes describe the emitting SDK and cannot be overridden with WithResourceAttribute(s). Anectico does not implicitly enable host or process resource detectors; add any reviewed infrastructure attributes explicitly.

The managed tracer provider uses parent-based sampling: local and remote child spans preserve the parent’s sampled or unsampled W3C decision, while WithTraceSampleRate applies only to new root traces. error.capture and message.capture spans are always retained so explicit error/message capture is not lost when ordinary traces are sampled out. WithTracerProvider remains fully caller-owned; Anectico neither replaces its sampler nor applies these managed-provider rules.

Authentication and error helpers

ValidateAPIKey, IsAPIKeyFormat, and MaskAPIKey support configuration UIs. IsAuthError, IsNetworkError, IsRetryableError, GetErrorSuggestion, and WrapGRPCError support custom transports. Prefer returning these errors rather than matching their strings.

Advanced configuration and utility API

API	Parameters	Returns/behavior
`DefaultConfig()`	—	`Config` populated from supported `ANECTICO_`/`OTEL_*` variables and safe defaults.
`config.Validate()`	—	`error` for missing credentials/identity or inconsistent protocol, sampling, queues, timeouts, and TLS.
`config.GetEndpointForSignal(signal)`	`traces`, `metrics`, or `logs`	Signal-specific OTLP endpoint.
`config.GetHeadersForSignal(signal)`	signal name	Copy of headers including active authentication.
`config.Logger()`	—	SDK diagnostic `*slog.Logger`.
`NewTransport(config)`	validated `*Config`	`(Transport, error)` for custom lifecycle ownership; most applications should use `Client`.
`TLSConfig.Validate()`	—	Rejects incomplete certificate pairs and unsafe/inconsistent TLS bounds.
`TLSConfig.GetStandardTLSConfig()`	—	`(*tls.Config, error)` for HTTP transports.
`TLSConfig.GetTLSCredentials()`	—	`(credentials.TransportCredentials, error)` for gRPC.
`ContextWithUser(ctx, user)`	context; `*User`	Request-local error user.
`UserFromContext(ctx)`	context	Request-local `*User` or nil.
`user.ToOTelAttributes()`	—	OpenTelemetry `enduser.` and `user.data.` attributes.
`CaptureStackTrace(skip)`	number of caller frames to skip	Structured `[]StackFrame` for a custom error integration.
`GetPoolStats()` / `ResetPoolStats()`	—	SDK allocation-pool counters, and a test/debug reset.

Config exposes the same fields represented by the functional options: service identity, credentials, endpoint/protocol/headers/TLS, batch and retry values, signal switches, sampling, logging, resources, and error settings. TLSConfig additionally accepts Enabled, InsecureSkipVerify, certificate/key/CA files, ServerName, TLS version bounds, and cipher suites. The package’s typed sentinel errors (ErrUnauthorized, ErrForbidden, ErrInvalidAPIKey, ErrExpiredToken, ErrRateLimited, ErrInvalidCredentials, ErrConnectionFailed, ErrTimeout, and ErrServiceUnavailable) are compatible with errors.Is.

Framework and model-provider packages

Package/API	Parameters	Returns	Behavior
`instrumentation/openai.WrapClient(anecticoClient, client, opts...)`	Anectico client; official OpenAI client; options	instrumented client	Wraps `Chat.Completions.New` and `NewStreaming` calls while preserving provider responses, chunks, errors, and stream iteration.
`instrumentation/openai.WithCaptureContent()`	—	wrapper option	Opts into prompt/completion content; off by default.
`instrumentation/anthropic.WrapClient(anecticoClient, client, opts...)`	Anectico client; official Anthropic client; options	instrumented client	Wraps non-streaming `Messages.New` calls and preserves provider results/errors.
`instrumentation/anthropic.WithCaptureContent()`	—	wrapper option	Opts into prompt/completion content; off by default.
`instrumentation/gin.Middleware(client)` / `MiddlewareWithOptions(client, opts)`	Anectico client; optional `Options`	Gin handler	Creates inbound request spans and request-scoped propagation, captures `c.Errors`, and captures handler panics recovered by Gin as one canonical Issue occurrence.
`instrumentation/echo.Middleware(client)` / `MiddlewareWithOptions(client, opts)`	Anectico client; optional `Options`	Echo middleware	Creates inbound request spans and request-scoped propagation. `DefaultSkipper` is the exported standard skip predicate.
`instrumentation/fiber.Middleware(client)` / `MiddlewareWithOptions(client, opts)`	Anectico client; optional `Options`	Fiber handler	Creates inbound request spans and request-scoped propagation. `DefaultNext` skips standard health paths; `GetSpan(ctx)` reads the active request span.
`instrumentation/grpc.UnaryServerInterceptor(client)` / `UnaryServerInterceptorWithOptions(client, opts)`	client; optional `ServerOptions`	unary server interceptor	Extracts trace context, creates the server span, and optionally adopts trusted identity.
`instrumentation/grpc.StreamServerInterceptor(client)` / `StreamServerInterceptorWithOptions(client, opts)`	client; optional `ServerOptions`	stream server interceptor	Instruments stream lifetime and propagation.
`instrumentation/grpc.UnaryClientInterceptor(client)` / `StreamClientInterceptor(client)`	client	client interceptor	Copies existing metadata, injects W3C trace/identity context, and traces RPCs. Stream completion is idempotent; transport errors remain spans rather than duplicate Issues.
`instrumentation/grpc.CombinedServerInterceptors(client)`	client	`[]grpc.ServerOption`	Installs both server interceptors.
`instrumentation/grpc.CombinedClientInterceptors(client)`	client	`[]grpc.DialOption`	Installs both client interceptors.

OpenAI NewStreaming keeps the official Next/Current/Err/Close flow and automatically requests the terminal usage chunk. Exhausted streams record the model, finish reason, and exact token/cache counts that OpenAI returned. Provider stream failures, context cancellation, and closing before the terminal usage chunk or exhaustion record one error-status model call. Always close the stream, normally with defer stream.Close(). Anthropic streaming methods are not wrapped. Content capture can record sensitive text and remains off unless WithCaptureContent is supplied.

Gin Options supports TrustIncomingIdentity, SkipPaths, request/response body capture, MaxBodySize, custom attributes, span naming, filtering, captured-header allowlists, and sensitive header redaction. Gin Recovery can be registered before or after Anectico; the configured recovery still controls the response. Registering Recovery first (the gin.Default() order) retains the original panic value in Anectico. When Recovery is inside Anectico, Gin has already discarded that value, so Anectico records a generic panic message with the handler stack. In both orders, the failed server span stays visible and correlated in Traces while the stacked error.capture child is the only Issue occurrence. Echo provides the same controls through Skipper (rather than SkipPaths and a filter). Fiber supports Next, custom attributes, span naming, and header controls. Every HTTP package exports WithSkipHealthCheck() and WithCaptureAllHeaders() presets. Body or header capture can collect secrets; keep it disabled unless a reviewed debugging need requires it. gRPC ServerOptions contains TrustIncomingIdentity and an explicit CaptureMetadata allowlist.

Package-level and client-bound HTTP client/transport wrappers mark their generated outbound spans with anectico.issue.suppressed=true. Transport failures and cancellations keep their normal span status, trace/baggage propagation, and HTTP metrics, so they remain diagnosable in Traces without producing stackless Issues. To turn an actionable dependency failure into an Issue, translate it into an explicit typed application/domain error after retries are exhausted and call CaptureError once at that boundary.

The custom gRPC client interceptors inject the newly started client span as traceparent/tracestate and propagate request identity in W3C baggage. Generated client calls must receive the request context that carries the active span and anectico.ContextWithDistinctID value. A client stream span ends on EOF, the single response of a client-streaming RPC, a failed stream operation, or caller cancellation. Successful CloseSend does not end the response side. Concurrent or repeated terminal signals end the span once while returning the original gRPC status unchanged. Client transport statuses do not create Issues. The server interceptor captures one occurrence for unexpected server failures (Unknown, ResourceExhausted, Unimplemented, Internal, Unavailable, or DataLoss). Cancellation, deadlines, and expected caller/control statuses remain visible as error-status spans without becoming Issues. Non-canonical transport spans carry anectico.issue.suppressed=true; when server CaptureError succeeds, its transport parent also carries the returned error.id. This suppression remains exact if exporter batches separate or reorder the parent and canonical error.capture child. If server capture is disabled, sampled out, fails, or returns no ID, the actionable server transport span is left eligible as the fallback Issue. For an external dependency, explicitly capture one typed domain error after retries are exhausted when the failure should become an Issue.