otellog

func Activity ¶

func Activity(ctx goravelhttp.Context, m golib.Map)

Activity emits an HTTP activity log via OTEL SDK only (does not write to runtime.log). Use in middleware after calling Next() to capture full request/response with real trace.id.

func AddFields ¶ added in v1.1.12

func AddFields(ctx context.Context, fields ...golib.Map) context.Context

AddFields menambahkan field bisnis (mis. refno, order_id, pn_maker) ke context:

• disimpan sebagai request fields, sehingga otomatis ikut ke setiap log otellog.Runtime / RuntimeCtx / Activity yang memakai context ini
• dipasang sebagai attribute di span aktif pada ctx, supaya bisa dicari di Jaeger/APM

Nilai di-mask lewat MaskValue (key sensitif jadi "***"). Nilai nil atau string kosong dilewati. Field yang sudah ada di context ditimpa bila key-nya sama. Pakai context hasil kembalian untuk pemanggilan berikutnya:

ctx = otellog.AddFields(ctx, log.Map{"refno": req.Refno, "order_id": id})

func CallerName ¶ added in v1.1.11

func CallerName(skip int) string

CallerName mengembalikan nama "<Struct>.<Func>" fungsi pada kedalaman stack skip (0 = fungsi yang memanggil CallerName, 1 = pemanggilnya, dst.). Untuk helper/wrapper span sendiri:

func startSpan(ctx goravelhttp.Context) (context.Context, trace.Span) {
    return otel.Tracer(...).Start(otellog.GoContext(ctx), otellog.CallerName(1))
}

func ContextWithTraceParent ¶ added in v1.1.13

func ContextWithTraceParent(ctx context.Context, traceparent string) context.Context

ContextWithTraceParent mengembalikan ctx yang membawa span context remote dari traceparent, sehingga span yang dibuat dari ctx ini (mis. otellog.Trace di Handle job) menjadi CHILD dari span pengirim dan berada di trace.id yang sama. traceparent kosong/invalid → ctx apa adanya (proses memulai trace baru).

ctx = otellog.ContextWithTraceParent(ctx, j.TraceParent)
ctx, done := otellog.Trace(ctx)

func DBSystem ¶ added in v1.1.15

func DBSystem() string

DBSystem mengembalikan nilai db.system yang dipakai span database: override dari SetDBSystem bila ada, jika tidak diturunkan dari env DB_CONNECTION (nama koneksi Goravel). Kosong bila tidak bisa ditentukan — attribute tidak dipasang.

func EnrichMap ¶

func EnrichMap(ctx goravelhttp.Context, m map[string]any) map[string]any

func Flush ¶ added in v1.1.8

func Flush(ctx context.Context) error

func GoContext ¶

func GoContext(ctx goravelhttp.Context) context.Context

GoContext mengambil enriched Go context (dengan OTEL span) dari goravelhttp.Context. Gunakan di controller saat memanggil usecase agar trace menyambung. Fallback ke ctx.Context() jika OTEL belum di-set.

func IsSensitiveKey ¶ added in v1.1.10

func IsSensitiveKey(key string) bool

IsSensitiveKey melaporkan apakah nilai dengan key ini harus di-mask.

func MaskJSON ¶ added in v1.1.10

func MaskJSON(body []byte, maxBytes int) string

MaskJSON mem-parse body JSON, me-mask field sensitif, lalu memotong hasilnya ke maxBytes (0 = tanpa batas). Body non-JSON dikembalikan apa adanya (terpotong), karena tidak bisa diidentifikasi field-nya.

func MaskValue ¶ added in v1.1.10

func MaskValue(v any) any

MaskValue mengembalikan salinan v dengan semua nilai ber-key sensitif diganti MaskedValue, rekursif ke map dan slice. Nilai asli tidak dimodifikasi.

func RecordSpanError ¶ added in v1.1.18

func RecordSpanError(span trace.Span, err error)

RecordSpanError mencatat err pada span yang dibuat manual (mis. span controller dari tracer.Start) dengan aturan yang sama seperti TraceFunc: error bisnis stderr dan gorm.ErrRecordNotFound dilewati, error sistem dicatat (RecordError + status Error). Pengganti span.RecordError(err):

if err != nil {
    otellog.RecordSpanError(span, err)
    return RespondError(ctx, err)
}

func RegisterSensitiveKeys ¶ added in v1.1.10

func RegisterSensitiveKeys(keys ...string)

