reqid

Documentation

Overview

Package reqid parses the operator's STRUCTURED request identifier and turns it into a bounded log-search window (v0.9.1142).

Operatör isteği: kurumsal sistemlerde her istek TEK bir string ile izleniyor ve o string sabit yapıda — içinde işlemin TARİHİ ve SAATİ milisaniyesine kadar yazılı. Sohbete böyle bir kimlik yapıştırıldığında aramanın filo geneline yayılması gereksiz: kimliğin kendisi pencereyi söylüyor. Zincir şu: kimlik → gömülü zaman → o pencerede log araması → eşleşen kaydın trace_id'si → trace anlatısı.

GÜVENLİK: bu dosya (ve testleri) HİÇBİR gerçek kurum/müşteri değeri taşımaz. Örnekler tamamen sentetik ("ABCD001", müşteri "0000000042") — depo bir müşteri kimliği ya da kurum adı taşımaz (correlation_link.go ile aynı doktrin).

NEDEN AYRI PAKET: iki tüketici var ve ikisi ayrı paketlerde — internal/api (sohbet hızlı yolu + log köprüsü çipi) ve internal/mcptools (find_trace_by_request_id). api → mcptools import'u zaten var, tersi yok; ortak yeri ikisinin de import edebildiği bu saf paket. İkinci bir tespit/parse kopyası YOK.

Index

• Constants
• func FindLooseToken(text string) (string, bool)
• func FindToken(text string) (string, bool)
• func FmtLocal(t time.Time) string
• func Location(name string) *time.Location
• func LocationFrom(ctx context.Context, r SettingReader) *time.Location
• type ID
  • func Find(text string, loc *time.Location) (ID, bool)
  • func Parse(token string, loc *time.Location) (ID, bool)
  • func (id ID) Window() (from, to time.Time)
• type Resolution
  • func Resolve(ctx context.Context, ls logstore.Store, id ID) (Resolution, error)
• type SettingReader
• type Settings
  • func DecodeSettings(b []byte) Settings

Constants

const (
	// MinSaltLen — kuyruktaki en az rakam sayısı. 44 sabit + 3 = 47.
	//
	// Neden bir taban var: 44 karakterlik "salt'sız" bir dizi bu biçimde
	// gözlenmedi ve tabansız kabul, rastgele bir 44-hane sayının kimlik
	// sanılmasına kapı açardı.
	MinSaltLen = 3
	// MaxSaltLen — kuyruğun üst sınırı. Kimliğin kendisi bir uzunluk
	// beyanı taşımıyor, yani teorik olarak 200 haneli bir sayı da
	// "kimlik gibi" görünür. Sınır bir SEZGİ ve bilinçli: ofset 27'de
	// tesadüfen geçerli bir tarih taşıyan uzun bir rakam bloğu
	// (dosya boyutu, tutar, epoch dizisi) kimlik sanılmasın.
	MaxSaltLen = 20
	// MinLen / MaxLen — türetilmiş sınırlar.
	MinLen = offSalt + MinSaltLen
	MaxLen = offSalt + MaxSaltLen
)

const DefaultTZ = "Europe/Istanbul"

DefaultTZ — gömülü zamanın YEREL saat dilimi.

Kimlik UTC taşımıyor: kurumun kendi saatiyle damgalanıyor. Bu, ±10 dakikalık bir pencerede HAYATİ bir ayrım — üç saatlik bir tz hatası pencereyi tamamen ıskalar ve özellik "hiç bulamıyor" diye görünür.

const SearchLimit = 20

SearchLimit — pencere içinde okunacak log satırı tavanı.

20: aynı kimlik birden çok satır loglar (giriş/çıkış/hata) ve trace bağlamı taşıyan satır bunların herhangi biri olabilir. Daha büyük bir tavan tek ES sorgusunun maliyetini boşuna büyütürdü — biz satırları LİSTELEMİYORUZ, tek bir trace_id çıkarıyoruz.

const SearchPad = 10 * time.Minute

SearchPad — kimliğin damgası etrafındaki arama yarı-genişliği.

±10dk: kayıt zamanı ile log satırının damgası arasındaki fark (uygulama içi gecikme, ingest lag, hafif saat kayması) bu bandın içinde. Tz belirsizliğini pencereyi GENİŞLETEREK çözmek yanlış cevap olurdu — locu doğru kullanıp pencereyi dar tutuyoruz, çünkü pencere log arama maliyetinin TEK sınırı (ES 10B doc/gün).

const SettingKey = "reqid.timezone"

SettingKey — system_settings anahtarı.

Functions

func FindLooseToken

func FindLooseToken(text string) (string, bool)

FindLooseToken — v0.9.1144. Kimliğe BENZEYEN ama şablona (henüz) uymayan token: uzunluk aralığı tutuyor, rakam ağırlığı tutuyor, ama Parse geçmiyor (sürpriz bir segment sınıfı, bozuk kopyalama, gelecekte değişen şablon). Amaç yönlendirme dürüstlüğü: böyle bir token taşıyan mesaj doküman-QA katmanına DÜŞMEMELİ — guided "biçim çözülemedi" der ve köprü linkini yine üretir. Bu fonksiyon çözümleme İDDİA ETMEZ; çağıran Parse'ın düştüğünü bilerek kullanır.

func FindToken

func FindToken(text string) (string, bool)

FindToken — metindeki İLK yapılandırılmış kimlik token'ı (orijinal harf kasası korunur). tz'siz: segment/takvim makullüğü saat dilimi gerektirmiyor, dolayısıyla saf router (routeGuidedIntent) ayar okumadan karar verebilir.

