operationevent

package
v0.2.3 Latest Latest
Warning

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

 Go to latest Published: Sep 17, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrRecoveredPanic = errors.New("recovered panic")

ErrRecoveredPanic identifies an internal panic converted into an error at a child-goroutine boundary.

Functions

func IsConnectionAbortPanic 

func IsConnectionAbortPanic(recovered any) bool

IsConnectionAbortPanic reports whether recovered is an expected transport disconnect that should remain stack-suppressed.

func LogRecoveredPanic 

func LogRecoveredPanic(event *Event, operation string, recovered any, stack []byte)

LogRecoveredPanic emits a stack-bearing diagnostic point log correlated with an operation. Stacks and panic values intentionally remain outside the canonical event snapshot.

func RecoveredPanicError 

func RecoveredPanicError(event *Event, operation string, recovered any, stack []byte) error

RecoveredPanicError logs a recovered panic at its recovery site and returns a privacy-safe error that can be propagated to the operation boundary. Expected connection aborts remain stack-suppressed and become cancellation.

func WithContext 

func WithContext(ctx context.Context, event *Event) context.Context

WithContext attaches an event to a context.

func WithErrorDetails 

func WithErrorDetails(err error, details ErrorDetails) error

WithErrorDetails wraps err with privacy-safe typed operational diagnostics.

func WithEventRef added in v0.2.2 

func WithEventRef(ctx context.Context, ref *EventRef) context.Context

WithEventRef attaches a shared event reference to a context.

Types

type Emitter 

type Emitter func(message string, level Level, snapshot Snapshot)

Emitter receives an immutable event record. It is primarily useful for focused tests.

type ErrorDetailer 

type ErrorDetailer interface {
	OperationErrorDetails() ErrorDetails
}

ErrorDetailer exposes bounded, privacy-safe operational diagnostics.

type ErrorDetails 

type ErrorDetails struct {
	ErrorType string                `json:"errorType,omitempty"`
	ErrorCode string                `json:"errorCode,omitempty"`
	Reason    string                `json:"reason,omitempty"`
	Provider  *ErrorDetailsProvider `json:"provider,omitempty"`
}

ErrorDetails describes a privacy-safe typed error. Diagnostic values must not contain raw errors.

type ErrorDetailsEntry 

type ErrorDetailsEntry struct {
	ErrorType string                `json:"errorType,omitempty"`
	ErrorCode string                `json:"errorCode,omitempty"`
	Reason    string                `json:"reason,omitempty"`
	Provider  *ErrorDetailsProvider `json:"provider,omitempty"`
	Branch    string                `json:"branch,omitempty"`
	Depth     int                   `json:"depth"`
}

ErrorDetailsEntry records one typed cause and its position in an unwrap tree.

type ErrorDetailsProvider 

type ErrorDetailsProvider struct {
	Name          string `json:"name,omitempty"`
	StatusCode    int    `json:"statusCode,omitempty"`
	ErrorCode     string `json:"errorCode,omitempty"`
	TransactionID string `json:"transactionID,omitempty"`
}

ErrorDetailsProvider contains privacy-safe provider metadata.

type Event 

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

Event is a concurrency-safe canonical operation event.

func FromContext 

func FromContext(ctx context.Context) *Event

FromContext returns the event attached to ctx, if any.

func New 

func New(message string, options ...Option) *Event

New constructs an event. Call EmitTerminal exactly once at the operation boundary.

func (*Event) EmitStart 

func (e *Event) EmitStart() bool

EmitStart emits at most one start record. Use it only for substantial or streaming work.

func (*Event) EmitTerminal 

func (e *Event) EmitTerminal(result Result) bool

EmitTerminal emits at most one completion record.

func (*Event) EnrichError 

func (e *Event) EnrichError(err error)

EnrichError collects typed details from a terminal error only.

func (*Event) Message 

func (e *Event) Message() string

Message returns the stable operation name.

func (*Event) SetAgentID 

func (e *Event) SetAgentID(value string)

func (*Event) SetAttachmentID 

func (e *Event) SetAttachmentID(value string)

func (*Event) SetClientID 

func (e *Event) SetClientID(value string)

func (*Event) SetConnectionID 

func (e *Event) SetConnectionID(value string)

func (*Event) SetConversationID 

func (e *Event) SetConversationID(value string)

func (*Event) SetCursor 

func (e *Event) SetCursor(value string)

func (*Event) SetEntryID 

func (e *Event) SetEntryID(value string)

func (*Event) SetErrorCode 

func (e *Event) SetErrorCode(value string)

func (*Event) SetErrorType 

func (e *Event) SetErrorType(value string)

func (*Event) SetFailureCount 

func (e *Event) SetFailureCount(value int64)

func (*Event) SetGRPCStatus 

func (e *Event) SetGRPCStatus(status string)

func (*Event) SetHTTPStatus 

func (e *Event) SetHTTPStatus(status int)

func (*Event) SetMemoryID 

func (e *Event) SetMemoryID(value string)

func (*Event) SetProvider 

