entity

package
v0.10.157 Latest Latest
Warning

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

 Go to latest Published: Aug 29, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package entity — K8s ENTITY KATMANI (v0.10.129, AŞAMA 3 adım 3; docs/plans/entity-layer-design-2026-08-28.md).

cluster > node > namespace > workload > pod > container hiyerarşisi + ayrı service ekseni. Kök kimlik Remote Cluster kaydının id'si (thanos.ClusterConfig.EffectiveID) — keşfedilmez, konfigürasyondan gelir. Bu paket saf çekirdekleri (kimlik, normalizasyon, ömür farkı) ve senkronizasyon işçisini taşır; CH okuma/yazma chstore'da.

Index

Constants

View Source 
const (
	TypeCluster   = "cluster"
	TypeNode      = "node"
	TypeNamespace = "namespace"
	TypeWorkload  = "workload"
	TypePod       = "pod"
	TypeContainer = "container"
	TypeService   = "service"
)

Varlık tipleri (entities.entity_type).

View Source 
const (
	RelParent = "parent"  // cluster→node, cluster→ns, ns→wl, wl→pod, ns→pod (iş yüksüz), pod→ctr
	RelRunsOn = "runs_on" // pod→node
	RelRuns   = "runs"    // pod→service
)

İlişki tipleri (entity_relations.rel_type).

View Source 
const (
	SourceThanos = "thanos"
	SourceSpan   = "span"
)

Kaynak damgaları (entities.source).

View Source 
const (
	RunOK      = "ok"
	RunPartial = "partial"
	RunFailed  = "failed"
	RunSkipped = "skipped"
)
View Source 
const BackfillLookback = 24 * time.Hour

BackfillLookback — Tick'in span geçişi penceresi: atama sonrası kısa bir süre (BackfillUntil) 24 saat, sonra normal seenLookback.

View Source 
const SettingsKey = "entity_layer"
View Source 
const UnmappedClusterID = "(unmapped)"

UnmappedClusterID — eşlenemeyen span cluster değerlerinin koşu satırı.

Variables

This section is empty.

Functions

func AllowedLabels 

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

