operationevent

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 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.

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