tracekit

package
v1.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 14, 2026 License: MIT Imports: 41 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrUnsupportedExpression = errors.New("unsupported expression: requires server-side evaluation")

ErrUnsupportedExpression indicates the expression requires server-side evaluation.

Functions

func EvaluateCondition added in v1.5.1 

func EvaluateCondition(expression string, env map[string]interface{}) (bool, error)

EvaluateCondition evaluates an expression string against the given environment and returns a boolean result. Empty expressions return true (no condition = always fire). Returns ErrUnsupportedExpression for expressions that require server-side evaluation.

func EvaluateExpression added in v1.5.1 

func EvaluateExpression(expression string, env map[string]interface{}) (interface{}, error)

EvaluateExpression evaluates an expression and returns the raw result. Unlike EvaluateCondition, this does not require a boolean result. Returns ErrUnsupportedExpression for server-only expressions.

func EvaluateExpressions added in v1.5.1 

func EvaluateExpressions(expressions []string, env map[string]interface{}) map[string]interface{}

EvaluateExpressions evaluates multiple expressions against the given environment. Results are keyed by expression string. On error, nil is stored for that expression.

func ExtractClientIP added in v1.3.0 

func ExtractClientIP(r *http.Request) string

ExtractClientIP extracts the client IP address from an HTTP request. It checks X-Forwarded-For, X-Real-IP headers (for proxied requests) and falls back to RemoteAddr. This function is used by the HTTP middleware to automatically add client IP to traces.

func GetRequestContext added in v1.0.3 

func GetRequestContext(c *gin.Context) map[string]interface{}

GetRequestContext retrieves the request context from Gin context

func IsSDKEvaluable added in v1.5.1 

func IsSDKEvaluable(expression string) bool

IsSDKEvaluable returns true if the expression can be evaluated locally by the SDK. Returns false for expressions containing function calls, regex operators, assignment, array indexing, ternary, range, template literals, or bitwise operators.

Types

type BreakpointConfig 

type BreakpointConfig struct {
	ID                 string                 `json:"id"`
	ServiceName        string                 `json:"service_name"`
	FilePath           string                 `json:"file_path"`
	FunctionName       string                 `json:"function_name"`
	Label              string                 `json:"label,omitempty"` // Stable identifier
	LineNumber         int                    `json:"line_number"`
	Condition          string                 `json:"condition,omitempty"`
	MaxCaptures        int                    `json:"max_captures"`
	CaptureCount       int                    `json:"capture_count"`
	ExpireAt           *time.Time             `json:"expire_at,omitempty"`
	Enabled            bool                   `json:"enabled"`
	Metadata           map[string]interface{} `json:"metadata,omitempty"`
	Mode               string                 `json:"mode,omitempty"`                // "snapshot" or "logpoint"
	StackDepth         *int                   `json:"stack_depth,omitempty"`         // nil = default (full trace)
	MaxDepth           *int                   `json:"max_depth,omitempty"`           // nil = legacy unlimited
	MaxPayloadBytes    *int                   `json:"max_payload_bytes,omitempty"`   // nil = legacy unlimited
	ConditionEval      string                 `json:"condition_eval,omitempty"`      // "sdk-evaluable" or "server-only"
	CaptureExpressions []string               `json:"capture_expressions,omitempty"` // expressions for logpoint mode
}

BreakpointConfig represents a breakpoint configuration

type CaptureConfig added in v1.4.0 

type CaptureConfig struct {
	CaptureDepth   int           // 0 = unlimited depth (default)
	MaxPayload     int           // 0 = unlimited payload bytes (default)
	CaptureTimeout time.Duration // 0 = no timeout (default)
	Debug          bool          // Enable debug logging
	PIIScrubbing   *bool         // nil or true = enabled (default), false = disabled
	PIIPatterns    []PIIPattern  // Additional custom PII patterns appended to built-in set

	// Circuit breaker config -- nil means use defaults (3 failures in 60s, 5min cooldown)
	CircuitBreaker *CircuitBreakerConfig
}

CaptureConfig holds opt-in capture limit settings. All limits are disabled by default (zero values = unlimited).

type CircuitBreakerConfig added in v1.4.0 

type CircuitBreakerConfig struct {
	MaxFailures int   // default 3: failures before tripping
	WindowMs    int64 // default 60000: failure counting window (ms)
	CooldownMs  int64 // default 300000: time circuit stays open (ms)
}

CircuitBreakerConfig allows users to override circuit breaker thresholds. Zero values mean "use defaults".

type Config 

