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 ¶
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.
const ( OutcomeReleased = "released" OutcomeCancelled = "cancelled" OutcomeHeld = "held" )
Acquisition outcomes.
Variables ¶
This section is empty.
Functions ¶
func IsReportedKind ¶
IsReportedKind reports whether kind is one of the contract's own op kinds.
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 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 ¶
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.
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).