Documentation
¶
Overview ¶
Package observability defines the versioned, redacted operational event contract shared by the CLI, API client, transfer code, and MCP server.
Index ¶
- Constants
- func ClassifyError(err error) string
- func Emit(ctx context.Context, emitter Emitter, event Event)
- func EndpointClass(rawURL string) string
- func NewID(prefix string) string
- func OperationID(ctx context.Context) string
- func RequestID(ctx context.Context) string
- func WithEmitter(ctx context.Context, emitter Emitter) context.Context
- func WithOperationID(ctx context.Context, id string) context.Context
- func WithRequestID(ctx context.Context, id string) context.Context
- type Emitter
- type Error
- type Event
- type FileEmitter
- type JSONEmitter
- type NopEmitter
Constants ¶
const ( SchemaVersion = "osf.event.v1" LevelDebug = "debug" LevelInfo = "info" LevelWarn = "warn" LevelError = "error" OutcomeOK = "ok" OutcomeError = "error" OutcomeCancel = "canceled" )
Variables ¶
This section is empty.
Functions ¶
func ClassifyError ¶
ClassifyError maps errors to stable operational classes.
func EndpointClass ¶
EndpointClass returns a low-cardinality class without retaining a URL.
func OperationID ¶
OperationID returns the operation ID associated with a context.
func WithEmitter ¶
WithEmitter associates an event sink with a context.
func WithOperationID ¶
WithOperationID associates an operation ID with a context.
Types ¶
type Emitter ¶
type Emitter interface {
Emit(Event)
}
Emitter receives operational events. Implementations must be safe for concurrent use because API requests and MCP calls may overlap.
func EmitterFromContext ¶
EmitterFromContext returns the event sink associated with a context.
func OpenFromEnv ¶
OpenFromEnv enables events only when OSF_EVENT_LOG is set. The value may be a file path or "stderr". OSF_EVENT_LEVEL defaults to info. No stdout route is supported because structured events must never pollute command output.
type Error ¶
Error is a redacted, stable error classification.
func RedactedError ¶
RedactedError creates a stable error object without exposing credentials.
type Event ¶
type Event struct {
SchemaVersion string `json:"schemaVersion"`
Timestamp string `json:"timestamp"`
Level string `json:"level"`
Name string `json:"name"`
Provider string `json:"provider,omitempty"`
OperationID string `json:"operationId"`
RequestID string `json:"requestId"`
DurationMS int64 `json:"durationMs"`
RetryCount int `json:"retryCount"`
Outcome string `json:"outcome"`
EndpointClass string `json:"endpointClass,omitempty"`
Error *Error `json:"error,omitempty"`
Fields map[string]any `json:"fields,omitempty"`
}
Event is the stable JSON envelope emitted for an operational action.
type FileEmitter ¶
type FileEmitter struct {
*JSONEmitter
// contains filtered or unexported fields
}
FileEmitter is a JSONEmitter with an owned file destination.
func (*FileEmitter) Close ¶
func (e *FileEmitter) Close() error
Close closes the owned event log file.
type JSONEmitter ¶
type JSONEmitter struct {
// contains filtered or unexported fields
}
JSONEmitter writes one redacted JSON event per line.
func NewJSONEmitter ¶
func NewJSONEmitter(w io.Writer, minLevel string) *JSONEmitter
NewJSONEmitter creates a concurrent JSON event sink with the given minimum level.
func (*JSONEmitter) Close ¶
func (e *JSONEmitter) Close() error
Close closes the sink when it owns a file-backed writer.
type NopEmitter ¶
type NopEmitter struct{}
NopEmitter discards events and is the default when observability is disabled.
Source Files