type Config struct {
	// Required
	APIKey      string
	ServiceName string

	// Optional - defaults to app.tracekit.dev
	// Can be just the host (app.tracekit.dev) or full URL
	Endpoint string

	// Optional - defaults to /v1/traces
	TracesPath string

	// Optional - defaults to /v1/metrics
	MetricsPath string

	// Optional - defaults to true (use TLS)
	UseSSL bool

	// Optional - service version
	ServiceVersion string

	// Optional - deployment environment
	Environment string

	// Optional - additional resource attributes
	ResourceAttributes map[string]string

	// Optional - enable code monitoring
	EnableCodeMonitoring bool

	// Optional - code monitoring poll interval (default: 30s)
	CodeMonitoringPollInterval time.Duration

	// Optional - sampling rate (0.0 to 1.0, default: 1.0 = 100%)
	SamplingRate float64

	// Optional - batch timeout (default: 5s)
	BatchTimeout time.Duration

	// Optional - map hostnames to service names for peer.service attribute
	// Useful for mapping localhost URLs to actual service names
	// Example: map[string]string{"localhost:8084": "node-test-app", "localhost:8082": "go-test-app"}
	ServiceNameMappings map[string]string

	// Optional - LLM instrumentation configuration
	// When set, NewLLMTransport will use these settings.
	// If nil, DefaultLLMConfig() is used.
	InstrumentLLM *LLMConfig
}

Config holds the TraceKit SDK configuration

type Counter added in v1.3.1 

type Counter interface {
	Inc()
	Add(value float64)
}

Counter tracks monotonically increasing values

type Gauge added in v1.3.1 

type Gauge interface {
	Set(value float64)
	Inc()
	Dec()
}

Gauge tracks point-in-time values

type Histogram added in v1.3.1 

type Histogram interface {
	Record(value float64)
}

Histogram tracks value distributions

type LLMConfig added in v1.5.0 

type LLMConfig struct {
	// Enabled is the master toggle for LLM instrumentation (default: true).
	Enabled bool

	// OpenAI enables OpenAI-specific instrumentation (default: true).
	OpenAI bool

	// Anthropic enables Anthropic-specific instrumentation (default: true).
	Anthropic bool

	// CaptureContent enables capturing prompt/completion content (default: false).
	// Can be overridden by TRACEKIT_LLM_CAPTURE_CONTENT env var.
	CaptureContent bool
}

LLMConfig holds configuration for LLM auto-instrumentation.

func DefaultLLMConfig added in v1.5.0 

func DefaultLLMConfig() LLMConfig

DefaultLLMConfig returns an LLMConfig with sensible defaults.

type LLMOption added in v1.5.0 

type LLMOption func(*LLMTransport)

LLMOption is a functional option for configuring NewLLMTransport.

func WithCaptureContent added in v1.5.0 

func WithCaptureContent(capture bool) LLMOption

WithCaptureContent enables or disables content capture.

func WithLLMConfig added in v1.5.0 

func WithLLMConfig(cfg LLMConfig) LLMOption

WithLLMConfig sets the LLM configuration for the transport.

type LLMTransport added in v1.5.0 

type LLMTransport struct {
	// contains filtered or unexported fields
}

LLMTransport is an http.RoundTripper that automatically instruments OpenAI and Anthropic API calls with OpenTelemetry GenAI semantic conventions.

Usage: 

transport := tracekit.NewLLMTransport(nil)
httpClient := &http.Client{Transport: transport}
// Pass httpClient to OpenAI/Anthropic Go SDK

func NewLLMTransport added in v1.5.0 

func NewLLMTransport(base http.RoundTripper, opts ...LLMOption) *LLMTransport

NewLLMTransport creates an LLMTransport that wraps the given base transport. If base is nil, http.DefaultTransport is used. The tracer is obtained from the global OpenTelemetry tracer provider.

func (*LLMTransport) RoundTrip added in v1.5.0 

