collector

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package collector renders the external dbg-collector's config, manages its Docker lifecycle, and persists local state so `dbg collector` can install, inspect, and remove a collector that monitors a developer's local Postgres.

The collector itself is the Rust dbg-collector image; this package never talks to a database or the control plane directly. It only prepares config + secrets and drives Docker. Secrets are referenced in collector.toml as ${ENV} placeholders and supplied to the container via a 0600 env-file, never inlined into the TOML or onto the docker argv.

Index

Constants

View Source 
const (
	SecretEnv     = "DBG_SERVER_SECRET"
	DBPasswordEnv = "COLLECTOR_DB_PASSWORD"

	// DockerHostInternal is the hostname that resolves to the Docker host from
	// inside a container (native on Docker Desktop; on Linux we add an
	// --add-host mapping to host-gateway).
	DockerHostInternal = "host.docker.internal"
)

Env var names the rendered collector.toml references and the env-file supplies. The collector expands ${VAR} references at load time.

View Source 
const DefaultContainerName = "dbg-collector"

DefaultContainerName is the stable name for the local collector container.

View Source 
const DefaultImage = "dbgorillapublic.azurecr.io/dbg-collector:0.1.0@sha256:4874dfe63453d9335e17c37405e640b09d91090f8b78b46bbbb4adbe5337c77a"