func (e *Event) SetProvider(details ErrorDetailsProvider)

func (*Event) SetRateLimiter added in v0.2.2 

func (e *Event) SetRateLimiter(value string)

func (*Event) SetReason 

func (e *Event) SetReason(value string)

func (*Event) SetRequestID 

func (e *Event) SetRequestID(value string)

func (*Event) SetRetryAttempt 

func (e *Event) SetRetryAttempt(value int)

func (*Event) SetTaskID 

func (e *Event) SetTaskID(value string)

func (*Event) SetTraceContext added in v0.2.2 

func (e *Event) SetTraceContext(traceID, spanID string)

func (*Event) SetUserID 

func (e *Event) SetUserID(value string)

func (*Event) SetWorkCount 

func (e *Event) SetWorkCount(value int64)

func (*Event) Snapshot 

func (e *Event) Snapshot() Snapshot

Snapshot returns a deep, immutable copy of the current fields.

type EventRef added in v0.2.2 

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

EventRef shares an operation event between interceptors that derive contexts.

func EventRefFromContext added in v0.2.2 

func EventRefFromContext(ctx context.Context) *EventRef

EventRefFromContext returns a shared event reference attached to ctx.

func NewEventRef added in v0.2.2 

func NewEventRef() *EventRef

NewEventRef creates an empty shared event reference.

func (*EventRef) Get added in v0.2.2 

func (r *EventRef) Get() *Event

Get returns the event currently stored in the reference.

func (*EventRef) Set added in v0.2.2 

func (r *EventRef) Set(event *Event)

Set stores the event in the reference.

type Level 

type Level string

Level is the severity used for a canonical event. 

const (
	LevelInfo  Level = "info"
	LevelWarn  Level = "warn"
	LevelError Level = "error"
)

func LevelForResult 

func LevelForResult(result Result) Level

LevelForResult returns the canonical severity for result.

type Option 

type Option func(*Event)

func WithEmitter 

func WithEmitter(emitter Emitter) Option

WithEmitter overrides the default structured logger sink.

type Result 

type Result string

Result is the transport-independent outcome of an operation. 

const (
	ResultSuccess         Result = "success"
	ResultInvalid         Result = "invalid"
	ResultUnauthenticated Result = "unauthenticated"
	ResultForbidden       Result = "forbidden"
	ResultNotFound        Result = "not_found"
	ResultConflict        Result = "conflict"
	ResultRateLimited     Result = "rate_limited"
	ResultTimedOut        Result = "timed_out"
	ResultCanceled        Result = "canceled"
	ResultRejected        Result = "rejected"
	ResultFailed          Result = "failed"
	ResultRetrying        Result = "retrying"
)

func ResultFromGRPC 

func ResultFromGRPC(code codes.Code, ctxErr error) Result

ResultFromGRPC maps a final gRPC code and context state to a semantic result.

func ResultFromHTTP 

func ResultFromHTTP(status int, ctxErr error) Result

ResultFromHTTP maps a final HTTP status and context state to a semantic result.

type Snapshot 

type Snapshot struct {
	Phase                 string              `json:"phase,omitempty"`
	RequestID             string              `json:"requestID,omitempty"`
	TraceID               string              `json:"traceID,omitempty"`
	SpanID                string              `json:"spanID,omitempty"`
	Status                any                 `json:"status,omitempty"`
	Duration              time.Duration       `json:"duration,omitempty"`
	Result                Result              `json:"result,omitempty"`
	Reason                string              `json:"reason,omitempty"`
	ErrorCode             string              `json:"errorCode,omitempty"`
	ErrorType             string              `json:"errorType,omitempty"`
	RateLimiter           string              `json:"rateLimiter,omitempty"`
	UserID                string              `json:"userID,omitempty"`
	ClientID              string              `json:"clientID,omitempty"`
	AgentID               string              `json:"agentID,omitempty"`
	ConversationID        string              `json:"conversationID,omitempty"`
	EntryID               string              `json:"entryID,omitempty"`
	AttachmentID          string              `json:"attachmentID,omitempty"`
	MemoryID              string              `json:"memoryID,omitempty"`
	TaskID                string              `json:"taskID,omitempty"`
	ConnectionID          string              `json:"connectionID,omitempty"`
	Cursor                string              `json:"cursor,omitempty"`
	ProviderName          string              `json:"providerName,omitempty"`
	ProviderStatusCode    int                 `json:"providerStatusCode,omitempty"`
	ProviderErrorCode     string              `json:"providerErrorCode,omitempty"`
	ProviderTransactionID string              `json:"providerTransactionID,omitempty"`
	RetryAttempt          int                 `json:"retryAttempt,omitempty"`
	WorkCount             int64               `json:"workCount,omitempty"`
	FailureCount          int64               `json:"failureCount,omitempty"`
	ErrorDetails          []ErrorDetailsEntry `json:"errorDetails,omitempty"`
	ErrorDetailsTruncated bool                `json:"errorDetailsTruncated,omitempty"`
}

Snapshot is an immutable copy of an event's sparse canonical fields.

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.