logclient

package
v0.0.11 Latest Latest
Warning

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

Go to latest
Published: Oct 8, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

README

logclient — reading a finished sandbox's logs

A sandbox's Pod holds its logs only while it exists. Once the sandbox is released the Pod is recycled and the Kubernetes log API has nothing left to return, so anyone asking "what did that run print" has to be sent to the central log service the lines were shipped to. This package is that query.

ProjectFor and QueryOptions.Scope are the two things worth knowing here; the package doc in logclient.go explains both. This file is about the chain around them, because the query being right is not sufficient for a log to reach a human.

Everything on this path fails the same way

The service answers a query that matches nothing with 200 and an empty body. So all of these are one indistinguishable outcome at the transport:

  • the sandbox genuinely printed nothing
  • the cluster was not scoped into the query (no filters)
  • the wrong log store was asked (project)
  • the cluster ships no container output at all

Nothing in this package can tell them apart. That is why QueryOptions.Scope exists: every caller reports what it asked alongside what came back, so a reader can tell which of the four they are looking at. Keep that property when adding a caller — an empty result with no explanation costs hours.

The four consumers, and the order they fail in

Reaching a user's screen takes four independent hops, and any one of them going wrong renders the same empty panel:

# Hop Where
1 The console decides whether to ask at all dashboard/app/api/sandbox-logs/config/route.ts
2 The endpoint the console calls answers for a dead Pod handlers/logs_stream.go → streamCentralLogsToEnc
3 The cluster's scope reaches the Worker proto/.../sync.proto LogsConfig → both converters
4 The query itself is right this package

Only #4 is here, and it is the last one to suspect. All four have been broken at once; see docs/troubleshooting/central-logs-empty-project-mismatch.md in the deployment repo for the symptom-first version.

Two invariants that are easy to break without noticing:

  • The gate (#1) must match getLogConfig() in the route that serves the query. It once required LOG_APP_ID — the variable whose absence selects Bearer auth — so every Bearer deployment reported "not configured" and the console silently fell back to the live-stream endpoint, which has nothing to say about a recycled Pod.
  • Both log endpoints must answer for a finished sandbox. GET /logs and GET /logs/stream are separate code paths with separate fallbacks. The streaming one is what the console calls.

Sharding

Where a deployment splits container output across two stores, the store is a property of the query (which namespace) rather than of the deployment, so it cannot be configured once per Worker. ProjectFor holds the rule; the flag that turns it on (ClusterEntry.Logs.SplitProject) is hub configuration that reaches a Worker only over the sync snapshot. dashboard/lib/cluster-config.ts carries the same rule for the console — both halves query the same gateway, so a disagreement shows up as the console and the API answering differently about one sandbox. There is a test on each side running the same table.

Documentation

Overview

Package logclient reads container logs from the platform's central log service.

A sandbox's Pod holds its logs only while it exists. Once the sandbox is released the Pod is recycled and the Kubernetes log API has nothing left to return — but the lines were shipped to the central service, which is where anyone asking "what did that run print" has to be sent. The dashboard has queried it since the log integration landed; this is the same query from the worker, so the API can answer for a sandbox that has already ended.

Every failure here looks the same

The service answers a query that matches nothing with 200 and an empty body. So "that pod printed nothing", "this cluster is not scoped into the query", "the wrong log store was asked" and "this cluster ships no container output at all" are one indistinguishable outcome. Nothing in this package can tell them apart, which is why QueryOptions.Scope exists: callers report what they asked alongside what came back, and someone reading the result can see which of the four it was.

Index

Constants

View Source
const (
	// TenantNamespacePrefix marks a namespace as belonging to a tenant.
	TenantNamespacePrefix = "t-"
	// TenantProject holds tenant namespaces' output on a sharded deployment.
	TenantProject = "default"
	// PlatformProject holds everything else on a sharded deployment.
	PlatformProject = "internal"
)

Log-store sharding, for deployments whose central service splits container output across more than one store.

Where it is in use, the split is by namespace: tenant workloads land in one store and everything else — platform components, system namespaces — in another. Which clusters do this is deployment configuration (ClusterEntry.Logs.SplitProject), because a cluster that does not shard will return an empty result for the store it does not use, with a 200 and no error to say so.

Variables

This section is empty.

Functions

func CloneFilters

func CloneFilters(in map[string]string) map[string]string

CloneFilters returns a copy safe to hand to a query.

func ProjectFor added in v0.0.11

func ProjectFor(splitProject bool, namespace string) string

ProjectFor picks the log store to query for one namespace.

Returns the empty string when the cluster is not sharded, which leaves the endpoint's own `project` (or Config.Project) in force — the single-store case, and the one every cluster looked like before sharding existed.

Types

type Client

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

Client queries the central log service.

func New

func New(cfg Config) *Client

New returns a Client. An empty URL or Token leaves it unconfigured; callers must check Ready.

func (*Client) DefaultProject added in v0.0.11

func (c *Client) DefaultProject() string

DefaultProject returns the log store used when a query names none. Callers report it alongside an empty result, which is otherwise indistinguishable from having asked the wrong store.

func (*Client) Query

func (c *Client) Query(ctx context.Context, opts QueryOptions) ([]Entry, error)

Query returns the lines the named Pod produced within the requested window.

func (*Client) Ready

func (c *Client) Ready() bool

Ready reports whether the service is configured.

func (*Client) SetConfig

func (c *Client) SetConfig(cfg Config)

SetConfig replaces the endpoint and credentials.

type Config

type Config struct {
	// URL is the download endpoint, e.g.
	// https://op.example.com/api/v1/rms/logging/download
	URL string
	// AppID selects the authentication scheme: set it for the signed scheme
	// (Signature/AppID/Timestamp/Randstr), leave it empty for Bearer.
	AppID string
	// Token is the signing token, or the bearer token when AppID is empty.
	Token string
	// Project scopes the query on gateways that require it; empty omits it.
	Project string
	// Timeout bounds one query.
	Timeout time.Duration
}

Config addresses the central log service.

type Entry

type Entry struct {
	Timestamp     time.Time
	Log           string
	ContainerName string
	PodName       string
}

Entry is one log line as the service returns it.

type QueryOptions added in v0.0.11

type QueryOptions struct {
	// PodName is the pod whose output is wanted.
	PodName string
	// Filters scope the query to one cluster (region / cluster labels). They are
	// not optional in practice: pod names are unique per cluster, not globally,
	// so an unscoped query can return another cluster's output for the same name.
	Filters map[string]string
	// Container narrows the query to one container of the Pod. Empty returns
	// every container the collector shipped — which for a sandbox Pod means the
	// egress proxy's per-connection lines mixed in with the sandbox's own.
	Container string
	// Project overrides the configured log store for this query. Empty uses
	// Config.Project. A deployment that shards its store by namespace needs a
	// different value per query, not per process — see ProjectFor.
	Project string
	// Start and End bound the query window.
	Start, End time.Time
	// Limit caps the returned entries; 0 means no cap.
	Limit int
}

QueryOptions addresses one central-log query.

func (QueryOptions) Scope added in v0.0.11

func (o QueryOptions) Scope(defaultProject string) string

Scope describes, in one line, what a query actually asked for.

A query that matches nothing returns 200 with an empty body, so "no rows" and "you asked the wrong question" are indistinguishable at the transport. The caller has to be able to show what it asked, or every empty result turns into the same unanswerable ticket.

Jump to

Keyboard shortcuts

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