Documentation
¶
Overview ¶
Package tracing provides business-specific distributed tracing utilities
Index ¶
- Constants
- func AddAuthenticationAttrs(tc *TracedContext, username string, authType string, success bool)
- func AddBusinessMetricAttrs(tc *TracedContext, metricName string, value interface{}, unit string)
- func AddCacheOperationAttrs(tc *TracedContext, operation string, key string, hit bool)
- func AddChannelOperationAttrs(tc *TracedContext, channelName string, operation string)
- func AddDatabaseOperationAttrs(tc *TracedContext, operation string, table string, affected int64)
- func AddEmailAttrs(tc *TracedContext, email string)
- func AddHTTPRequestAttrs(tc *TracedContext, c echo.Context)
- func AddMailOperationAttrs(tc *TracedContext, recipient string, subject string, template string)
- func AddRateLimitAttrs(tc *TracedContext, identifier string, limit int64, remaining int64, ...)
- func AddSecurityEventAttrs(tc *TracedContext, eventType string, severity string, ...)
- func AddTokenAttrs(tc *TracedContext, token string, tokenType string)
- func AddUserActivityAttrs(tc *TracedContext, userID int64, username string, activity string)
- func AddUsernameAttrs(tc *TracedContext, username string)
- func AddValidationResultAttrs(tc *TracedContext, field string, valid bool, reason string)
- func AuthenticationAttrs(username string, authType string, success bool) map[string]interface{}
- func BusinessMetricAttrs(metricName string, value interface{}, unit string) map[string]interface{}
- func CacheOperationAttrs(operation string, key string, hit bool) map[string]interface{}
- func ChannelOperationAttrs(channelName string, operation string) map[string]interface{}
- func DatabaseOperationAttrs(operation string, table string, affected int64) map[string]interface{}
- func EmailAttributes(email string) map[string]interface{}
- func ExecuteWithResult[T any](op *Operation, resultStage string, resultFn func(*TracedContext) (T, error)) (T, error)
- func HTTPRequestAttributes(c echo.Context) map[string]interface{}
- func InitGlobalBusinessTracer(config BusinessTracerConfig)
- func MailOperationAttrs(recipient string, subject string, template string) map[string]interface{}
- func RateLimitAttrs(identifier string, limit int64, remaining int64, resetTime int64) map[string]interface{}
- func RecordDetailedError(ctx context.Context, errorInfo ErrorInfo)
- func RecordError(ctx context.Context, err error)
- func RecordErrorWithCategory(ctx context.Context, err error, operation string, userID *int64)
- func SecurityEventAttrs(eventType string, severity string, details map[string]interface{}) map[string]interface{}
- func SimpleOperation(ctx context.Context, name string, fn StageFunc) error
- func ThreeStageOperation(ctx context.Context, name, stage1Name, stage2Name, stage3Name string, ...) error
- func TokenAttributes(token string, tokenType string) map[string]interface{}
- func TraceAuthentication(ctx context.Context, username string, authType string, ...) error
- func TraceBusinessTransaction(ctx context.Context, transactionName string, f func(context.Context) error) error
- func TraceChannelOperation(ctx context.Context, channelID int32, userID int32, operation string, ...) error
- func TraceChannelSearch(ctx context.Context, userID int32, query string, ...) (int, error)
- func TraceOperation(ctx context.Context, operationName string, f func(context.Context) error) error
- func TraceUserActivation(ctx context.Context, username, token string, f func(context.Context) error) error
- func TraceUserRegistration(ctx context.Context, username, email string, stage string, ...) error
- func TwoStageOperation(ctx context.Context, name, stage1Name, stage2Name string, ...) error
- func UserActivityAttrs(userID int64, username string, activity string) map[string]interface{}
- func UsernameAttributes(username string) map[string]interface{}
- func ValidationResultAttrs(field string, valid bool, reason string) map[string]interface{}
- type BusinessTracer
- func (bt *BusinessTracer) AddAttributes(ctx context.Context, attrs ...attribute.KeyValue)
- func (bt *BusinessTracer) RecordDetailedError(ctx context.Context, errorInfo ErrorInfo)
- func (bt *BusinessTracer) RecordError(ctx context.Context, err error)
- func (bt *BusinessTracer) RecordErrorWithCategory(ctx context.Context, err error, operation string, userID *int64)
- func (bt *BusinessTracer) SetStatus(ctx context.Context, code codes.Code, description string)
- func (bt *BusinessTracer) StartSpan(ctx context.Context, operationName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- func (bt *BusinessTracer) TraceAuthentication(ctx context.Context, username string, authType string, ...) error
- func (bt *BusinessTracer) TraceBusinessTransaction(ctx context.Context, transactionName string, f func(context.Context) error) error
- func (bt *BusinessTracer) TraceChannelOperation(ctx context.Context, channelID int32, userID int32, operation string, ...) error
- func (bt *BusinessTracer) TraceChannelSearch(ctx context.Context, userID int32, query string, ...) (int, error)
- func (bt *BusinessTracer) TraceOperation(ctx context.Context, operationName string, f func(context.Context) error) error
- func (bt *BusinessTracer) TraceUserActivation(ctx context.Context, username, token string, f func(context.Context) error) error
- func (bt *BusinessTracer) TraceUserRegistration(ctx context.Context, username, email string, stage string, ...) error
- type BusinessTracerConfig
- type ErrorInfo
- type Operation
- func (op *Operation) AddOptionalStage(name string, fn StageFunc) *Operation
- func (op *Operation) AddStage(name string, fn StageFunc) *Operation
- func (op *Operation) Execute() error
- func (op *Operation) WithAttribute(key string, value interface{}) *Operation
- func (op *Operation) WithAttributes(attrs map[string]interface{}) *Operation
- func (op *Operation) WithContext(ctx context.Context) *Operation
- type Stage
- type StageFunc
- type TracedContext
- func (tc *TracedContext) AddAttr(key string, value interface{})
- func (tc *TracedContext) AddAttrs(attrs map[string]interface{})
- func (tc *TracedContext) AddBoolAttr(key string, value bool)
- func (tc *TracedContext) AddEvent(name string, attrs ...attribute.KeyValue)
- func (tc *TracedContext) AddInt64Attr(key string, value int64)
- func (tc *TracedContext) AddIntAttr(key string, value int)
- func (tc *TracedContext) AddStringAttr(key, value string)
- func (tc *TracedContext) AddStructuredEvent(eventName string, attrs map[string]interface{})
- func (tc *TracedContext) MarkFailure(reason string)
- func (tc *TracedContext) MarkSuccess()
- func (tc *TracedContext) RecordDetailedError(err error, context map[string]interface{})
- func (tc *TracedContext) RecordError(err error)
- func (tc *TracedContext) Span() trace.Span
Constants ¶
const ( ErrorCategoryValidation = "validation" ErrorCategoryDatabase = "database" ErrorCategoryAuthentication = "authentication" ErrorCategoryAuthorization = "authorization" ErrorCategoryExternal = "external_service" ErrorCategoryInternal = "internal" ErrorCategoryNetwork = "network" ErrorCategoryTimeout = "timeout" ErrorCategoryRateLimit = "rate_limit" ErrorCategoryBusiness = "business_logic" )
ErrorCategory constants for categorizing errors
const ( ErrorSeverityLow = "low" ErrorSeverityMedium = "medium" ErrorSeverityHigh = "high" ErrorSeverityCritical = "critical" )
ErrorSeverity constants for error severity levels
Variables ¶
This section is empty.
Functions ¶
func AddAuthenticationAttrs ¶ added in v0.5.3
func AddAuthenticationAttrs(tc *TracedContext, username string, authType string, success bool)
AddAuthenticationAttrs adds authentication attributes to a traced context
func AddBusinessMetricAttrs ¶ added in v0.5.3
func AddBusinessMetricAttrs(tc *TracedContext, metricName string, value interface{}, unit string)
AddBusinessMetricAttrs adds business metric attributes to a traced context
func AddCacheOperationAttrs ¶ added in v0.5.3
func AddCacheOperationAttrs(tc *TracedContext, operation string, key string, hit bool)
AddCacheOperationAttrs adds cache operation attributes to a traced context
func AddChannelOperationAttrs ¶ added in v0.5.3
func AddChannelOperationAttrs(tc *TracedContext, channelName string, operation string)
AddChannelOperationAttrs adds channel operation attributes to a traced context
func AddDatabaseOperationAttrs ¶ added in v0.5.3
func AddDatabaseOperationAttrs(tc *TracedContext, operation string, table string, affected int64)
AddDatabaseOperationAttrs adds database operation attributes to a traced context
func AddEmailAttrs ¶ added in v0.5.3
func AddEmailAttrs(tc *TracedContext, email string)
AddEmailAttrs adds email-related attributes to a traced context
func AddHTTPRequestAttrs ¶ added in v0.5.3
func AddHTTPRequestAttrs(tc *TracedContext, c echo.Context)
AddHTTPRequestAttrs adds HTTP request attributes to a traced context
func AddMailOperationAttrs ¶ added in v0.5.3
func AddMailOperationAttrs(tc *TracedContext, recipient string, subject string, template string)
AddMailOperationAttrs adds email operation attributes to a traced context
func AddRateLimitAttrs ¶ added in v0.5.3
func AddRateLimitAttrs(tc *TracedContext, identifier string, limit int64, remaining int64, resetTime int64)
AddRateLimitAttrs adds rate limiting attributes to a traced context
func AddSecurityEventAttrs ¶ added in v0.5.3
func AddSecurityEventAttrs(tc *TracedContext, eventType string, severity string, details map[string]interface{})
AddSecurityEventAttrs adds security event attributes to a traced context
func AddTokenAttrs ¶ added in v0.5.3
func AddTokenAttrs(tc *TracedContext, token string, tokenType string)
AddTokenAttrs adds token-related attributes to a traced context
func AddUserActivityAttrs ¶ added in v0.5.3
func AddUserActivityAttrs(tc *TracedContext, userID int64, username string, activity string)
AddUserActivityAttrs adds user activity attributes to a traced context
func AddUsernameAttrs ¶ added in v0.5.3
func AddUsernameAttrs(tc *TracedContext, username string)
AddUsernameAttrs adds username-related attributes to a traced context
func AddValidationResultAttrs ¶ added in v0.5.3
func AddValidationResultAttrs(tc *TracedContext, field string, valid bool, reason string)
AddValidationResultAttrs adds validation result attributes to a traced context
func AuthenticationAttrs ¶ added in v0.5.3
AuthenticationAttrs creates attributes for authentication operations
func BusinessMetricAttrs ¶ added in v0.5.3
BusinessMetricAttrs creates attributes for business metrics
func CacheOperationAttrs ¶ added in v0.5.3
CacheOperationAttrs creates attributes for cache operations
func ChannelOperationAttrs ¶ added in v0.5.3
ChannelOperationAttrs creates attributes for channel-related operations
func DatabaseOperationAttrs ¶ added in v0.5.3
DatabaseOperationAttrs creates attributes for database operations
func EmailAttributes ¶ added in v0.5.3
EmailAttributes extracts email-related attributes for tracing Safely extracts email domain and validates format
func ExecuteWithResult ¶ added in v0.5.3
func ExecuteWithResult[T any](op *Operation, resultStage string, resultFn func(*TracedContext) (T, error)) (T, error)
ExecuteWithResult runs all stages and returns a result This is useful for operations that need to return a value
func HTTPRequestAttributes ¶ added in v0.5.3
func HTTPRequestAttributes(c echo.Context) map[string]interface{}
HTTPRequestAttributes extracts common HTTP request attributes from Echo context
func InitGlobalBusinessTracer ¶
func InitGlobalBusinessTracer(config BusinessTracerConfig)
InitGlobalBusinessTracer initializes the global business tracer
func MailOperationAttrs ¶ added in v0.5.3
MailOperationAttrs creates attributes for email operations
func RateLimitAttrs ¶ added in v0.5.3
func RateLimitAttrs(identifier string, limit int64, remaining int64, resetTime int64) map[string]interface{}
RateLimitAttrs creates attributes for rate limiting events
func RecordDetailedError ¶
RecordDetailedError records an error with detailed information using the global tracer
func RecordError ¶
RecordError records an error in the current span using the global tracer
func RecordErrorWithCategory ¶
RecordErrorWithCategory records an error with automatic categorization using the global tracer
func SecurityEventAttrs ¶ added in v0.5.3
func SecurityEventAttrs(eventType string, severity string, details map[string]interface{}) map[string]interface{}
SecurityEventAttrs creates attributes for security-related events
func SimpleOperation ¶ added in v0.5.3
SimpleOperation creates and executes a single-stage operation
func ThreeStageOperation ¶ added in v0.5.3
func ThreeStageOperation(ctx context.Context, name, stage1Name, stage2Name, stage3Name string, stage1, stage2, stage3 StageFunc) error
ThreeStageOperation creates an operation with three stages
func TokenAttributes ¶ added in v0.5.3
TokenAttributes extracts token-related attributes for tracing Safely extracts token metadata without logging the token itself
func TraceAuthentication ¶
func TraceAuthentication(ctx context.Context, username string, authType string, f func(context.Context) error) error
TraceAuthentication traces authentication operations using the global tracer
func TraceBusinessTransaction ¶
func TraceBusinessTransaction(ctx context.Context, transactionName string, f func(context.Context) error) error
TraceBusinessTransaction traces multi-step business transactions using the global tracer
func TraceChannelOperation ¶
func TraceChannelOperation(ctx context.Context, channelID int32, userID int32, operation string, f func(context.Context) error) error
TraceChannelOperation traces channel-related operations using the global tracer
func TraceChannelSearch ¶
func TraceChannelSearch(ctx context.Context, userID int32, query string, f func(context.Context) (int, error)) (int, error)
TraceChannelSearch traces channel search operations using the global tracer
func TraceOperation ¶
TraceOperation wraps a business operation with tracing using the global tracer
func TraceUserActivation ¶
func TraceUserActivation(ctx context.Context, username, token string, f func(context.Context) error) error
TraceUserActivation traces user activation operations using the global tracer
func TraceUserRegistration ¶
func TraceUserRegistration(ctx context.Context, username, email string, stage string, f func(context.Context) error) error
TraceUserRegistration traces user registration operations using the global tracer
func TwoStageOperation ¶ added in v0.5.3
func TwoStageOperation(ctx context.Context, name, stage1Name, stage2Name string, stage1, stage2 StageFunc) error
TwoStageOperation creates an operation with two stages
func UserActivityAttrs ¶ added in v0.5.3
UserActivityAttrs creates attributes for user activity tracking
func UsernameAttributes ¶ added in v0.5.3
UsernameAttributes extracts username-related attributes for tracing
Types ¶
type BusinessTracer ¶
type BusinessTracer struct {
// contains filtered or unexported fields
}
BusinessTracer provides tracing utilities for business logic operations
func GetGlobalBusinessTracer ¶
func GetGlobalBusinessTracer() *BusinessTracer
GetGlobalBusinessTracer returns the global business tracer
func NewBusinessTracer ¶
func NewBusinessTracer(config BusinessTracerConfig) *BusinessTracer
NewBusinessTracer creates a new business tracer
func (*BusinessTracer) AddAttributes ¶
func (bt *BusinessTracer) AddAttributes(ctx context.Context, attrs ...attribute.KeyValue)
AddAttributes adds attributes to the current span
func (*BusinessTracer) RecordDetailedError ¶
func (bt *BusinessTracer) RecordDetailedError(ctx context.Context, errorInfo ErrorInfo)
RecordDetailedError records an error with detailed information in the current span
func (*BusinessTracer) RecordError ¶
func (bt *BusinessTracer) RecordError(ctx context.Context, err error)
RecordError records an error in the current span
func (*BusinessTracer) RecordErrorWithCategory ¶
func (bt *BusinessTracer) RecordErrorWithCategory(ctx context.Context, err error, operation string, userID *int64)
RecordErrorWithCategory records an error with automatic categorization
func (*BusinessTracer) StartSpan ¶
func (bt *BusinessTracer) StartSpan(ctx context.Context, operationName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
StartSpan creates a new child span for business operations
func (*BusinessTracer) TraceAuthentication ¶
func (bt *BusinessTracer) TraceAuthentication(ctx context.Context, username string, authType string, f func(context.Context) error) error
TraceAuthentication traces authentication operations
func (*BusinessTracer) TraceBusinessTransaction ¶
func (bt *BusinessTracer) TraceBusinessTransaction(ctx context.Context, transactionName string, f func(context.Context) error) error
TraceBusinessTransaction traces multi-step business transactions
func (*BusinessTracer) TraceChannelOperation ¶
func (bt *BusinessTracer) TraceChannelOperation(ctx context.Context, channelID int32, userID int32, operation string, f func(context.Context) error) error
TraceChannelOperation traces channel-related operations
func (*BusinessTracer) TraceChannelSearch ¶
func (bt *BusinessTracer) TraceChannelSearch(ctx context.Context, userID int32, query string, f func(context.Context) (int, error)) (int, error)
TraceChannelSearch traces channel search operations
func (*BusinessTracer) TraceOperation ¶
func (bt *BusinessTracer) TraceOperation(ctx context.Context, operationName string, f func(context.Context) error) error
TraceOperation wraps a business operation with tracing
func (*BusinessTracer) TraceUserActivation ¶
func (bt *BusinessTracer) TraceUserActivation(ctx context.Context, username, token string, f func(context.Context) error) error
TraceUserActivation traces user activation operations
type BusinessTracerConfig ¶
type BusinessTracerConfig struct {
TracerProvider trace.TracerProvider
ServiceName string
}
BusinessTracerConfig holds configuration for business tracing
type ErrorInfo ¶
type ErrorInfo struct {
Error error
Category string
Severity string
UserID *int64
Operation string
StackTrace []string
Context map[string]interface{}
}
ErrorInfo contains detailed information about an error for tracing
type Operation ¶ added in v0.5.3
type Operation struct {
// contains filtered or unexported fields
}
Operation represents a traced business operation that can be composed of multiple stages
func NewOperation ¶ added in v0.5.3
NewOperation creates a new traced operation
func (*Operation) AddOptionalStage ¶ added in v0.5.3
AddOptionalStage adds an optional stage to the operation Optional stages that fail will log the error but won't fail the operation
func (*Operation) Execute ¶ added in v0.5.3
Execute runs all stages of the operation within a traced context
func (*Operation) WithAttribute ¶ added in v0.5.3
WithAttribute adds a single attribute to the root span
func (*Operation) WithAttributes ¶ added in v0.5.3
WithAttributes adds attributes that will be applied to the root span
type Stage ¶ added in v0.5.3
type Stage struct {
// contains filtered or unexported fields
}
Stage represents a single stage within an operation
type StageFunc ¶ added in v0.5.3
type StageFunc func(*TracedContext) error
StageFunc is the function signature for operation stages
type TracedContext ¶ added in v0.5.3
TracedContext wraps a context and span to provide convenient tracing methods This eliminates the need for repeated trace.SpanFromContext() calls
func NewTracedContext ¶ added in v0.5.3
func NewTracedContext(ctx context.Context) *TracedContext
NewTracedContext creates a new TracedContext from a context If the context doesn't have a span, it uses a no-op span
func WithSpan ¶ added in v0.5.3
func WithSpan(ctx context.Context, span trace.Span) *TracedContext
WithSpan creates a new TracedContext with the given span
func (*TracedContext) AddAttr ¶ added in v0.5.3
func (tc *TracedContext) AddAttr(key string, value interface{})
AddAttr adds a single attribute to the span Automatically handles type conversion for common Go types
func (*TracedContext) AddAttrs ¶ added in v0.5.3
func (tc *TracedContext) AddAttrs(attrs map[string]interface{})
AddAttrs adds multiple attributes to the span at once
func (*TracedContext) AddBoolAttr ¶ added in v0.5.3
func (tc *TracedContext) AddBoolAttr(key string, value bool)
AddBoolAttr adds a bool attribute (convenience method)
func (*TracedContext) AddEvent ¶ added in v0.5.3
func (tc *TracedContext) AddEvent(name string, attrs ...attribute.KeyValue)
AddEvent adds an event to the span
func (*TracedContext) AddInt64Attr ¶ added in v0.5.3
func (tc *TracedContext) AddInt64Attr(key string, value int64)
AddInt64Attr adds an int64 attribute (convenience method)
func (*TracedContext) AddIntAttr ¶ added in v0.5.3
func (tc *TracedContext) AddIntAttr(key string, value int)
AddIntAttr adds an int attribute (convenience method)
func (*TracedContext) AddStringAttr ¶ added in v0.5.3
func (tc *TracedContext) AddStringAttr(key, value string)
AddStringAttr adds a string attribute (convenience method)
func (*TracedContext) AddStructuredEvent ¶ added in v0.5.3
func (tc *TracedContext) AddStructuredEvent(eventName string, attrs map[string]interface{})
Helper to create span events with structured attributes
func (*TracedContext) MarkFailure ¶ added in v0.5.3
func (tc *TracedContext) MarkFailure(reason string)
MarkFailure marks the current operation as failed
func (*TracedContext) MarkSuccess ¶ added in v0.5.3
func (tc *TracedContext) MarkSuccess()
MarkSuccess marks the current operation as successful
func (*TracedContext) RecordDetailedError ¶ added in v0.5.3
func (tc *TracedContext) RecordDetailedError(err error, context map[string]interface{})
RecordDetailedError records an error with additional context
func (*TracedContext) RecordError ¶ added in v0.5.3
func (tc *TracedContext) RecordError(err error)
RecordError records an error in the span with automatic categorization
func (*TracedContext) Span ¶ added in v0.5.3
func (tc *TracedContext) Span() trace.Span
Span returns the underlying span
Source Files