contract

package
v1.0.0-beta.23 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package contract decodes the wcprof reporting contract: how a client or a program inside an exec reports its own work (tasks and task groups), what each task waited for (dependency waits), its limited resources and the acquisitions of them, and its completeness, as OTel spans and links with the wcprof.* attributes of engine/telemetryattrs.

It is the one decoder of that contract: the recorder uses it for spans it records natively, and the offline analyzers for traces they load, so they can't read the contract differently. It works on Span, a source-neutral view of a span, so any span representation can be converted to it.

Index

Constants

View Source
const (
	// PolicyPriorityFIFO admits the highest priority first, the earliest
	// request first among equals.
	PolicyPriorityFIFO = "priority_fifo"
	// PolicyFIFO admits the earliest request first.
	PolicyFIFO = "fifo"
)

Resource admission policies.

View Source
const (
	OutcomeReleased  = "released"
	OutcomeCancelled = "cancelled"
	OutcomeHeld      = "held"
)

Acquisition outcomes.

Variables

This section is empty.

Functions

func IsReportedKind

func IsReportedKind(kind string) bool

IsReportedKind reports whether kind is one of the contract's own op kinds.

func Record

func Record(s Span, name string, r Reported) (op wcprof.ReportedOp, ok bool)

Record converts what s reports into the recorder's form (see wcprof.RecordReported); ok is false when s reports no op. name is the span's name, the op's class.

Types

type Acquisition

type Acquisition struct {
	ResourceID     string
	Priority       int64
	PriorityInputs map[string]string
	// GrantedUnixNS is when the unit was granted; 0 when it never was.
	GrantedUnixNS int64
	Outcome       string
}

Acquisition is one unit of a resource requested at the span's start and released (or given up, or still held) at its end.

type Link struct {
	TraceID string
	SpanID  string
	Attrs   map[string]any
}

Link is a span link: its target and attributes.

type Op

type Op struct {
	Kind     string
	WorkType string
	Label    string
	Producer string
	// CausalParent is the span ID of the op's cause: wcprof.parent when set,
	// else the span's parent.
	CausalParent string
	StartUnixNS  int64
	EndUnixNS    int64
}

Op is a reported op.

type ProducerComplete

type ProducerComplete struct {
	Producer  string
	SpanCount int64
	Dropped   int64
}

ProducerComplete is a producer's declaration of how many spans it reported.

type Reported

type Reported struct {
	// Op is the reported op; nil for a span that isn't one (an engine span,
	// or a producer's completeness carrier).
	Op *Op
	// Waits are the span's wait links.
	Waits []Wait
	// Resource is set when Op.Kind is "resource".
	Resource *Resource
	// Acquisition is set when Op.Kind is "acquire".
	Acquisition *Acquisition
	// Complete is set on a producer's completeness carrier.
	Complete *ProducerComplete
}

Reported is what one span reports under the contract. At most one of Op's kinds applies; Resource and Acquisition are set for those kinds.

func Decode

func Decode(s Span) (Reported, error)

Decode reads what s reports under the contract. A span that reports nothing (an engine span, an unrelated span) decodes to the zero Reported. Malformed contract values are errors, never guesses.

type Resource

type Resource struct {
	Name     string
	Capacity int64
	Policy   string
}

Resource is a limited resource instance; its ID is its span's span ID.

type Span

type Span struct {
	TraceID      string
	SpanID       string
	ParentSpanID string
	StartUnixNS  int64
	EndUnixNS    int64
	Attrs        map[string]any
	Links        []Link
}

Span is what the contract reads from a span. IDs are lower-hex; times are Unix nanoseconds. Attribute values are as the source decoded them: strings, or bools and numbers for sources that keep them (decimal-string values are accepted as numbers either way).

type Wait

type Wait struct {
	TargetTraceID string
	TargetSpanID  string
	Reason        string
	Ident         string
	StartUnixNS   int64
	EndUnixNS     int64
}

Wait is a wait link: the waiter (the span carrying it) was blocked on the target span, or on the named resource Ident, from StartUnixNS to EndUnixNS.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL