cloud

package
v1.0.0-beta.14 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

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

func LogMessagesToRecords added in v0.20.2

func LogMessagesToRecords(traceID string, msgs []LogMessage) []sdklog.Record

LogMessagesToRecords converts Cloud API LogMessage values into OTel SDK log records suitable for feeding into a LogExporter.

func SpansToPB added in v0.20.0

func SpansToPB(spans []SpanData) []*tracepb.ResourceSpans

SpansToPB converts Cloud API SpanData into OTLP ResourceSpans proto, suitable for feeding through telemetry.SpansFromPB and into a SpanExporter.

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) 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) StatsSummary

func (c *Client) StatsSummary() string

StatsSummary returns a human-readable breakdown of data fetched from Cloud, for --debug diagnostics.

func (*Client) StreamLogs added in v0.20.0

func (c *Client) StreamLogs(
	ctx context.Context,
	orgID string,
	traceID string,
	spanID string,
	descendants bool,
	handler func([]LogMessage),
) error

StreamLogs streams log messages for a span from Dagger Cloud's GraphQL API. When descendants is true, logs from the span's whole subtree are included; when false, only the span's own logs are returned.

func (*Client) StreamSpans added in v0.20.0

func (c *Client) StreamSpans(
	ctx context.Context,
	orgID string,
	traceID string,
	handler func([]SpanData),
) error

StreamSpans streams a trace's priority (root) spans. It's a convenience wrapper over StreamSpansWith and skips empty "caught up" batches.

func (*Client) StreamSpansWith

func (c *Client) StreamSpansWith(
	ctx context.Context,
	orgID string,
	traceID string,
	opts SpanStreamOpts,
	handler func([]SpanData),
) error

StreamSpansWith streams span data with explicit subscription options. Unlike StreamSpans it passes through empty batches: the server emits an empty batch once it has caught up to the trace's current state, which callers doing incremental loading use as a "done with this pass" signal.

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 LogMessage added in v0.20.0

type LogMessage struct {
	SpanID     *string        `json:"spanId"`
	Timestamp  time.Time      `json:"timestamp"`
	Body       string         `json:"body"`
	Attributes map[string]any `json:"attributes"`
}

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) 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 SpanData added in v0.20.0

type SpanData struct {
	ID         string         `json:"id"`
	TraceID    string         `json:"traceId"`
	TraceState string         `json:"traceState"`
	Name       string         `json:"name"`
	ParentID   *string        `json:"parentId"`
	Kind       string         `json:"kind"`
	Timestamp  time.Time      `json:"timestamp"`
	EndTime    *time.Time     `json:"endTime"`
	UpdateTime time.Time      `json:"updateTime"`
	Attributes map[string]any `json:"attributes"`
	Status     SpanStatus     `json:"status"`
	Events     []SpanEvent    `json:"events"`
	Links      []SpanLink     `json:"links"`
	Scope      SpanScope      `json:"scope"`
	HasLogs    bool           `json:"hasLogs"`
	ChildCount int            `json:"childCount"`
	Partial    bool           `json:"partial"`
}

type SpanEvent added in v0.20.0

type SpanEvent struct {
	Timestamp  time.Time      `json:"timestamp"`
	Name       string         `json:"name"`
	Attributes map[string]any `json:"attributes"`
}
type SpanLink struct {
	TraceID    string         `json:"traceId"`
	SpanID     string         `json:"spanId"`
	TraceState string         `json:"traceState"`
	Attributes map[string]any `json:"attributes"`
}

type SpanScope added in v0.20.0

type SpanScope struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type SpanStatus added in v0.20.0

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

type SpanStreamOpts

type SpanStreamOpts struct {
	Root   bool
	Listen []string
	After  *time.Time
	Before *time.Time
	// Incremental forces priority-only + listened-subtree loading regardless of
	// trace size. Falls back to a full fetch against an API that predates the
	// argument.
	Incremental bool
}

SpanStreamOpts selects which spans the GetSpanUpdates subscription returns. It mirrors the variables the Cloud web UI drives (cloud/app_server.go):

  • Root: stream the trace's priority spans (roots, revealed spans, checks, tests) plus their ancestors. The server marks spans Partial when the tree is incomplete, signalling that deeper spans must be fetched lazily.
  • Listen: also stream the subtrees of these span IDs (used to fetch a span's children on demand when the user expands it).
  • After/Before: restrict updates to a time window, used to resubscribe for live updates (After) or backfill historical children (Before).

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 {
	HeadSHA string `json:"headSHA"`
}

type TraceCIMetadata

type TraceCIMetadata struct {
	IsNativeCI bool           `json:"isNativeCI"`
	Change     *TraceCIChange `json:"change"`
}

type TraceGitMetadata

type TraceGitMetadata struct {
	Ref string `json:"ref"`
}

type TraceImportSink

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 TraceMetadata

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

TraceMetadata is the trace's source git/CI context: the commit it ran on and whether re-running via Dagger Cloud applies.

type UserResponse

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

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