RegisterSensitiveKeys menambah key yang harus di-mask (pencocokan exact, setelah normalisasi). Panggil sekali saat boot service, mis. untuk field domain khusus: otellog.RegisterSensitiveKeys("namaIbuKandung", "noHp").

func RegisterTypeName ¶ added in v1.1.11

func RegisterTypeName(goName, display string)

RegisterTypeName mengatur nama tampil tipe receiver untuk Trace, TraceDBAuto, CallerName, dan otelmetric.Record — untuk akronim yang tidak bisa ditebak:

func init() { otellog.RegisterTypeName("glDebitUsecase", "GLDebitUsecase") }

func ServerMiddleware ¶ added in v1.1.10

func ServerMiddleware(opts ...MiddlewareOption) goravelhttp.Middleware

ServerMiddleware menggantikan pasangan middleware OtelMetrics + OtelActivity dan startSpan di controller. Untuk setiap request ia:

1. Extract traceparent dari header (bisa dimatikan, lihat WithTrustIncomingTrace)
2. Membuat span SERVER dan menyimpannya ke context ("otelSpan", "otelContext"), sehingga otellog.Runtime / otellog.GoContext di controller langsung tersambung
3. Mencatat HTTP metrics (total, durasi, active)
4. Setelah handler selesai: set http.status_code, status Error untuk 5xx/panic, lalu kirim activity log dengan body yang sudah di-mask & dipotong

Pasang PALING AWAL, sebelum middleware bisnis (auth, PreRequest, dll.), supaya request yang ditolak middleware tersebut tetap punya trace:

facades.Route().Middleware(otellog.ServerMiddleware(), middleware.PreRequest).Group(...)

Di controller, nama span bisa diperjelas:

trace.SpanFromContext(otellog.GoContext(ctx)).SetName("OrderController.Create")

func SetDBAttrs ¶

func SetDBAttrs(ctx context.Context, statement string)

SetDBAttrs menyimpan db.statement ke span aktif di ctx. Gunakan untuk INSERT, UPDATE, DELETE, atau single SELECT.

ctx, done := otellog.TraceDB(ctx, "mst_rekanan", "UPDATE")
defer done(&err)
otellog.SetDBAttrs(ctx, query.ToRawSql().Update("status", val))

func SetDBPaginateAttrs ¶

func SetDBPaginateAttrs(ctx context.Context, statement string, page, limit int, rowsReturned int64)

SetDBPaginateAttrs menyimpan db.statement + pagination + rows_returned ke span aktif di ctx. Panggil setelah Paginate selesai dengan stmt yang diambil sebelum eksekusi.

ctx, done := otellog.TraceDB(ctx, "mst_rekanan", "SELECT")
defer done(&err)
stmt := query.ToRawSql().Find(&list)
_ = query.Paginate(page, limit, &list, &total)
otellog.SetDBPaginateAttrs(ctx, stmt, page, limit, total)

func SetDBSystem ¶ added in v1.1.15

func SetDBSystem(system string)

SetDBSystem menetapkan nilai attribute db.system untuk semua span TraceDB / TraceDBAuto (mis. "postgresql", "mysql"). Tanpa pemanggilan ini, nilai diturunkan dari env DB_CONNECTION (lihat DBSystem). String kosong mengembalikan ke perilaku env.

db.system dipakai Kibana APM untuk mengisi span.subtype, sehingga span database tampil dengan nama database ("postgresql") di legend dan filter, bukan "db" generik.

func Trace ¶ added in v1.1.11

func Trace(ctx context.Context, fields ...golib.Map) (context.Context, func(*error))

Trace sama dengan TraceFunc, tetapi nama span diambil otomatis dari fungsi pemanggil dengan format "<Struct>.<Func>" (atau "<pkg>.<Func>" untuk fungsi tanpa receiver). Contoh: method (*orderNotarisUsecase).CreateOrderNotaris → "OrderNotarisUsecase.CreateOrderNotaris". Closure (.func1) diabaikan sehingga nama tetap nama method yang membungkusnya.

func (u *orderNotarisUsecase) CreateOrderNotaris(ctx context.Context, req Req) (res Res, err error) {
    ctx, done := otellog.Trace(ctx)
    defer done(&err)
    defer otelmetric.Record(ctx)()
    ...
}

Harus dipanggil LANGSUNG dari fungsi yang ingin di-trace. Untuk wrapper (mis. helper startSpan di controller) pakai TraceFunc(ctx, CallerName(1)). Akronim pada nama struct (glDebitUsecase → GLDebitUsecase) diatur via RegisterTypeName.

func TraceDB ¶

