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
- Variables
- func CanFallback(ctx context.Context, err error) bool
- type CallClosureReader
- type CloudLogFetcher
- type CloudLogs
- type Live
- type LiveLogClient
- type LogQuery
- type LogReader
- type LogSearcher
- type Open
- type Source
- type Store
- func (a *Store) ConversationOnly() *Store
- func (a *Store) FetchBootstrap(ctx context.Context, sink cloud.TraceImportSink) error
- func (a *Store) FetchCallClosure(ctx context.Context, traceID string, digests, known []string, ...) error
- func (a *Store) FetchLogs(ctx context.Context, traceID string, sel cloud.LogSelection, ...) error
- func (a *Store) FetchSpans(ctx context.Context, traceID string, sel cloud.SpanSelection, ...) error
- func (a *Store) FetchTrace(ctx context.Context, traceID string, sink cloud.TraceImportSink) (rerr error)
- func (a *Store) ReadLogs(ctx context.Context, traceID string, q LogQuery, ...) error
- func (a *Store) SealTime() time.Time
- func (a *Store) SearchLogs(ctx context.Context, traceID string, search archive.LogSearch) (archive.LogSearchResult, error)
- type StoreLogQuerier
- type StoreLogSearcher
- type StoreReader
Constants ¶
const DefaultCloudLogConcurrency = 8
DefaultCloudLogConcurrency bounds CloudLogs' concurrent per-span streams.
Variables ¶
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 ¶
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.
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 ¶
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 ¶
type Source interface {
FetchTrace(context.Context, string, cloud.TraceImportSink) error
FetchSpans(context.Context, string, cloud.SpanSelection, func(context.Context, *coltracepb.ExportTraceServiceRequest) error) error
FetchLogs(context.Context, string, cloud.LogSelection, func(context.Context, *collogspb.ExportLogsServiceRequest) error) error
}
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.
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 OpenStore ¶
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 ¶
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 ¶
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) FetchSpans ¶
func (a *Store) FetchSpans(ctx context.Context, traceID string, sel cloud.SpanSelection, cb func(context.Context, *coltracepb.ExportTraceServiceRequest) error) error
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 (*Store) ReadLogs ¶
func (a *Store) ReadLogs(ctx context.Context, traceID string, q LogQuery, cb func(context.Context, *collogspb.ExportLogsServiceRequest, string) error) error
ReadLogs reads display text at the archive's fixed cut. An archive is finite, so Follow ends there too.
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 ¶
type StoreReader interface {
Traces(context.Context, string, archive.StreamOptions, func(int64, *coltracepb.ExportTraceServiceRequest) error) (int64, error)
Logs(context.Context, string, archive.StreamOptions, func(int64, *collogspb.ExportLogsServiceRequest) error) (int64, error)
Metrics(context.Context, string, archive.StreamOptions, func(int64, *colmetricspb.ExportMetricsServiceRequest) error) (int64, error)
}
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.