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 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 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 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)
    ...
}

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)
    ...
}

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 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.