func TraceDB(ctx context.Context, table, operation string) (context.Context, func(*error))

TraceDB membuat DB span (kind CLIENT) bernama "db.<table>.<operation>". Untuk nama otomatis "<Repository>.<Func>" pakai TraceDBAuto. Gunakan dengan named return error dan defer:

func (r *Repo) GetList(ctx context.Context, ...) (result []Model, err error) {
    ctx, done := otellog.TraceDB(ctx, "nama_tabel", "SELECT")
    defer done(&err)
    ...
}

gorm.ErrRecordNotFound (termasuk yang dibungkus %w) tidak dicatat sebagai error; span diberi attribute db.result="not_found".

func TraceDBAuto ¶ added in v1.1.11

func TraceDBAuto(ctx context.Context, table, operation string) (context.Context, func(*error))

TraceDBAuto sama dengan TraceDB, tetapi nama span diambil otomatis dari fungsi pemanggil, mis. (*orderNotarisRepository).GetListOrderNotaris → "OrderNotarisRepository.GetListOrderNotaris". Tabel & operasi tetap tersimpan sebagai attribute db.table / db.operation.

ctx, done := otellog.TraceDBAuto(ctx, constants.TableOrderNotaris, "SELECT")
defer done(&err)

func TraceFunc ¶

func TraceFunc(ctx context.Context, name string, fields ...golib.Map) (context.Context, func(*error))

TraceFunc membuat span + log error otomatis untuk satu fungsi, dengan nama span eksplisit. Untuk nama otomatis "<Struct>.<Func>" pakai Trace. Gunakan dengan named return error dan defer:

func (u *Usecase) MyFunc(ctx context.Context, req Req) (resp Resp, err error) {
    ctx, done := otellog.TraceFunc(ctx, "Usecase.MyFunc", log.Map{"key": val})
    defer done(&err)
    ...
}

Error bisnis stderr (kode 01, 02, 03, 05, X0, X1) tidak dicatat sebagai error (tanpa RecordError, status Error, dan log Error); error sistem tetap dicatat.

fields opsional: dipasang sebagai attribute span dan digabung ke setiap log yang memakai ctx hasil kembalian (termasuk log error dari done), mis. log.Map{"refno": req.Refno}. Nilai sensitif di-mask, nilai kosong dilewati.

func TraceParent ¶ added in v1.1.13

func TraceParent(ctx context.Context) string

TraceParent mengambil header W3C traceparent dari span aktif di ctx, untuk diteruskan ke proses asinkron (argumen job queue, pesan Kafka, dll.). String kosong bila ctx tidak membawa span (mis. OTEL mati) — aman diteruskan apa adanya.

{Type: "string", Value: otellog.TraceParent(ctx)}

func TraceRedis ¶ added in v1.1.20

func TraceRedis(ctx context.Context, operation string) (context.Context, func(*error))

TraceRedis membuat span Redis (kind CLIENT, db.system="redis") bernama "redis.<operation>". Untuk nama otomatis "<Repository>.<Func>" pakai TraceRedisAuto. operation adalah perintah Redis, mis. "GET", "SET", "DEL". Gunakan dengan named return error dan defer:

func (r *sessionRepo) GetSession(ctx context.Context, ...) (res *Session, err error) {
    ctx, done := otellog.TraceRedis(ctx, "GET")
    defer done(&err)
    ...
}

redis.Nil (key tidak ada) tidak dicatat sebagai error; span diberi attribute db.result="not_found". Error Redis lain (koneksi, timeout) tetap dicatat.

func TraceRedisAuto ¶ added in v1.1.20

func TraceRedisAuto(ctx context.Context, operation string) (context.Context, func(*error))

TraceRedisAuto sama dengan TraceRedis, tetapi nama span diambil otomatis dari fungsi pemanggil, mis. (*sessionRepo).GetSession → "SessionRepo.GetSession". Perintah Redis tersimpan sebagai attribute db.operation.

ctx, done := otellog.TraceRedisAuto(ctx, "GET")
defer done(&err)

func WithRequestFields ¶

func WithRequestFields(ctx context.Context, fields golib.Map) context.Context

WithRequestFields menyimpan field request ke dalam Go context. Field ini otomatis di-merge ke setiap log call yang menggunakan context tersebut, tanpa perlu ditulis ulang di setiap Info/Warning/Error.

Field yang sudah ada di context digabung (key yang sama ditimpa oleh fields); map milik context sebelumnya tidak dimodifikasi. Untuk field bisnis yang juga perlu muncul sebagai attribute span, pakai AddFields.