func (t *LLMTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper. It detects OpenAI and Anthropic API calls, instruments them with GenAI spans, and passes all other requests through.

type PIIPattern added in v1.4.0 

type PIIPattern struct {
	Pattern *regexp.Regexp
	Marker  string // e.g., "[REDACTED:email]"
}

PIIPattern represents a pattern for detecting and redacting sensitive data

type SDK 

type SDK struct {
	// contains filtered or unexported fields
}

SDK is the main TraceKit SDK client

func NewSDK 

func NewSDK(config *Config) (*SDK, error)

NewSDK creates and initializes the TraceKit SDK

func (*SDK) AddAttribute 

func (s *SDK) AddAttribute(span trace.Span, key, value string)

AddAttribute adds a string attribute to a span

func (*SDK) AddAttributes 

func (s *SDK) AddAttributes(span trace.Span, attrs ...attribute.KeyValue)

AddAttributes adds multiple attributes to a span

func (*SDK) AddBoolAttribute 

func (s *SDK) AddBoolAttribute(span trace.Span, key string, value bool)

AddBoolAttribute adds a boolean attribute to a span

func (*SDK) AddBusinessAttributes 

func (s *SDK) AddBusinessAttributes(span trace.Span, attrs map[string]interface{})

AddBusinessAttributes adds business-specific attributes (order ID, transaction ID, etc.)

func (*SDK) AddDatabaseAttributes 

func (s *SDK) AddDatabaseAttributes(span trace.Span, dbSystem, dbName, operation, table string)

AddDatabaseAttributes adds common database attributes to a span

func (*SDK) AddEvent 

func (s *SDK) AddEvent(span trace.Span, name string, attrs ...attribute.KeyValue)

AddEvent adds an event to a span

func (*SDK) AddFloatAttribute 

func (s *SDK) AddFloatAttribute(span trace.Span, key string, value float64)

AddFloatAttribute adds a float attribute to a span

func (*SDK) AddHTTPAttributes 

func (s *SDK) AddHTTPAttributes(span trace.Span, method, url string, statusCode int)

AddHTTPAttributes adds common HTTP attributes to a span

func (*SDK) AddIntAttribute 

func (s *SDK) AddIntAttribute(span trace.Span, key string, value int64)

AddIntAttribute adds an integer attribute to a span

func (*SDK) AddUserAttributes 

func (s *SDK) AddUserAttributes(span trace.Span, userID, email string)

AddUserAttributes adds user-related attributes to a span

func (*SDK) CheckAndCapture added in v1.0.2 

func (s *SDK) CheckAndCapture(filePath string, lineNumber int, variables map[string]interface{})

CheckAndCapture checks if there's a breakpoint and captures a snapshot

func (*SDK) CheckAndCaptureWithContext added in v1.0.4 

func (s *SDK) CheckAndCaptureWithContext(ctx context.Context, label string, variables map[string]interface{})

CheckAndCaptureWithContext is a wrapper for code monitoring snapshot capture with context It automatically registers the breakpoint location - no need to manually create breakpoints!

label: Optional stable identifier (e.g. "payment-error", "auth-check") 

If empty, uses auto-generated label based on function name

func (*SDK) Counter added in v1.3.1 

func (s *SDK) Counter(name string, tags map[string]string) Counter

SDK methods for metrics

func (*SDK) EchoMiddleware 

func (s *SDK) EchoMiddleware() echo.MiddlewareFunc

EchoMiddleware returns an Echo middleware with OpenTelemetry instrumentation

func (*SDK) GRPCClientInterceptors 

func (s *SDK) GRPCClientInterceptors() []grpc.DialOption

GRPCClientInterceptors returns gRPC client interceptors with OpenTelemetry

func (*SDK) GRPCServerInterceptors 

func (s *SDK) GRPCServerInterceptors() []grpc.ServerOption

GRPCServerInterceptors returns gRPC server interceptors with OpenTelemetry

func (*SDK) Gauge added in v1.3.1 

func (s *SDK) Gauge(name string, tags map[string]string) Gauge

func (*SDK) GinMiddleware 

func (s *SDK) GinMiddleware() gin.HandlerFunc

GinMiddleware returns a Gin middleware with OpenTelemetry instrumentation It captures request context for code monitoring and adds client IP to spans

func (*SDK) GormPlugin 

func (s *SDK) GormPlugin() gorm.Plugin

GormPlugin returns a GORM plugin with OpenTelemetry instrumentation Use with: db.Use(sdk.GormPlugin())

func (*SDK) HTTPClient 

func (s *SDK) HTTPClient(client *http.Client) *http.Client

HTTPClient wraps an http.Client with OpenTelemetry instrumentation Automatically creates CLIENT spans for outgoing HTTP calls with peer.service attribute

func (*SDK) HTTPHandler 

func (s *SDK) HTTPHandler(handler http.Handler, operation string) http.Handler

HTTPHandler wraps an http.Handler with OpenTelemetry instrumentation and automatically captures client IP address

func (*SDK) HTTPMiddleware 

func (s *SDK) HTTPMiddleware(operation string) func(http.Handler) http.Handler

HTTPMiddleware returns a middleware function for standard http.Handler chains

func (*SDK) Histogram added in v1.3.1 

func (s *SDK) Histogram(name string, tags map[string]string) Histogram

func (*SDK) MongoClientOptions 

func (s *SDK) MongoClientOptions() *options.ClientOptions

MongoClientOptions returns MongoDB client options with OpenTelemetry instrumentation

func (*SDK) NewLLMTransport added in v1.5.0 

func (s *SDK) NewLLMTransport(base http.RoundTripper, opts ...LLMOption) *LLMTransport

NewLLMTransport creates an LLM-instrumented HTTP transport using this SDK's tracer and LLM configuration. If base is nil, http.DefaultTransport is used.

Usage with OpenAI Go SDK: 

transport := sdk.NewLLMTransport(nil)
httpClient := &http.Client{Transport: transport}
openaiClient := openai.NewClient(option.WithHTTPClient(httpClient))

func (*SDK) RecordError 

func (s *SDK) RecordError(span trace.Span, err error)

RecordError records an error on a span with stack trace and marks it as error

func (*SDK) RecordErrorWithMessage 

func (s *SDK) RecordErrorWithMessage(span trace.Span, err error, message string)

RecordErrorWithMessage records an error with a custom message

func (*SDK) SetError 

func (s *SDK) SetError(span trace.Span, message string)

SetError marks a span as error with a message (without recording an error object)

func (*SDK) SetSuccess 

func (s *SDK) SetSuccess(span trace.Span)

SetSuccess marks a span as successful

func (*SDK) SetSuccessWithMessage 

func (s *SDK) SetSuccessWithMessage(span trace.Span, message string)

SetSuccessWithMessage marks a span as successful with a message

func (*SDK) Shutdown 

func (s *SDK) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the SDK

func (*SDK) SnapshotClient 

func (s *SDK) SnapshotClient() *SnapshotClient

SnapshotClient returns the code monitoring client (nil if not enabled)

func (*SDK) StartSpan 

func (s *SDK) StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

StartSpan starts a new span with the given name

func (*SDK) TraceFunction 

func (s *SDK) TraceFunction(ctx context.Context, name string, fn func(context.Context, trace.Span) error) error

TraceFunction wraps a function with automatic span creation

func (*SDK) TraceGormDB 

func (s *SDK) TraceGormDB(db *gorm.DB) error

TraceGormDB adds tracing to an existing GORM DB instance

func (*SDK) Tracer 

func (s *SDK) Tracer() trace.Tracer

Tracer returns the underlying OpenTelemetry tracer

func (*SDK) WithGormTracing 

func (s *SDK) WithGormTracing(config *gorm.Config) *gorm.Config

WithGormTracing is a helper to configure a GORM DB with tracing Example: 

db, err := gorm.Open(postgres.Open(dsn), sdk.WithGormTracing(&gorm.Config{}))

func (*SDK) WrapDB 

func (s *SDK) WrapDB(db *sql.DB, dbSystem string) *TracedDB

WrapDB wraps a database/sql DB with OpenTelemetry tracing This creates traced versions of all database operations

func (*SDK) WrapMongoClient 

func (s *SDK) WrapMongoClient(client *mongo.Client) *mongo.Client

WrapMongoClient wraps an existing MongoDB client with OpenTelemetry (not recommended, use MongoClientOptions instead) Note: This should be called before any operations on the client

func (*SDK) WrapRedis 

func (s *SDK) WrapRedis(client *redis.Client) error

WrapRedis adds OpenTelemetry instrumentation to a Redis client using hooks

func (*SDK) WrapRedisCluster 

func (s *SDK) WrapRedisCluster(client *redis.ClusterClient) error

WrapRedisCluster adds OpenTelemetry instrumentation to a Redis cluster client

func (*SDK) WrapRoundTripper 

func (s *SDK) WrapRoundTripper(rt http.RoundTripper) http.RoundTripper

WrapRoundTripper wraps an http.RoundTripper with OpenTelemetry instrumentation

type SecurityFlag added in v1.2.0 

type SecurityFlag struct {
	Type     string `json:"type"`
	Severity string `json:"severity"`
	Variable string `json:"variable,omitempty"`
}

SecurityFlag represents a security issue found in snapshot variables

type Snapshot 

type Snapshot struct {
	BreakpointID      string                 `json:"breakpoint_id"`
	ServiceName       string                 `json:"service_name"`
	FilePath          string                 `json:"file_path"`
	LineNumber        int                    `json:"line_number"`
	Variables         map[string]interface{} `json:"variables"`
	SecurityFlags     []SecurityFlag         `json:"security_flags,omitempty"`
	StackTrace        string                 `json:"stack_trace"`
	TraceID           string                 `json:"trace_id,omitempty"`
	SpanID            string                 `json:"span_id,omitempty"`
	RequestContext    map[string]interface{} `json:"request_context,omitempty"`
	ExpressionResults map[string]interface{} `json:"expression_results,omitempty"`
	CapturedAt        time.Time              `json:"captured_at"`
}

Snapshot represents a captured code state

type SnapshotClient 

type SnapshotClient struct {
	// contains filtered or unexported fields
}

SnapshotClient handles code monitoring snapshots

func NewSnapshotClient 

func NewSnapshotClient(apiKey, baseURL, serviceName string) *SnapshotClient

NewSnapshotClient creates a new snapshot client with PII scrubbing enabled by default

func NewSnapshotClientWithConfig added in v1.4.0 

func NewSnapshotClientWithConfig(apiKey, baseURL, serviceName string, config CaptureConfig) *SnapshotClient

NewSnapshotClientWithConfig creates a new snapshot client with capture limits config

func (*SnapshotClient) CheckAndCapture 

func (c *SnapshotClient) CheckAndCapture(filePath string, lineNumber int, variables map[string]interface{})

CheckAndCapture checks if there's an active breakpoint at this location and captures a snapshot

func (*SnapshotClient) CheckAndCaptureWithContext 

func (c *SnapshotClient) CheckAndCaptureWithContext(ctx context.Context, label string, variables map[string]interface{})

CheckAndCaptureWithContext checks and captures with trace context It automatically registers the breakpoint location on first call label: optional stable identifier for the checkpoint

func (*SnapshotClient) SetCaptureConfig added in v1.4.0 

func (c *SnapshotClient) SetCaptureConfig(config CaptureConfig)

SetCaptureConfig updates the capture limit configuration

func (*SnapshotClient) Start 

func (c *SnapshotClient) Start()

Start begins polling for active breakpoints

func (*SnapshotClient) Stop 

func (c *SnapshotClient) Stop()

Stop stops the snapshot client

type TracedDB 

type TracedDB struct {
	// contains filtered or unexported fields
}

TracedDB is a wrapper around sql.DB that adds tracing

func (*TracedDB) Begin 

func (tdb *TracedDB) Begin() (*sql.Tx, error)

Begin starts a transaction with tracing (no context)

func (*TracedDB) BeginTx 

func (tdb *TracedDB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)

BeginTx starts a transaction with tracing

func (*TracedDB) Close 

func (tdb *TracedDB) Close() error

Close closes the database connection

func (*TracedDB) DB 

func (tdb *TracedDB) DB() *sql.DB

DB returns the underlying sql.DB

func (*TracedDB) Driver 

func (tdb *TracedDB) Driver() driver.Driver

Driver returns the database driver

func (*TracedDB) Exec 

func (tdb *TracedDB) Exec(query string, args ...interface{}) (sql.Result, error)

Exec executes a query without returning rows, with tracing (no context)

func (*TracedDB) ExecContext 

func (tdb *TracedDB) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

ExecContext executes a query without returning rows, with tracing

func (*TracedDB) Ping 

func (tdb *TracedDB) Ping() error

Ping verifies connection with tracing (no context)

func (*TracedDB) PingContext 

func (tdb *TracedDB) PingContext(ctx context.Context) error

PingContext verifies connection with tracing

func (*TracedDB) Prepare 

func (tdb *TracedDB) Prepare(query string) (*sql.Stmt, error)

Prepare creates a prepared statement with tracing (no context)

func (*TracedDB) PrepareContext 

func (tdb *TracedDB) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)

PrepareContext creates a prepared statement with tracing

func (*TracedDB) Query 

func (tdb *TracedDB) Query(query string, args ...interface{}) (*sql.Rows, error)

Query executes a query with tracing (no context)

func (*TracedDB) QueryContext 

func (tdb *TracedDB) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

QueryContext executes a query with tracing

func (*TracedDB) QueryRow 

func (tdb *TracedDB) QueryRow(query string, args ...interface{}) *sql.Row

QueryRow executes a query that returns a single row with tracing (no context)

func (*TracedDB) QueryRowContext 

func (tdb *TracedDB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

QueryRowContext executes a query that returns a single row with tracing

func (*TracedDB) SetMaxIdleConns 

func (tdb *TracedDB) SetMaxIdleConns(n int)

SetMaxIdleConns sets the maximum number of idle connections

func (*TracedDB) SetMaxOpenConns 

func (tdb *TracedDB) SetMaxOpenConns(n int)

SetMaxOpenConns sets the maximum number of open connections

func (*TracedDB) Stats 

func (tdb *TracedDB) Stats() sql.DBStats

Stats returns database statistics

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.