DefaultImage is the published GA collector image, pinned by digest for reproducibility. Bump this on each release (see the collector repo's "Releasing" docs). Override with `dbg collector install --image`. Used as the fallback when the deployment advertises no preferred version.

View Source 
const ImageRepo = "dbgorillapublic.azurecr.io/dbg-collector"

ImageRepo is the published collector repository, used to build an image ref from a deployment-advertised preferred version (`<ImageRepo>:<version>`).

Variables

This section is empty.

Functions

func ClearSecrets 

func ClearSecrets(agentID string)

ClearSecrets removes both keychain entries (best-effort).

func ConfigPath 

func ConfigPath() (string, error)

ConfigPath / EnvPath / statePath are the on-disk artifact locations.

func Dir 

func Dir() (string, error)

Dir returns the per-user collector directory (~/.config/dbgorilla/collector), creating it 0700 if needed.

func DockerAvailable 

func DockerAvailable() error

DockerAvailable returns nil when a usable Docker engine is reachable.

func EnvPath 

func EnvPath() (string, error)

func ImageForVersion 

func ImageForVersion(version string) string

ImageForVersion returns the image ref for a deployment-blessed version string.

func IsLoopback 

func IsLoopback(host string) bool

IsLoopback reports whether host refers to the local loopback interface, in which case it must be rewritten to host.docker.internal for the containerized collector to reach a database running on the host.

func LoadSecrets 

func LoadSecrets(agentID string) (secret, dbPassword string, err error)

LoadSecrets reads the collector secret and DB password from the keychain.

func PinnedRef 

func PinnedRef(ref string) (string, error)

PinnedRef ensures ref is pinned to an immutable digest before we run it. If ref already carries an @sha256 digest (e.g. the built-in DefaultImage) it is returned unchanged. Otherwise — a deployment-blessed version like "<repo>:0.2.0" or a bare --image tag — the image is pulled and its repo digest resolved, yielding "<ref>@sha256:...". This keeps a centrally rolled-out version as reproducible and tamper-evident as a hard-pinned default (a tag is mutable; a digest is not).

func RemoveState 

func RemoveState() error

RemoveState deletes the state file (best-effort).

func SaveState 

func SaveState(s *State) error

SaveState writes the record atomically (tempfile + rename, 0600).

func StoreSecrets 

func StoreSecrets(agentID, secret, dbPassword string) error

StoreSecrets persists the collector secret and DB password in the OS keychain, keyed by agent id.

func WriteConfig 

func WriteConfig(path, contents string) error

WriteConfig writes the rendered collector.toml atomically. It is 0644 (not 0600) because it is bind-mounted into the collector container, which runs as a non-root user with a read-only rootfs and must be able to read it. The file holds no secrets — only ${ENV} references — so world-readable is safe.

func WriteEnvFile 

func WriteEnvFile(path, secret, dbPassword string) error

WriteEnvFile materializes the secrets into a 0600 env-file that `docker run --env-file` reads. Called on install and on start; the file is the only place plaintext secrets land on disk.

Types

type Auth 

type Auth struct {
	Method   string `toml:"method"`
	User     string `toml:"user"`
	Password string `toml:"password"`
}

Auth is [component.auth].

type Commands 

type Commands struct {
	Enabled bool `toml:"enabled"`
}

Commands is [commands].

type Component 

type Component struct {
	Name     string   `toml:"name"`
	Engine   string   `toml:"engine"`
	Provider Provider `toml:"provider"`
	Auth     Auth     `toml:"auth"`
	Connect  Connect  `toml:"connect"`
}

Component is one [[component]] to monitor.

type Config 

type Config struct {
	Dbgorilla Dbgorilla   `toml:"dbgorilla"`
	Component []Component `toml:"component"`
	Topology  Topology    `toml:"topology"`
	Commands  Commands    `toml:"commands"`
}

Config mirrors the dbg-collector collector.toml schema. Only the subset this CLI generates is modelled (postgres / self_hosted / password).

func Build 

func Build(agentID, tenantID string, target Target, eps Endpoints) Config

Build assembles a Config from the minted identity, the target, and optional endpoint overrides. A loopback target host is rewritten to host.docker.internal so the in-container collector reaches the host's DB.

func (Config) Render 

func (c Config) Render() (string, error)

Render serializes the Config to collector.toml text.

type Connect 

type Connect struct {
	Host      string   `toml:"host"`
	Port      int      `toml:"port"`
	Databases []string `toml:"databases,omitempty"`
	SSLMode   string   `toml:"ssl_mode"`
}

Connect is [component.connect].

type Dbgorilla 

type Dbgorilla struct {
	AgentID         string `toml:"agent_id"`
	TenantID        string `toml:"tenant_id"`
	Secret          string `toml:"secret"`
	OpampBaseURL    string `toml:"opamp_base_url,omitempty"`
	OtlpBaseURL     string `toml:"otlp_base_url,omitempty"`
	KeycloakBaseURL string `toml:"keycloak_base_url,omitempty"`
}

Dbgorilla is the [dbgorilla] block: identity plus optional endpoint overrides. Empty *_base_url fields fall back to the collector's built-in production defaults, so local-dev-against-prod needs none of them.

type Endpoints 

type Endpoints struct {
	OpampBaseURL    string
	OtlpBaseURL     string
	KeycloakBaseURL string
}

Endpoints carries optional explicit endpoint overrides (Phase 1: from the provisioning response; Phase 2: from the .well-known discovery document). Leave fields empty to use the collector's production defaults.

type Provider 

type Provider struct {
	Type string `toml:"type"`
}

Provider is [component.provider]. self_hosted carries no extra fields.

type Runner 

type Runner struct {
	Name        string
	Image       string
	ConfigPath  string
	EnvFilePath string
	// CACertPath, when set, is a PEM CA bundle mounted into the container and
	// pointed at via SSL_CERT_FILE so the collector trusts a private/internal
	// CA (e.g. on-prem or internal deployments). Note: this replaces the
	// system trust bundle inside the container, so it is intended for
	// deployments whose endpoints all chain to this CA.
	CACertPath string
}

Runner drives the collector container's lifecycle via the docker CLI.

func (Runner) ImageRef 

func (r Runner) ImageRef() string

ImageRef returns the image the container was created from (for status).

func (Runner) Logs 

func (r Runner) Logs(follow bool, tail string) error

Logs streams container logs to stdout/stderr. When follow is true it blocks until interrupted.

func (Runner) Remove 

func (r Runner) Remove() error

Remove force-removes the container (stopping it first if needed).

func (Runner) Restart 

func (r Runner) Restart() error

Restart restarts the container.

func (Runner) Run 

func (r Runner) Run() error

Run starts the collector container detached.

func (Runner) RunCommandString 

func (r Runner) RunCommandString() string

RunCommandString returns the printable `docker run ...` invocation, for dry-run output. Secrets are not on argv (they ride --env-file), so this is safe to display.

func (Runner) Running 

func (r Runner) Running() (exists bool, running bool, err error)

Running reports whether the container exists and is currently running.

func (Runner) Start 

func (r Runner) Start() error

Start (re)starts an existing stopped container.

func (Runner) Stop 

func (r Runner) Stop() error

Stop stops the running container.

type State 

type State struct {
	AgentID       string    `json:"agent_id"`
	TenantID      string    `json:"tenant_id"`
	Domain        string    `json:"domain"`
	ContainerName string    `json:"container_name"`
	Image         string    `json:"image"`
	ConfigPath    string    `json:"config_path"`
	EnvFilePath   string    `json:"env_file_path"`
	CACertPath    string    `json:"ca_cert_path,omitempty"`
	TargetName    string    `json:"target_name"`
	CreatedAt     time.Time `json:"created_at"`
}

State records the installed collector so status/stop/uninstall work across CLI invocations. It holds no secrets.

func LoadState 

func LoadState() (*State, error)

LoadState reads the installed-collector record. A missing file returns (nil, nil) — no collector installed.

type Target 

type Target struct {
	Name      string
	Host      string
	Port      int
	Databases []string
	User      string
	SSLMode   string
}

Target describes one local database the developer wants monitored.

func (Target) HostDial 

func (t Target) HostDial() string

HostDial returns the host:port a process on the host (i.e. this CLI) uses to reach the target, for the pre-install reachability check. This deliberately uses the original loopback host, not the rewritten container host.

type Topology 

type Topology struct {
	Interval string `toml:"interval"`
}

Topology is [topology].

Source Files

View all Source files

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.