ANAHTAR KELİME ÇAPASI YOK ve bu bilinçli bir SAPMA: request_id_links.go genel bir "uzun token yakala" regex'ini yanlış pozitif kusacağı için reddediyor (trace id'ler, sürüm damgaları, pod adları). Burada çapa gerekmiyor çünkü şeklin KENDİSİ doğrulanıyor — 47-64 karakterlik, sabit ofsetlerinde geçerli bir takvim tarihi + saat taşıyan bir dizi tesadüfen oluşmaz.

Tarama MAKSİMAL alnum blokları üzerinde: kimliğin bir ucundan kırpılmış alt dizi eşleşmesi olmuyor ("…086ve" biçiminde yapışık bir kuyruk kabul EDİLMEZ), 100 haneli bir rakam bloğu da kimlik sanılmıyor.

func FmtLocal

func FmtLocal(t time.Time) string

FmtLocal — kimliğin saat diliminde okunabilir damga. 24 saat konvansiyonu (v0.9.879) sunucu tarafında da geçerli: AM/PM yok.

func Location

func Location(name string) *time.Location

Location — ayar adından saat dilimi. Boş ad = DefaultTZ; yüklenemeyen ad da DefaultTZ'ye düşer (yanlış bir ad yüzünden UTC'ye düşmek sessiz ıska demek). tzdata hiç yoksa sabit +03:00.

func LocationFrom

func LocationFrom(ctx context.Context, r SettingReader) *time.Location

LocationFrom — ayardan saat dilimi. Okuma HER çağrıda yapılıyor (correlationLinkTemplates emsali): çağrı sıklığı düşük, buna karşılık boot'ta yüklenen bir kopya operatör tz'yi değiştirdiğinde yeniden başlatmaya kadar bayat kalırdı. Reader nil → varsayılan.

Types

type ID

type ID struct {
	Raw        string
	FuncCode   string
	Channel    string
	SubCode    string
	CustomerNo string
	Salt       string
	// TS — gömülü tarih+saat, Location'da (yerel banka saati).
	TS time.Time
}

ID — çözümlenmiş kimlik. Raw, aramada kullanılan ORİJİNAL token'dır (büyük/küçük harf korunur: ES keyword alanlarında eşleşme harfe duyarlı olabilir).

func Find

func Find(text string, loc *time.Location) (ID, bool)

Find — FindToken + Parse (loc ile). Metinden doğrudan çözümlenmiş kimlik isteyen çağıranlar (MCP tool'u, köprü çipi) bunu kullanır.

func Parse

func Parse(token string, loc *time.Location) (ID, bool)

Parse — token → ID. SAF, tablo testli.

ok=false her zaman "bu bir kimlik DEĞİL" demek: uzunluk, segment karakter sınıfı ya da takvim/saat makullüğü tutmuyor. Çağıran bunu ŞEKİL hatası olarak raporlar (bulunamama ile karıştırmadan).

func (ID) Window

func (id ID) Window() (from, to time.Time)

Window — arama penceresi (TS ± SearchPad).

type Resolution

type Resolution struct {
	ID ID
	// TraceID — bulunan trace; "" = bulunamadı (HATA DEĞİL).
	TraceID string
	// SpanID — trace bağlamını taşıyan log satırının span'i (varsa);
	// waterfall içinde işaret etmeye yarar.
	SpanID string
	// Service — o log satırının servisi ("" = kayıt taşımıyor).
	Service string
	// LogTS — eşleşen log satırının damgası (unix ns, 0 = yok).
	LogTS int64
	// MatchedLogs — pencere+tavan içinde kimlikle eşleşen satır sayısı.
	MatchedLogs int
	// DistinctTraces — eşleşen satırlarda görülen FARKLI trace sayısı.
	// >1 ise cevap "tek trace" diye sunulmamalı (dürüstlük zarfı).
	DistinctTraces int
	// Partial — logstore dürüstlük zarfı: soft timeout / başarısız shard.
	// true ise satırlar gerçek cevabın ALT KÜMESİ, yani "bulunamadı"
	// kesin bir yokluk değildir.
	Partial bool
}

Resolution — çözümlemenin dürüst sonucu.

func Resolve

func Resolve(ctx context.Context, ls logstore.Store, id ID) (Resolution, error)

Resolve — tek arama, tek pencere.

ES MALİYET DİSİPLİNİ: WantCursor BİLEREK false (v0.9.286 — cursor istemeyen okuma PIT tutturmaz); tek Search çağrısı; pencere kimliğin kendisinden, yani dar.

HasTrace filtresi KULLANILMIYOR ve bu v0.9.1084'ün dersi: ES mapping'inde yapısal trace alanı yoksa `exists` hiçbir doc'la eşleşmez ve filtre SESSİZCE her şeyi eler. Burada onu kullanmak "kimlik yok" diye yanlış cevap üretirdi. Satırları filtresiz alıp trace bağlamını KENDİMİZ seçiyoruz.

type SettingReader

type SettingReader interface {
	GetSetting(ctx context.Context, key string) ([]byte, error)
}

SettingReader — ayar okuma yeteneği. chstore.Store bunu karşılıyor; arayüz olarak alınıyor ki bu saf paket chstore'a bağlanmasın.

type Settings

type Settings struct {
	// TZ — IANA saat dilimi adı ("Europe/Istanbul"). Boş = DefaultTZ.
	// Emsal: ChannelMatchRules.QuietHoursTz (chstore/settings.go).
	TZ string `json:"tz,omitempty"`
}

Settings — blob şekli. Tek alan, ama blob: ileride bir alan eklemek (ör. pencere genişliği) şema değişikliği olmadan mümkün kalsın.

func DecodeSettings

func DecodeSettings(b []byte) Settings

DecodeSettings — blob → Settings. SAF (tablo testli). Bozuk blob boş Settings, yani varsayılan tz.