Documentation
¶
Overview ¶
Package observability records bounded, payload-free backend diagnostics. Recording never calls application code or starts workers. Applications own synchronous export through Drain; a blocked exporter blocks only its caller. Attempts, stream consumption, acknowledged data and actual cleanup joins are separate phases. Delivered updates cumulative metrics only, not the event ring.
Index ¶
Examples ¶
Constants ¶
const Other = "_other"
Other is the label for unknown and over-capacity artifacts.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DrainReport ¶
type DrainReport struct {
// Removed is the number of dequeued events.
Removed int
// Errors is the number of callbacks returning an error.
Errors int
// Panics is the number of recovered callback panics.
Panics int
}
DrainReport describes one batch, removed before callbacks run and never retried.
type Metric ¶
type Metric struct {
// Observation contains labels and the cumulative seconds for this series.
Observation
// Count is the cumulative number of observations.
Count uint64
}
Metric is a cumulative count and duration sum independent of event retention.
type Observation ¶
type Observation struct {
// Artifact is a registered label, or _other.
Artifact string
// Operation is the backend operation.
Operation Operation
// Transport is the query delivery classification.
Transport Transport
// Phase identifies the completed lifecycle boundary.
Phase Phase
// Outcome is the final result classification.
Outcome Outcome
// Seconds is monotonic elapsed time in seconds.
Seconds float64
}
Observation contains copied scalars only; it cannot carry a payload or error.
type Options ¶
type Options struct {
// ArtifactLimit defaults to 1000, the maximum; _other does not use a slot.
ArtifactLimit int
// EventCapacity defaults to 256. Its maximum is 65536.
EventCapacity int
}
Options bounds recorder-wide memory, even when pipelines share a recorder.
type Outcome ¶
type Outcome uint8
Outcome is a fixed, payload-free final classification.
const ( // Success means the measured phase completed normally, not proof of commit. Success Outcome = iota // Validation means retained input or business validation findings. Validation // Authorization means access was denied, taking precedence over other failures. Authorization // AppendRejected means a constraint or concurrency validation reason. AppendRejected // Cancelled means a failed operation whose execution context was cancelled. Cancelled // Error means another failure. No error value or message is retained. Error )
type Phase ¶
type Phase uint8
Phase identifies the measured lifecycle boundary.
const ( // Completed records a finalized snapshot or command invocation. Completed Phase = iota // Opening records observable admission and source activation. Opening // Consumption records a single consumer's terminal outcome before Close cancels. Consumption // FirstDelivery records the first successfully acknowledged data result. FirstDelivery // Delivered counts every acknowledged data result, without queuing events. Delivered // Joined records lifetime through actual release of source and resource ownership. Joined // Cleanup records elapsed time from the first Close until actual ownership release. Cleanup )
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder is concurrent-safe and must not be copied. Use NewRecorder; the zero value and a nil pointer are disabled. No producer waits for exporter callbacks.
Example ¶
package main
import (
"context"
"fmt"
"github.com/cratis/arc.go/commands"
"github.com/cratis/arc.go/observability"
)
type announce struct{ Message string }
func main() {
recorder, err := observability.NewRecorder(observability.Options{})
if err != nil {
panic(err)
}
var registry commands.Registry
if err := commands.Register(®istry, commands.Void(func(announce, context.Context) error { return nil })); err != nil {
panic(err)
}
pipeline, err := registry.Build(commands.PipelineOptions{Diagnostics: recorder})
if err != nil {
panic(err)
}
result, err := pipeline.Execute(context.Background(), announce{Message: "not in diagnostics"})
if err != nil {
panic(err)
}
fmt.Println(result.IsSuccess())
// Export explicitly, after execution. No callback runs inside the pipeline.
report := recorder.Drain(64, func(event observability.Observation) error {
fmt.Println(event.Outcome.String())
return nil
})
fmt.Println(report.Removed)
}
Output: true success 1
func NewRecorder ¶
NewRecorder constructs bounded state without I/O, callbacks or goroutines.
func (*Recorder) Drain ¶
func (r *Recorder) Drain(limit int, observe func(Observation) error) DrainReport
Drain removes at most limit events, unlocks, then synchronously invokes observe. Nonpositive limits or nil callbacks remove nothing. Errors and panics are counted without retaining their values; successful and failed exports are never retried. Callbacks may reenter the recorder. Concurrent drains own disjoint batches but may invoke callbacks concurrently/out of order. A blocked callback blocks Drain; no timeout goroutine is created. Applications must own cancellation/export I/O.
func (*Recorder) Label ¶
Label returns a registered identity or _other without retaining unknown input.
func (*Recorder) Record ¶
func (r *Recorder) Record(event Observation)
Record updates cumulative metrics and a bounded event ring. Only trusted adapters should produce observations. Unknown labels/enums are normalized; nonfinite or negative durations become zero. Full rings drop new events.
func (*Recorder) Register ¶
Register admits frozen artifact identities, sorted within this batch. Earlier batches win recorder-wide capacity. Call only with trusted registration names, never request input. Empty, reserved and over-512-byte names use _other. Rejected identities are not retained. It activates no application services.
type Snapshot ¶
type Snapshot struct {
// Metrics are cumulative series in stable label order.
Metrics []Metric
// Events are queued observations in recording order.
Events []Observation
// Dropped counts events discarded because the ring was full.
Dropped uint64
// ExportErrors counts failed synchronous exporter calls.
ExportErrors uint64
// ExportPanics counts recovered exporter panics, without retaining values.
ExportPanics uint64
}
Snapshot is detached recorder state. Mutations never affect the recorder.
Source Files