tracesource

package
v1.0.0-beta.28 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package tracesource reads historical traces from equivalent telemetry providers -- the engine's retained telemetry store and Dagger Cloud -- behind one interface, and selects between them. Selection finishes before any records reach an importer; a chosen source never changes mid-import.

Index

Constants

View Source
const DefaultCloudLogConcurrency = 8

DefaultCloudLogConcurrency bounds CloudLogs' concurrent per-span streams.

Variables

View Source
var ErrEngineUnavailable = errors.New("engine unavailable")

ErrEngineUnavailable marks a failure to reach or provision the local engine at all (e.g. no container runtime): it was never asked for the trace, so another source may serve it.

Functions

func CanFallback

func CanFallback(ctx context.Context, err error) bool

CanFallback classifies only source-opening errors, never errors after import starts. Explicit refusals, bad data and cancellation always remain visible.

Types

type CallClosureReader

type CallClosureReader interface {
	CallClosure(ctx context.Context, traceID string, unsealed bool, digests, known []string, consume func(*collogspb.ExportLogsServiceRequest) error) error
}

CallClosureReader is the archive client's call-closure read (archive.Client.CallClosure).

type CloudLogFetcher

type CloudLogFetcher interface {
	FetchLogs(context.Context, string, cloud.LogSelection, func(context.Context, *collogspb.ExportLogsServiceRequest) error) error
}

CloudLogFetcher is Cloud's per-span log stream (cloud.OTLPClient).

type CloudLogs

type CloudLogs struct {
	Client      CloudLogFetcher
	Concurrency int
}

CloudLogs reads display text from Dagger Cloud, which serves one span (or subtree) per stream: it fans out one GET /v1/logs/{trace}?span_id=… stream per selected span, at most Concurrency at once.

Cloud has no display-text record class that keeps global and verbose records, so it asks for every record class and leaves the filtering to the caller; nor a digest selection, so a span's Digests are not read (the routed rows remain readable through the span that emitted them). Cloud's streams end once their span has ended, whether or not Follow is set. The cursor maps each span to the timestamp of the last record received for it.

func (CloudLogs) ReadLogs

type Live

type Live struct {
	Client LiveLogClient
}

Live reads a running session's display text from the connected client's own engine store. Its trace is the session's; traceID is not consulted.

type LiveLogClient

type LiveLogClient interface {
	QueryLogs(context.Context, archive.LogQuery, int64, func(int64, *collogspb.ExportLogsServiceRequest) error) (int64, error)
}

LiveLogClient is an engine client's on-demand read of its own live store (engine/client.Client).

type LogQuery

type LogQuery struct {
	// Spans each select a span, optionally with descendants, plus rows that
	// carry one of its dagger.io/dag.digest values (which the frontend
	// routes to the span that created the digest).
	Spans []archive.LogSpan
	// Follow keeps reading as records arrive, until ctx ends or the source
	// has no more to give (the session drained, the spans ended).
	Follow bool
	// Cursor resumes a read after the batch that carried it; "" reads from
	// the start. Cursors are opaque, and valid only for the same reader and
	// spans.
	Cursor string
	// Through, when set, ends a one-shot read at this cursor (one a
	// previous batch carried) instead of the source's end: catching newly
	// selected spans up to where a follow of other spans stands. Only Live
	// honors it; finite sources end where they end.
	Through string
}

LogQuery asks a LogReader for the display text of a set of spans: what a frontend that renders only some spans reads on demand.

type LogReader

type LogReader interface {
	ReadLogs(ctx context.Context, traceID string, q LogQuery, cb func(context.Context, *collogspb.ExportLogsServiceRequest, string) error) error
}

LogReader reads display text for a set of spans. A reader may deliver more than was selected (other record classes, rows of spans whose place it does not know); the caller applies the frontend's exact routing and roll-up. cb is called serially, each batch with the cursor to resume after it.

type LogSearcher

type LogSearcher interface {
	SearchLogs(ctx context.Context, traceID string, search archive.LogSearch) (archive.LogSearchResult, error)
}

LogSearcher searches a trace's display text where it is stored: the engine's telemetry store. Cloud has no search, so a Cloud trace has none.

type Open