AllowedLabels — allow-list süzgeci (+ app.kubernetes.io/* öneki).

func ClosedRowsForDead added in v0.10.141 

func ClosedRowsForDead(cid string, dead []SeenRow) ([]EntityRow, []RelationRow)

ClosedRowsForDead — saf: ölü satırlardan yalnız POD entity'leri (kapalı ömür) + ilişkileri (parent ns→pod, runs pod→svc, runs_on pod→node; hepsi kapalı). Namespace/servis/node kayıtları canlı yoldan gelir; burada üretilmez. Aynı pod'un birden çok satırı (servis başına) birleşir.

func ClusterID 

func ClusterID(cid string) string

func ContainerID 

func ContainerID(cid, ns, pod, ctr string) string

func GroupSeenByCluster 

func GroupSeenByCluster(rows []SeenRow, refs []ClusterRef) (map[string][]SeenRow, map[string]int)

GroupSeenByCluster — satırları cluster_id'ye göre böler; eşlenemeyenleri sayar.

func NamespaceID 

func NamespaceID(cid, ns string) string

func NodeID 

func NodeID(cid, node string) string

func Normalize 

func Normalize(cid string, s Snapshot) ([]Entity, []Relation)

Normalize — anlık görüntü → varlıklar + ilişkiler, id sırasında.

func ParseIDOK 

func ParseIDOK(id string) bool

ParseIDOK — kapanış sayacı için: id bir varlık mı (ilişki anahtarı değil).

func PodID 

func PodID(cid, ns, pod string) string

func ResolveWorkload 

func ResolveWorkload(ns, pod string, idx OwnerIndex) (kind, name string, ok bool)

ResolveWorkload — pod'un iş yükü (tür, ad). ok=false: iş yükü yok (static pod, sahipsiz, bilinmeyen pod).

func ServiceID 

func ServiceID(name string) string

func SnapshotQueries 

func SnapshotQueries(nsMatcher string) map[string]string

SnapshotQueries — seri adı → PromQL. Her sorgu seçici taşır (filtresiz seri taraması YOK); nsMatcher `,namespace=~"…"` biçiminde (thanos. nsMatcher çıktısı) ya da boş. kube_node_info namespace etiketi taşımaz.

func SpanSeenToEntities 

func SpanSeenToEntities(cid string, rows []SeenRow, known map[string]Entity) ([]Entity, []Relation)

SpanSeenToEntities — bir cluster'ın span satırları → ek varlık/ilişki. known: Thanos'un bu tick ürettiği varlıklar (pod çakışmasında kazanır).

func WorkloadID 

func WorkloadID(cid, ns, kind, name string) string

Types

type CHSeen 

type CHSeen interface {
	EntitySeenRecent(ctx context.Context, since time.Time) ([]SeenRow, error)
	EntitySeenRecentFor(ctx context.Context, since time.Time, clusterValue string) ([]SeenRow, error)
}

CHSeen — chstore.EntitySeenRecent (yapısal tipleme).

type CHStore 

type CHStore interface {
	EntityOpenLifetimes(ctx context.Context, cid string) (map[string]Lifetime, error)
	EntityApply(ctx context.Context, cid string, rows []EntityRow, rels []RelationRow) error
	EntityRecordRun(ctx context.Context, run Run) error
	EntityIDsExisting(ctx context.Context, cid string, ids []string) (map[string]bool, error)
}

type Change 

type Change struct {
	Open    []Lifetime // yeni ömürler (valid_from = now)
	Close   []Lifetime // kapanan ömürler (valid_to = eski last_seen)
	Refresh []Lifetime // last_seen tazelenen açık ömürler
}

Change — bir tick'in yazım kararı.

func DiffLifetimes 

func DiffLifetimes(now time.Time, prev map[string]Lifetime, seen map[string]Entity, podGap time.Duration, reachable bool) Change

DiffLifetimes — prev: id → AÇIK ömür; seen: id → bu tick görülen varlık; reachable: cluster'a bu tick başarıyla ulaşıldı mı.

type ClusterRef 

type ClusterRef struct {
	ID               string
	Name             string
	NamespaceFilter  string // thanos.nsMatcher çıktısı DEĞİL, ham regex
	SpanClusterValue string // span `cluster` kolonundaki birincil değer (boş = Name)
	// SpanClusterValues — v0.10.139: tüm değerler (teklik Settings'te).
	SpanClusterValues []string
}

ClusterRef — Remote Cluster kaydının syncer'a gereken kısmı.

type ContainerInfo 

type ContainerInfo struct{ Namespace, Pod, Container, Image string }

type Entity 

type Entity struct {
	Type      string
	ClusterID string
	ID        string
	Namespace string
	Name      string
	UID       string
	ParentID  string
	Labels    map[string]string
	Source    string
}

Entity — entities satırının yazım-öncesi hâli (ömür alanları diff'te).

type EntityRow 

type EntityRow struct {
	Type, ClusterID, ID, Namespace, Name, UID, ParentID string
	ValidFrom, ValidTo, FirstSeen, LastSeen             time.Time
	LabelKeys, LabelValues                              []string
	Source                                              string
	Stale                                               bool
}

EntityRow / RelationRow — chstore'a giden tam satırlar.

func RowsForChange 

func RowsForChange(cid string, ch Change, cur, prev map[string]Entity) []EntityRow

RowsForChange — ömür değişikliği → tam satırlar (invariant #4: her satır TÜM alanları taşır; kapanış satırı önceki anlık görüntünün alanlarıyla).

type JobOwner 

type JobOwner struct{ Namespace, Job, OwnerKind, OwnerName string }

type Lifetime 

type Lifetime struct {
	ID        string
	UID       string
	ValidFrom time.Time
	ValidTo   time.Time // sıfır = açık
	LastSeen  time.Time
}

Lifetime — açık ya da kapanmış bir ömür.

type NodeInfo 

type NodeInfo struct {
	Node, InternalIP, KernelVersion, OSImage, SystemUUID string
}

Thanos etiket setleri (etiket adları = KSM'nin kendi adları).

type Observability 

type Observability struct {
	Ticks            int64
	ClustersOK       int64
	ClustersFailed   int64
	EntitiesWritten  int64
	RelationsWritten int64
	LastTickMs       int64
	LastTickAt       time.Time
}

Observability — /api/admin/entities/sync + SystemStats.

type OwnerIndex 

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

OwnerIndex — owner zinciri arama tabloları (namespace-kapsamlı).

func IndexOwners 

func IndexOwners(s Snapshot) OwnerIndex

IndexOwners — anlık görüntüden arama tabloları.

type PodInfo 

type PodInfo struct {
	Namespace, Pod, UID, Node, IP string
	CreatedByKind, CreatedByName  string
}

type PodOwner 

type PodOwner struct{ Namespace, Pod, OwnerKind, OwnerName string }

type RSOwner 

type RSOwner struct{ Namespace, ReplicaSet, OwnerKind, OwnerName string }

type Ref 

type Ref struct {
	Type      string
	ClusterID string
	Namespace string
	Kind      string // workload türü (Deployment/StatefulSet/…)
	Pod       string // container için sahibi
	Name      string
}

Ref — çözülmüş entity_id.

func ParseID 

func ParseID(id string) (Ref, bool)

ParseID — "<önek>:<cid>/<…>" → Ref. Bilinmeyen önek / eksik bileşen → ok=false. Fazla '/' SON bileşende kalır (ad içinde '/' olmaz ama çözümleyici kırılmaz).

func (Ref) String 

func (r Ref) String() string

String — gidiş-dönüş.

type Relation 

type Relation struct {
	Type      string
	ClusterID string
	ParentID  string
	ChildID   string
	Source    string
}

Relation — entity_relations satırı (ömür alanları diff'te).

type RelationRow 

type RelationRow struct {
	Type, ClusterID, ParentID, ChildID string
	ValidFrom, ValidTo, LastSeen       time.Time
	Source                             string
}

type Resolved 

type Resolved struct {
	Enabled          bool
	SyncInterval     time.Duration
	PodGap           time.Duration
	StaleAfter       time.Duration
	ParallelClusters int
	BackfillUntil    time.Time // sıfır = yok
	BackfillValue    string
}

Resolved — kelepçelenmiş, çözülmüş vidalar.

type Run 

type Run struct {
	ClusterID, Status string
	StartedAt         time.Time
	FinishedAt        time.Time
	EntitiesWritten   int
	RelationsWritten  int
	Closed            int
	UnmappedKeys      []string
	UnmappedCounts    []uint32
	ThanosMs, CHMs    int
	Error             string
}

Run — entity_sync_runs satırı.

type Sample 

type Sample struct {
	Labels map[string]string
	Value  float64
}

Sample — bir anlık-sorgu satırı (thanos.Sample'ın paket-içi aynası; thanos paketine bağımlılık taşımamak için kopya).

type SampleSets 

type SampleSets struct {
	NodeInfo, PodInfo, PodOwner, RSOwner, JobOwner, ContainerInfo []Sample
}

SampleSets — altı serinin yanıtları (kısmi olabilir).

type SeenReader 

type SeenReader interface {
	RecentSeen(ctx context.Context, since time.Time) ([]SeenRow, error)
	// RecentSeenFor — v0.10.141: yalnız bir span cluster değerinin satırları
	// (backfill; kesim tavanı o değere uygulanır).
	RecentSeenFor(ctx context.Context, since time.Time, clusterValue string) ([]SeenRow, error)
}

SeenReader — chstore.EntitySeenRecent adaptörü.

func SeenFromCH 

func SeenFromCH(ch CHSeen) SeenReader

type SeenRow 

type SeenRow struct {
	ClusterValue, Namespace, Pod, Node, Service string
	Spans                                       int
	FirstSeen, LastSeen                         time.Time
}

SeenRow — entity_seen_5m'den bir (cluster, ns, pod, servis) satırı.

func SplitBackfillRows added in v0.10.141 

func SplitBackfillRows(rows []SeenRow, value string, liveCut time.Time) (live, dead []SeenRow)

SplitBackfillRows — saf: değere süz, canlı/ölü ayır. Karar POD başına: aynı pod'un bir satırı (servis) canlıysa TÜM satırları canlıdır — satır başına karar, canlı pod'a eski bir servis satırı yüzünden kapalı ömür yazdırırdı.

type Settings 

type Settings struct {
	Enabled          bool   `json:"enabled"`
	SyncInterval     string `json:"syncInterval,omitempty"`
	PodGap           string `json:"podGap,omitempty"`
	StaleAfter       string `json:"staleAfter,omitempty"`
	ParallelClusters int    `json:"parallelClusters,omitempty"`
	// UpdatedAt — v0.10.129: yazım damgası (UnixNano). LoadPersisted daha
	// eski bir blobu bellekteki yeninin üstüne yazmaz — PUT'un kendi reload
	// sinyali replike olmamış eski satırı okuyup değeri geri alıyordu.
	UpdatedAt int64 `json:"updatedAt,omitempty"`
	// BackfillUntil — v0.10.141 (otomatik eşleme brief'i): bu ana (ms) kadar
	// span geçişi 24 saatlik pencereyle koşar — bir span cluster değeri bir
	// kayda ATANDIĞINDA geriye dönük pod/servis entity'leri üretilsin.
	// Rol-güvenli: blob üzerinden yayılır, lider Tick'i okur.
	BackfillUntil int64 `json:"backfillUntil,omitempty"`
	// BackfillValue — geriye dönük geçiş YALNIZ bu span cluster değeri için
	// (inceleme: küresel 24 s pencere her cluster'ın ölü pod'larını canlı
	// olarak yeniden açıyordu). Boş = backfill yok.
	BackfillValue string `json:"backfillValue,omitempty"`
}

Settings — kayıtlı blob.

func DefaultSettings 

func DefaultSettings() Settings

func (Settings) Resolved 

func (s Settings) Resolved() Resolved

Resolved — kelepçeler: syncInterval 15s..1h, podGap 1m..24h, staleAfter 1h..30d, parallelClusters 1..16.

type SettingsService 

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

SettingsService — bellekteki ayar + kalıcılık.

func NewSettingsService 

func NewSettingsService() *SettingsService

func (*SettingsService) Configure 

func (s *SettingsService) Configure(cfg Settings)

func (*SettingsService) Current 

func (s *SettingsService) Current() Settings

func (*SettingsService) LoadPersisted 

func (s *SettingsService) LoadPersisted(ctx context.Context, store settingsStore) error

LoadPersisted — boot: blob yoksa varsayılan (kapalı).

func (*SettingsService) Resolved 

func (s *SettingsService) Resolved() Resolved

func (*SettingsService) SavePersisted 

func (s *SettingsService) SavePersisted(ctx context.Context, store settingsStore, cfg Settings) error

SavePersisted — admin PUT: tam blob + canlı swap.

func (*SettingsService) StartConfigRefresh 

func (s *SettingsService) StartConfigRefresh(ctx context.Context, store settingsStore, interval time.Duration)

StartConfigRefresh — çok-pod blob eşitlemesi (30 s).

type Snapshot 

type Snapshot struct {
	Nodes      []NodeInfo
	Pods       []PodInfo
	PodOwners  []PodOwner
	RSOwners   []RSOwner
	JobOwners  []JobOwner
	Containers []ContainerInfo
}

Snapshot — bir cluster'ın tek tick'lik görüntüsü.

func SnapshotFromSamples 

func SnapshotFromSamples(ss SampleSets) Snapshot

SnapshotFromSamples — etiket setleri → Snapshot; namespace'siz/adsız satır düşer, tekrarlar tekilleşir (ilk görülen kazanır).

type Source 

type Source interface {
	Clusters() []ClusterRef
	Fetch(ctx context.Context, c ClusterRef, queries map[string]string) (SampleSets, error)
}

Source — Thanos kapısı (thanos.Service adaptörü; testte sahte).

type Store 

type Store interface {
	OpenLifetimes(ctx context.Context, cid string) (map[string]Lifetime, error)
	Apply(ctx context.Context, cid string, rows []EntityRow, rels []RelationRow) error
	RecordRun(ctx context.Context, run Run) error
	// Existing — v0.10.141: bu id'lerden HERHANGİ bir ömrü olanlar (backfill
	// yalnız hiç kaydı olmayan ölü pod'ları yazar; yeniden koşum idempotent).
	Existing(ctx context.Context, cid string, ids []string) (map[string]bool, error)
}

Store — CH kapısı (chstore adaptörü; testte bellek).

func StoreFromCH 

func StoreFromCH(ch CHStore) Store

type Syncer 

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

Syncer — durumlu işçi.

func NewSyncer 

func NewSyncer(src Source, store Store, settings func() Resolved) *Syncer

func (*Syncer) Observability 

func (s *Syncer) Observability() Observability

func (*Syncer) Run 

func (s *Syncer) Run(ctx context.Context, isLeader func() bool)

Run — lider olduğu sürece periyodik tick (çağıran IsLeader ile sarar).

func (*Syncer) SetLeaderCheck added in v0.10.141 

func (s *Syncer) SetLeaderCheck(f func() bool)

SetLeaderCheck — main.go LeaderHolder.IsLeader'ı bağlar.

func (*Syncer) SetSeenReader 

func (s *Syncer) SetSeenReader(r SeenReader)

SetSeenReader — span-türevli geçiş kaynağı (chstore.EntitySeenRecent).

func (*Syncer) Tick 

func (s *Syncer) Tick(ctx context.Context) bool

Tick — bir senkronizasyon turu (bayrak kapalıysa no-op). Tick — bir senkronizasyon turu; aynı pod'da örtüşen tur koşmaz (false döner). Tüm çağıranlar (Run, SetOnAcquire, Run now, TryTick) bu kapıdan geçer — inceleme: kapı yalnız TryTick'teyken API tick'i periyodik tick'le çakışıp aynı ömrü iki kez açabiliyordu.

func (*Syncer) TryTick added in v0.10.141 

func (s *Syncer) TryTick(ctx context.Context) (ran bool, reason string)

TryTick — API tarafından tetiklenen anlık tick: lider değilse koşmaz (inceleme: lider olmayan pod'un tick'i liderin tick'iyle yarışıp aynı ömrü iki kez açıyordu). Örtüşme koruması Tick'in kendisinde — periyodik Run, SetOnAcquire ve "Run now" ucu da aynı kapıdan geçer.

type ThanosSource 

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

func NewThanosSource 

func NewThanosSource(svc *thanos.Service) *ThanosSource

func (*ThanosSource) Clusters 

func (t *ThanosSource) Clusters() []ClusterRef

func (*ThanosSource) Fetch 

func (t *ThanosSource) Fetch(ctx context.Context, c ClusterRef, queries map[string]string) (SampleSets, error)

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.