tracekit

package
v1.3.2 Latest Latest
Warning

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

 Go to latest Published: Feb 2, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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

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"`
}

BreakpointConfig represents a breakpoint configuration

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
}

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 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) 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"`
	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

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) 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.