cloud

package
v1.0.0-beta.15 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// LogRecordsAll is every log row: text output and the semantic records
	// riding the log channel (call payloads, progress, agent state, span
	// names).
	LogRecordsAll = ""
	// LogRecordsLogs is text output only, with the global/verbose records
	// dropped -- what a rolled-up "show me this span's output" wants. It
	// requires a span ID.
	LogRecordsLogs = "logs"
	// LogRecordsCallPayloads is the dagql call payload records alone.
	LogRecordsCallPayloads = "call_payloads"
)

Log record classes a /v1/logs stream can be narrowed to (the server's `records` parameter). The zero value is every record.

View Source 
const (
	TraceListSortStart    = "START"
	TraceListSortDuration = "DURATION"
)

Sort orders for Org.traceList.

View Source 
const (
	TraceStatePassed  = "passed"
	TraceStateFailed  = "failed"
	TraceStateRunning = "running"
)

Trace states as the CLI shows them.

Variables

View Source 
var ErrNoOrg = errors.New("no org associated with this Engine")
View Source 
var ErrStreamStalled = errors.New("cloud OTLP stream stalled")

ErrStreamStalled identifies a stream that exceeded its idle timeout.

Functions

This section is empty.

Types

type Check 

type Check struct {
	ID            string     `json:"id"`
	Name          string     `json:"name"`
	Status        string     `json:"status"`
	StartedAt     *time.Time `json:"startedAt"`
	EndTime       *time.Time `json:"endTime"`
	Duration      *int       `json:"duration"`
	TraceID       string     `json:"traceId"`
	SpanID        string     `json:"spanId"`
	ModuleRef     string     `json:"moduleRef"`
	ModuleVersion string     `json:"moduleVersion"`
	Internal      bool       `json:"internal"`
}

func (*Check) DurationAsTime 

func (c *Check) DurationAsTime() time.Duration

type CheckActor 

type CheckActor struct {
	ID        string `json:"id"`
	Login     string `json:"login"`
	Name      string `json:"name"`
	AvatarURL string `json:"avatarUrl"`
}

type CheckCommit 

type CheckCommit struct {
	Repo          string           `json:"repo"`
	CommitSHA     string           `json:"commitSHA"`
	CommitMessage string           `json:"commitMessage"`
	Timestamp     time.Time        `json:"timestamp"`
	AuthorName    string           `json:"authorName"`
	AuthorEmail   string           `json:"authorEmail"`
	Events        []CheckEvent     `json:"events"`
	Refs          []CheckCommitRef `json:"refs"`
	Checks        []Check          `json:"checks"`
	// Org identifies the owning org of the commit. It is only populated by
	// user-scoped queries (e.g. UserChecks) where checks may span orgs; the
	// org-scoped queries leave it zero since the org is known from context.
	Org CheckCommitOrg `json:"org"`
}

type CheckCommitOrg 

type CheckCommitOrg struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type CheckCommitRef 

type CheckCommitRef struct {
	Typename string `json:"__typename"`

	Name string `json:"name,omitempty"`
	URL  string `json:"url,omitempty"`

	Number            int    `json:"number,omitempty"`
	Title             string `json:"title,omitempty"`
	State             string `json:"state,omitempty"`
	IntegrationCommit string `json:"integrationCommit,omitempty"`
}

type CheckEvent 

type CheckEvent struct {
	Provider  string     `json:"provider"`
	Type      string     `json:"type"`
	Timestamp time.Time  `json:"timestamp"`
	Actor     CheckActor `json:"actor"`
}

type Client 

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

func NewClient 

func NewClient(
	ctx context.Context,
	cloudAuth *auth.Cloud,
) (*Client, error)

func (*Client) ConfigureSource 

func (c *Client) ConfigureSource(ctx context.Context, installationID, mode string, repositories []string) (*MappedSource, error)

func (*Client) CreatePortalSession 

func (c *Client) CreatePortalSession(ctx context.Context, orgID string) (string, error)

func (*Client) DeleteOrgRepoSetting 

func (c *Client) DeleteOrgRepoSetting(ctx context.Context, orgID, repo string) (bool, error)

func (*Client) Engine added in v0.18.9 

func (c *Client) Engine(ctx context.Context, req EngineRequest) (*EngineSpec, error)

func (*Client) GitHubOAuthURL 

func (c *Client) GitHubOAuthURL(ctx context.Context, redirectURI string) (string, error)

func (*Client) LastUserTraceID 

func (c *Client) LastUserTraceID(ctx context.Context, orgName string) (string, error)

LastUserTraceID returns the ID of the logged-in user's most recent trace in the org, or "" when there is none.

func (*Client) ModuleChecks 

func (c *Client) ModuleChecks(
	ctx context.Context,
	org string,
	moduleRef string,
	moduleVersion string,
) ([]CheckCommit, error)

func (*Client) MonthComputeUsage 

func (c *Client) MonthComputeUsage(ctx context.Context, orgID, month string) (*MonthlyComputeUsage, error)

MonthComputeUsage returns the Cloud Engine compute usage total (core minutes and cost) for the given org and UTC month (YYYY-MM). The daily breakdown is intentionally not requested; see MonthlyComputeUsage.

func (*Client) MonthUsage 

func (c *Client) MonthUsage(ctx context.Context, orgID, month string) (*MonthlyUsage, error)

MonthUsage returns the telemetry usage (spans and log lines) for the given org and month. The month argument is the first day of the UTC month (YYYY-MM-01).

func (*Client) OrgByName added in v0.20.0 

func (c *Client) OrgByName(ctx context.Context, name string) (*OrgResponse, error)

func (*Client) OrgChecks 

func (c *Client) OrgChecks(
	ctx context.Context,
	org string,
	repos []string,
	first int,
) ([]CheckCommit, error)

func (*Client) OrgDetails 

func (c *Client) OrgDetails(ctx context.Context, orgName string) (*OrgDetails, error)

func (*Client) OrgMappedSources 

func (c *Client) OrgMappedSources(ctx context.Context, orgName string) ([]MappedSource, error)

func (*Client) OrgRepoSetting 

func (c *Client) OrgRepoSetting(ctx context.Context, orgName, repo string) (*RepoSetting, error)

func (*Client) Plans 

func (c *Client) Plans(ctx context.Context) (*PlansResponse, error)

func (*Client) Repos 

func (c *Client) Repos(ctx context.Context) ([]Repo, error)

func (*Client) RerunChecks 

func (c *Client) RerunChecks(ctx context.Context, orgID string, checkIDs []string, cleanSlate bool) ([]Check, error)

RerunChecks re-runs the given checks (by ID) on Dagger Cloud, against the same commit they originally ran on, and returns the newly queued check runs. Checks that are already running or queued are skipped server-side and won't appear in the result. cleanSlate requests a no-cache-reuse run; it's an experimental, org-gated feature and is ignored when unavailable.

func (*Client) RerunLoad 

func (c *Client) RerunLoad(ctx context.Context, orgID, checkID string) (*Check, error)

RerunLoad re-runs a failed load check (the gate that discovers and runs a commit's checks) by ID, returning the newly queued load check. Load checks are internal and can't go through RerunChecks; the server requires the check to be a failed load check.

func (*Client) SourceRepositories 

func (c *Client) SourceRepositories(ctx context.Context, installationID, orgID string) ([]SourceRepository, error)

func (*Client) Sources 

func (c *Client) Sources(ctx context.Context) ([]Source, error)

func (*Client) TraceList 

func (c *Client) TraceList(ctx context.Context, orgName string, filter TraceListFilter, sort string, first int) ([]TraceSummary, error)

TraceList lists an org's traces, local and CI, that match filter.

func (*Client) TraceMetadata 

func (c *Client) TraceMetadata(ctx context.Context, orgID, traceID string) (*TraceMetadata, error)

TraceMetadata fetches a trace's git/CI context. Returns nil (no error) when the trace has no metadata recorded.

func (*Client) UpdateOrgRepoSetting 

func (c *Client) UpdateOrgRepoSetting(ctx context.Context, orgID, repo string, isPublic bool) (bool, error)

func (*Client) User 

func (c *Client) User(ctx context.Context) (*UserResponse, error)

func (*Client) UserChecks 

func (c *Client) UserChecks(
	ctx context.Context,
	repos []string,
	first int,
) ([]CheckCommit, error)

func (*Client) UserRepositories 

func (c *Client) UserRepositories(ctx context.Context, refs ...string) ([]Repository, error)

UserRepositories returns the repo-scoped Cloud configuration for the given refs, scoped to the authenticated user. Only repos that are currently auto-checked (selected) are returned.

type EngineRequest added in v0.19.1 

type EngineRequest struct {
	Module               string   `json:"module,omitempty"`
	Function             string   ` json:"function,omitempty"`
	ExecCmd              []string `json:"exec_cmd,omitempty"`
	ClientID             string   `json:"client_id,omitempty"`
	MinimumEngineVersion string   `json:"minimum_engine_version,omitempty"`
	TraceID              string   `json:"trace_id,omitempty"`
}

type EngineSpec added in v0.18.9 

type EngineSpec struct {
	EngineRequest

	Image          string                   `json:"image,omitempty"`
	Location       string                   `json:"location,omitempty"`
	OrgID          string                   `json:"org_id,omitempty"`
	UserID         string                   `json:"user_id,omitempty"`
	URL            string                   `json:"url,omitempty"`
	CertSerialized *SerializableCertificate `json:"cert,omitempty"`
	InstanceID     string                   `json:"instance_id,omitempty"`
}

func (*EngineSpec) TLSCertificate added in v0.18.9 

func (es *EngineSpec) TLSCertificate() (*tls.Certificate, error)

type ErrResponse added in v0.18.9 

type ErrResponse struct {
	Message string `json:"message"`
}

type Feature 

type Feature struct {
	Name       string  `json:"name"`
	Status     string  `json:"status"`
	TrialStart *string `json:"trialStart,omitempty"`
	TrialEnd   *string `json:"trialEnd,omitempty"`
}

type LogSelection 

type LogSelection struct {
	SpanID      string
	Descendants bool
	After       *time.Time
	Records     string
}

LogSelection narrows a /v1/logs stream to one span's records, mirroring the server's parseLogStreamOptions and the logsEmitted subscription:

  • SpanID selects the span; Descendants rolls its subtree up too, walking past boundary/encapsulated/internal spans the way the UI does. The stream ends once the selected span has ended.
  • After bounds records by timestamp.
  • Records picks the record class (LogRecords*).

type MappedSource 

type MappedSource struct {
	SourceName     string   `json:"sourceName"`
	InstallationID string   `json:"installationId"`
	Mode           string   `json:"mode"`
	Repositories   []string `json:"repositories"`
}

type MonthlyComputeUsage 

type MonthlyComputeUsage struct {
	CoreMinutes        float64 `json:"coreMinutes"`
	CostUSD            float64 `json:"costUSD"`
	PricePerCoreMinute float64 `json:"pricePerCoreMinute"`
}

MonthlyComputeUsage is the Cloud Engine compute usage total for a UTC calendar month. The API also exposes a per-day breakdown via the daily field, but this command reports only the total, so it is intentionally not requested: on the server the daily field is resolved separately and skipping it avoids the expensive per-day expansion for large orgs.

type MonthlyUsage 

type MonthlyUsage struct {
	Usage int `json:"usage"`
	Cap   int `json:"cap"`
}

MonthlyUsage is the telemetry usage (spans and log lines ingested) for a UTC calendar month, along with the plan cap.

type OTLPClient 

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

OTLPClient streams a whole published trace out of Dagger Cloud as OTLP.

func NewOTLPClient 

func NewOTLPClient(ctx context.Context, cloudAuth *auth.Cloud) (*OTLPClient, error)

NewOTLPClient returns a client for the binary OTLP stream endpoints, reading the base URL from DAGGER_CLOUD_URL exactly as NewClient does.

cloudAuth comes from auth.GetCloudAuth, the same value NewClient takes — passing it in rather than fetching it keeps the one interactive/credential -reading step at the caller, where `dagger trace` already does it.

func (*OTLPClient) FetchLogs 

func (c *OTLPClient) FetchLogs(ctx context.Context, traceID string, sel LogSelection, cb func(context.Context, *collogspb.ExportLogsServiceRequest) error) error

FetchLogs streams the log records sel selects from traceID to cb, one export request per data frame, until the server's terminal frame.

func (*OTLPClient) FetchSpans 

func (c *OTLPClient) FetchSpans(ctx context.Context, traceID string, sel SpanSelection, cb func(context.Context, *coltracepb.ExportTraceServiceRequest) error) error

FetchSpans streams the spans sel selects from traceID to cb, one export request per data frame, until the server's terminal frame. Unlike FetchTrace it neither seals nor touches logs and metrics: the caller is assembling a view incrementally and owns that bookkeeping.

func (*OTLPClient) FetchTrace 

func (c *OTLPClient) FetchTrace(ctx context.Context, traceID string, sink TraceImportSink) error

FetchTrace streams the whole of traceID into sink and seals it.

The three network streams run concurrently so a slow or blocked endpoint does not prevent the others from transferring. Sink callbacks remain serialized: TraceImportSink deliberately makes no concurrency-safety promise, and common sinks (including the OTel SDK exporters and a bare dagui.DB) require callers not to invoke exports concurrently.

Once all three streams stop, no late span callbacks remain. FetchTrace then calls Seal exactly once with the parent context, even after a stream error, so partial span snapshots become a consistent bounded import. A seal error is joined with the stream error rather than masking it.

func (*OTLPClient) StatsSummary 

func (c *OTLPClient) StatsSummary() string

StatsSummary returns a human-readable breakdown of what the fetch pulled from Cloud, for --debug diagnostics.

func (*OTLPClient) WithBaseURL 

func (c *OTLPClient) WithBaseURL(base string) (*OTLPClient, error)

WithBaseURL points the client at a different base URL than DAGGER_CLOUD_URL resolved to.

It exists for callers that serve the §5.1 endpoints themselves — the end-to-end restore test stands up its own, over a capture of a real agent session. The alternative, setting DAGGER_CLOUD_URL, is a process-wide mutation no parallel test suite can make safely, and it would reach every other Cloud client in the process.

func (*OTLPClient) WithStallTimeout 

func (c *OTLPClient) WithStallTimeout(timeout time.Duration) *OTLPClient

WithStallTimeout returns a copy that stops any stream after it delivers no bytes for timeout. The timeout measures idle time, not total fetch time; Heartbeat frames and payloads both reset it. A non-positive timeout disables the watchdog.

type OrgDetails 

type OrgDetails struct {
	ID           string           `json:"id"`
	Name         string           `json:"name"`
	CreatedAt    string           `json:"createdAt"`
	Subscription SubscriptionInfo `json:"subscription"`
	Features     []Feature        `json:"features"`
}

type OrgResponse added in v0.20.0 

type OrgResponse struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type Plan 

type Plan struct {
	Item  PlanItem    `json:"item"`
	Price []PlanPrice `json:"price"`
}

type PlanItem 

type PlanItem struct {
	ID           string `json:"id"`
	ExternalName string `json:"external_name"`
}

type PlanPrice 

type PlanPrice struct {
	ID           string `json:"id"`
	ItemID       string `json:"item_id"`
	ExternalName string `json:"external_name"`
	Unit         string `json:"unit"`
	Price        uint   `json:"price"`
	PeriodUnit   string `json:"period_unit"`
}

type PlansResponse 

type PlansResponse struct {
	Plans []Plan `json:"plans"`
}

type Repo 

type Repo struct {
	Name     string `json:"name"`
	FullName string `json:"fullName"`
	Private  bool   `json:"private"`
}

type RepoSetting 

type RepoSetting struct {
	Repo     string `json:"repo"`
	IsPublic bool   `json:"isPublic"`
}

type Repository 

type Repository struct {
	Ref          string        `json:"ref"`
	Settings     *RepoSetting  `json:"settings"`
	MappedSource *MappedSource `json:"mappedSource"`
}

Repository is a repo-scoped view of Cloud configuration, reachable through the user-scoped User.repositories(refs:) field. It only surfaces repos that are currently auto-checked (selected under a mapped source).

type SerializableCertificate added in v0.18.9 

type SerializableCertificate struct {
	CertificateChain [][]byte `json:"certificate_chain"` // DER-encoded certs
	PrivateKey       []byte   `json:"private_key"`       // PKCS#8 encoded private key
	OCSPStaple       []byte   `json:"ocsp_staple,omitempty"`
	SCTs             [][]byte `json:"scts,omitempty"`
}

type Source 

type Source struct {
	Name         string  `json:"name"`
	ID           string  `json:"id"`
	Type         string  `json:"type"`
	ConfiguredAt string  `json:"configuredAt"`
	OrgName      *string `json:"orgName"`
	ConfigURL    string  `json:"configUrl"`
}

type SourceRepository 

type SourceRepository struct {
	Repository string `json:"repository"`
	Selected   bool   `json:"selected"`
}

type SpanSelection 

type SpanSelection struct {
	NoRoot      bool
	Listen      []string
	Incremental bool
	Before      *time.Time
	After       *time.Time
	DagUIView   bool
}

SpanSelection narrows a /v1/traces stream. It mirrors the server's parseTraceStreamOptions (api/otlp/stream_options.go in dagger.io), which shares its query layer with the spansUpdated GraphQL subscription, so these have the semantics the Cloud web UI drives:

  • Root selects the root span(s) and their visible children; the roots also anchor completion, so a stream with Root set ends once every root has been over for a few seconds. The zero value is the server's default (true), spelled out on the wire either way.
  • Listen adds each span, its children and their passthrough descendants, and anchors completion on them too. At most 256 per request.
  • Incremental forces the priority-only selection regardless of trace size; without it a trace under the server's threshold comes back whole even when Listen is set.
  • Before/After bound spans by their Cloud-side update time. Before also bounds the STREAM: one poll, then the terminal frame -- which is what makes a backfill on a still-running span return instead of follow.
  • DagUIView asks for the dagger.io/ui.* egress attributes (child count, has-logs, partial, update time; engine/telemetryattrs) an incremental, lazily-expanding view needs and the OTLP span form otherwise lacks.

type SubscriptionInfo 

type SubscriptionInfo struct {
	Status         string  `json:"status"`
	TrialStart     *string `json:"trialStart,omitempty"`
	TrialEnd       *string `json:"trialEnd,omitempty"`
	SubscriptionID string  `json:"subscriptionID"`
	PlanID         string  `json:"planID"`
	HasCaching     bool    `json:"hasCaching"`
}

type TraceCIChange 

type TraceCIChange struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Branch  string `json:"branch"`
	HeadSHA string `json:"headSHA"`
}

type TraceCIMetadata 

type TraceCIMetadata struct {
	IsNativeCI bool           `json:"isNativeCI"`
	Provider   *string        `json:"provider"`
	Repository *string        `json:"repository"`
	Change     *TraceCIChange `json:"change"`
}

type TraceGitAuthor 

type TraceGitAuthor struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

type TraceGitMetadata 

type TraceGitMetadata struct {
	Remote string          `json:"remote"`
	Title  string          `json:"title"`
	Ref    string          `json:"ref"`
	Tag    *string         `json:"tag"`
	Branch *string         `json:"branch"`
	Author *TraceGitAuthor `json:"author"`
}

type TraceImportSink 

type TraceImportSink interface {
	ImportSpans(context.Context, *coltracepb.ExportTraceServiceRequest) error
	ImportLogs(context.Context, *collogspb.ExportLogsServiceRequest) error
	ImportMetrics(context.Context, *colmetricspb.ExportMetricsServiceRequest) error
	Seal(context.Context) error
}

TraceImportSink receives the OTLP export requests a fetch decodes, and is told once when the stream has ended.

engine/telemetry.TraceImporter is the implementation resume uses; the interface is here so this package stays transport-only (it has no opinion about sealing, passthrough stamps or where the spans finally land) and so a test can observe the call sequence.

Seal is what turns "no end time" into a fact: a live span is exported at START and again at end, so a span the capture shows running is only really unfinished once importing has stopped. FetchTrace calls it exactly once after all three stream goroutines return, including on partial or failed fetches. Implementations need not be concurrency-safe; FetchTrace serializes all callbacks while fetching the streams in parallel.

type TraceListFilter 

type TraceListFilter struct {
	Repos       []string   `json:"repos,omitempty"`
	Branch      string     `json:"branch,omitempty"`
	Commit      string     `json:"commit,omitempty"`
	Tag         string     `json:"tag,omitempty"`
	Change      string     `json:"change,omitempty"`
	Status      string     `json:"status,omitempty"` // PASSED, FAILED or RUNNING
	Local       *bool      `json:"local,omitempty"`
	Mine        bool       `json:"mine,omitempty"`
	User        string     `json:"user,omitempty"`
	Token       string     `json:"token,omitempty"`
	Author      string     `json:"author,omitempty"`
	Name        string     `json:"name,omitempty"`
	Provider    string     `json:"provider,omitempty"`
	Since       *time.Time `json:"since,omitempty"`
	Until       *time.Time `json:"until,omitempty"`
	MinDuration float64    `json:"minDuration,omitempty"` // seconds
	MaxDuration float64    `json:"maxDuration,omitempty"` // seconds
}

TraceListFilter narrows Org.traceList. Zero fields do not filter.

type TraceMetadata 

type TraceMetadata struct {
	Git *TraceGitMetadata `json:"git"`
	CI  *TraceCIMetadata  `json:"ci"`
}

TraceMetadata is the trace's source git/CI context. A query fills only the fields it selects.

type TraceRef 

type TraceRef struct {
	TraceID string
	Org     string
	SpanID  string
}

TraceRef addresses a trace, and optionally the org and span that a Dagger Cloud link names.

func ParseTraceRef 

func ParseTraceRef(s string) (TraceRef, error)

ParseTraceRef reads a trace ID, a pasted 'dagger cloud traces view <id>' or 'dagger trace <id>' command, or a https://dagger.cloud/<org>/traces/<id> link, which can select a span with ?span=<id>.

Links are identifiers only: requests always go to the configured Cloud API, never to a host from the input. Other hosts, arbitrary URLs and shell syntax are rejected, and the error does not repeat the input.

type TraceSender 

type TraceSender struct {
	Name string `json:"name"`
}

type TraceStatus 

type TraceStatus struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type TraceSummary 

type TraceSummary struct {
	ID        string       `json:"id"`
	Name      string       `json:"name"`
	Status    *TraceStatus `json:"status"`
	Timestamp time.Time    `json:"timestamp"`
	EndTime   *time.Time   `json:"endTime"`
	Local     bool         `json:"local"`
	Sender    *TraceSender `json:"sender"`
	TraceMetadata
}

TraceSummary is one row of Org.traceList.

func (*TraceSummary) Duration 

func (t *TraceSummary) Duration(now time.Time) time.Duration

Duration is the trace's run time so far, measured to now while it runs.

func (*TraceSummary) State 

func (t *TraceSummary) State() string

State is the trace's state: running until it has an end time, then failed or passed by its status code.

type UserResponse 

type UserResponse struct {
	ID   string     `json:"id"`
	Orgs []auth.Org `json:"orgs"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package otlpstream implements the binary framing Dagger Cloud's OTLP read streams speak — a byte-for-byte mirror of the server's api/otlpstream package (dagger.io#5226, "feat(cloud): stream telemetry over binary OTLP"), kept here because the server repository is not importable.
 Package otlpstream implements the binary framing Dagger Cloud's OTLP read streams speak — a byte-for-byte mirror of the server's api/otlpstream package (dagger.io#5226, "feat(cloud): stream telemetry over binary OTLP"), kept here because the server repository is not importable.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.