type Open func(context.Context) (Source, func() error, error)

Open must not import telemetry. Its cleanup belongs to the caller until all incremental reads have stopped, including interactive reads after a report.

type Source

Source supports both complete imports and the incremental display protocol (priority spans, listened subtrees, a span's own or descendant logs by record class). Cloud's OTLPClient implements it directly and the engine's Store answers the same selections, so callers drive one loader against either.

func Select

func Select(ctx context.Context, local, remote Open) (Source, func() error, error)

Select prefers the engine's retained store. Only an unavailable source may fall back. When the fallback fails too, its error also says why the local source was not used.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is a trace in the engine's retained telemetry store, as a Source pinned to one fixed cut. It answers the same selections Dagger Cloud's OTLP endpoints do.

func NewStore

func NewStore(reader StoreReader, manifest archive.Manifest) *Store

func OpenStore

func OpenStore(ctx context.Context, client *archive.Client, traceID string) (*Store, error)

OpenStore inspects metadata to pin the trace's cut. No bootstrap, recipe, agent, or telemetry record is evaluated or imported. An archive whose session ended without a seal is opened best-effort at the current end of its store, as restore does.

func (*Store) ConversationOnly

func (a *Store) ConversationOnly() *Store

ConversationOnly narrows the priority view, for a trace too large to load broadly: its priority spans are only the agents' conversations (loop and message spans, and each tool call's execution span, which holds its result), not checks, tests or failures, which load as their ancestors are expanded. An engine that predates the selection ignores it and serves the broader view.

func (*Store) FetchBootstrap

func (a *Store) FetchBootstrap(ctx context.Context, sink cloud.TraceImportSink) error

FetchBootstrap imports the verified canonical agent roster and its recipe closure for agent inspection: a sealed archive's history omits the agent control records its bootstrap carries. This is display-only: no recipe is evaluated. Call only after source selection; a verification or import failure must not fall back.

func (*Store) FetchCallClosure

func (a *Store) FetchCallClosure(ctx context.Context, traceID string, digests, known []string, cb func(context.Context, *collogspb.ExportLogsServiceRequest) error) error

FetchCallClosure reads the call payloads of digests' recipe closures, up to the archive's cut, best-effort (archive.Client.CallClosure), in requests of at most archive.MaxCallClosureDigests digests, leaving out the closures of known calls (at most as many). A reader without the read fails with archive.ErrCallClosureUnsupported.

func (*Store) FetchLogs

func (*Store) FetchSpans

FetchSpans reads a span selection. Listened subtrees beyond what one store request accepts are read in successive requests; only the first includes the priority roots it asked for.

func (*Store) FetchTrace

func (a *Store) FetchTrace(ctx context.Context, traceID string, sink cloud.TraceImportSink) (rerr error)

func (*Store) ReadLogs

ReadLogs reads display text at the archive's fixed cut. An archive is finite, so Follow ends there too.

func (*Store) SealTime

func (a *Store) SealTime() time.Time

SealTime is the archive's independent capture boundary, unlike a Cloud display's best-effort seal inferred from the received records. It is zero for an unsealed archive.

func (*Store) SearchLogs

func (a *Store) SearchLogs(ctx context.Context, traceID string, search archive.LogSearch) (archive.LogSearchResult, error)

SearchLogs searches the archive's display text, up to its cut.

type StoreLogQuerier

type StoreLogQuerier interface {
	LogQuery(context.Context, string, archive.StreamOptions, archive.LogQuery, func(int64, *collogspb.ExportLogsServiceRequest) error) (int64, error)
}

StoreLogQuerier is the archive client's multi-span log read (archive.Client.LogQuery), which Store.ReadLogs needs of its reader.

type StoreLogSearcher

type StoreLogSearcher interface {
	SearchLogs(ctx context.Context, traceID string, unsealed bool, search archive.LogSearch) (archive.LogSearchResult, error)
}

StoreLogSearcher is the archive client's search (archive.Client.SearchLogs).

type StoreReader

StoreReader is the engine telemetry store's read-only signal transport (the archive client). It also permits reusing a restore's already verified cut without downloading its bootstrap again.

Jump to

Keyboard shortcuts

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