Áttekintés

A telemetry önálló Go modul (github.com/gp-system/telemetry, +telemetry/logx, +telemetry/otelx, +telemetry/sentryx): a logolást, a mérést és a hibariportolást egyetlen hívás bootolja. Egy generált projektben ezt a hívást sem te írod: a server.Run és a worker.Run első dolga a telemetry.Setup. Amikor a shop main.go-ja elindul, a logolás, a trace-elés és a hibariportolás már be van kötve, mielőtt az első kérés beérkezne.

Telepítés

go get github.com/gp-system/telemetry@v0.1.0 # a kit is ezt a taget használja
go get github.com/gp-system/telemetry@latest

Egy bináris, aminek csak egy darabra van szüksége, importálhatja önmagában azt az alcsomagot: egy CLI vagy migrátor, ami OTel-trace-elést akar, de Sentryt nem, önmagában importálja a telemetry/otelx-et, és sosem linkeli be a sentry-go-t.

A telemetry facade

Három csomag birtokol egy-egy képességet, és egy negyedik komponálja őket:

A telemetry.Config pontosan az, amit a server.Config.Telemetry és a worker.Config.Telemetry mező hordoz:

type Config struct {
    Otel   otelx.Config   // OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_DEV_MODE
    Log    logx.Config    // LOG_LEVEL, LOG_STDOUT, LOG_FORMAT
    Sentry sentryx.Config // SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_TRACES, SENTRY_DEBUG
}

Prefix nélkül ágyazódik be, így az env-változók a standard neveiken töltődnek: a deployment ugyanúgy konfigurálja a service-t, mint bármely más OTel-instrumentált appot. A teljes változólista: Konfiguráció-referencia.

func Setup(ctx context.Context, cfg Config) (shutdown func(context.Context) error, err error)

A telemetry az egyetlen csomag, ami mindhárom építőkockát importálja: az otelx és a sentryx nem tud egymásról, a logx-nek pedig nincs véleménye arról, hova megy még egy logrekord. Ez nem kozmetika: egy nem-chassis bináris (egy CLI, egy migrátor), ami csak az otelx-et használja, soha nem linkeli be a sentry-go-t.

Mi történik a Setup-ban

A sorrend számít, mert a részek egymásba drótozódnak:

1. Sentry először. A sentryx.Setup fut le elsőnek: SENTRY_DSN nélkül minden hookja no-op, és minden pontosan úgy viselkedik, mintha a Sentry nem is létezne.
2. OTel, a Sentry span-exporterével. Az otelx.Setup az otelx.WithSpanExporter(sentryHandle.SpanExporter()) opcióval kapja meg a Sentry exporterét: ugyanazok a spanek egy plusz batcherrel a Sentrybe is mennek, így egy hiba a teljes request-trace-hez linkelődik.
3. Egy slog.Default(). A konzol-handler (dev módban mindig, prodban LOG_STDOUT=true esetén), az OTLP log-bridge és a Sentry capture handler a logx.Fanout-tal egyetlen handlerré áll össze, elé egy logx.LevelFilter(LOG_LEVEL, ...) kerül, és az egész lesz a processz default loggere.

Vagyis egyetlen slog.InfoContext(ctx, ...) hívás a service-edben egyszerre: olvasható konzolsor (dev), OTLP-n exportált, trace-korrelált logrekord (prod), és hiba esetén Sentry event breadcrumb-nyomvonallal.

Mit kapsz nulla konfigurációval

Egy kivétel van: ha dev módban SENTRY_DSN-t állítasz be, a kit egy Sentry-only tracer providert épít, így collector nélkül, lokálisan is teljes trace-t és hibát kapsz a Sentryben; a részletek a Sentry oldalon.

A flush a legvégén fut

A Setup visszatérési értéke egy aggregált shutdown-függvény, amit a chassis az alkalmazás-életciklus Flush lépéseként, legutolsóként futtat, a HTTP-drain és az összes WithCloser closered után. Ez a sorrend nem véletlen: a closerek maguk is bocsátanak ki telemetriát (egy pool-lezárás logja, egy cleanup közben nyitott span), és ezek csak akkor érnek célba, ha az exporterek még élnek.

A shutdown-on belül is van sorrend: előbb az OTel providerek állnak le, és a Sentry flushol legutoljára, így a providerek leállása közben keletkező eventek is kimennek.

Ha nem kell, vagy magad akarod

Mindhárom chassis-nak van kikapcsolója:

server.Run(ctx, cfg.Server, register, server.WithoutTelemetry())
worker.Run(ctx, cfg.Worker, register, worker.WithoutTelemetry())
realtime.Run(ctx, cfg.Realtime, register, realtime.WithoutTelemetry())

A WithoutTelemetry a telemetry.Setup-ot és a HTTP-oldali OTel middleware-t is kihagyja. Tesztekben ez az alapfelállás (nincs globális állapot-piszkálás), élesben pedig akkor kell, ha a processz maga konfigurálja a telemetriáját: például egy már meglévő OTel-setupba illeszkedik.

Nem-chassis processzben (CLI, cron-szerű egyszeri futás) a telemetry.Setup közvetlenül is hívható: ugyanazt a kompozíciót kapod, csak a shutdown-függvényt neked kell defer-elni. Ha a Sentry sem kell, az otelx.Setup önmagában is megáll.

Merre tovább

• Logolás: a slog kompozíció és a Monolog-formátumú dev konzol, PHP-s szemmel a leglátványosabb rész.
• OpenTelemetry: mit instrumentál a kit magától, és hogyan áll össze a shop „kövesd a rendelést" trace-e.
• Sentry: hibariportolás errs-kód szerinti issue-csoportosítással, az OTel tetején.