apmcore

func BatchSpanEmitter ¶ added in v0.7.0

func BatchSpanEmitter() func(table string, ops int, elapsed time.Duration)

BatchSpanEmitter returns a SpanEmitter compatible with gormautobatch.Config.SpanEmitter. It emits a background OTel span for each batch flush so batched writes are visible in APM even though they belong to no specific request.

func CaptureError ¶

func CaptureError(ctx context.Context, err error)

CaptureError records err on the APM transaction in ctx and sends it to the agent. Safe to call with nil err (no-op) or with ctx that has no active transaction (drops the event).

Use this from handlers that map errors inline (return ctx.Status(...). JSON(...)) so the error still appears in Kibana → APM → Errors with the request's trace.id attached.

func InjectFastHTTPTraceContext ¶ added in v0.5.0

func InjectFastHTTPTraceContext(ctx context.Context, req *fasthttp.Request)

InjectFastHTTPTraceContext writes the W3C traceparent header on req from the currently active APM span (or transaction) in ctx. Use this when you must hand the *fasthttp.Request off to a library you do not control — so you can't wrap the call site with TraceFastHTTPCall.

No-op when ctx has neither span nor transaction.

func InstrumentCacher ¶ added in v0.8.0

func InstrumentCacher(inner caches.Cacher) caches.Cacher

InstrumentCacher wraps inner with OTel spans for every cache operation. Spans are emitted on the tracer "gormcache" and capture hit/miss for Get, tag counts for Store, and affected tables for Invalidate. Errors are recorded and the span status is set to Error so that APM tools can surface them via error-rate metrics.

func InstrumentRedis ¶

func InstrumentRedis(client redis.UniversalClient) error

InstrumentRedis attaches the redisotel tracing + metrics hooks to client. Spans/metrics flow through the OTel global providers configured by SetupOTelSDK and end up in the APM agent's transport.

Pass any redis.UniversalClient (Client, ClusterClient, Ring, etc.).

func InstrumentRueidis ¶ added in v0.7.0

func InstrumentRueidis(client rueidis.Client) rueidis.Client

InstrumentRueidis wraps client with OpenTelemetry tracing and metrics via rueidisotel and returns the instrumented client. It mirrors InstrumentRedis for the rueidis client used by gsrueidis.

Pass the client returned by rueidis.NewClient — the returned client is a drop-in replacement that emits OTel spans and metrics through the global providers configured by SetupOTelSDK.

Example:

client, err := rueidis.NewClient(rueidis.ClientOption{...})
if err != nil { ... }
client = apmcore.InstrumentRueidis(client)

func LogCtxFields ¶

func LogCtxFields(ctx context.Context) []zap.Field

LogCtxFields returns the trace.id / transaction.id / span.id zap fields for the active APM transaction (or nil if ctx has none).

Usage in request handlers:

logger.With(apmcore.LogCtxFields(ctx)...).Info("processed request")

Returns an empty slice when ctx is nil or has no active transaction.

func NewGormPlugin ¶

func NewGormPlugin() gorm.Plugin

NewGormPlugin returns a gorm.Plugin that wraps each gorm operation (Create/Query/Update/Delete/Row/Raw) in a parent APM span named "<Op> <table>" of type "db.gorm.<op>". The driver-level spans then nest underneath, producing a foldable hierarchy in Kibana.

The plugin assigns the new ctx back into tx.Statement.Context so the driver-level spans inherit the gorm span as parent. This is the foldable-spans invariant — without it, driver spans parent directly to the transaction and the gorm span looks empty.

func PluginNameOf ¶

func PluginNameOf(p gorm.Plugin) string

PluginNameOf is exported for callers who want to assert plugin registration.

func RegisterDBPoolMetrics ¶

func RegisterDBPoolMetrics(db *sql.DB) func()

RegisterDBPoolMetrics registers an apm.MetricsGatherer that publishes *sql.DB pool statistics on the agent's metrics tick (default 30s, configurable via ELASTIC_APM_METRICS_INTERVAL).

Emitted metrics:

db.pool.max_open
db.pool.open
db.pool.in_use
db.pool.idle
db.pool.wait_count
db.pool.wait_duration_ms
db.pool.max_idle_closed
db.pool.max_idle_time_closed
db.pool.max_lifetime_closed

They land in the metrics-apm.app.<service>-default data stream and are chartable from Kibana → Observability → Infrastructure → Metrics Explorer.

The returned function deregisters the gatherer; call it when the pool is closed (e.g. from a graceful-shutdown PhasePostDB hook).

func RegisterDBPoolMetricsWithManager ¶ added in v0.7.0

func RegisterDBPoolMetricsWithManager(db *sql.DB, mgr CloserRegistrar, phase int, timeout time.Duration)

RegisterDBPoolMetricsWithManager registers the APM pool metrics gatherer and wires its deregister function as a PhasePostDB closer. Without deregistering, the APM agent collects zeroed metrics from the closed pool for one extra tick.

phase must be gscore.PhasePostDB (value 4). Pass 0 to use PhasePostDB. timeout=0 defaults to 5s.

apmcore.RegisterDBPoolMetricsWithManager(sqlDB, mgr, gscore.PhasePostDB, 0)

func RegisterDriver ¶

func RegisterDriver(name string, base driver.Driver)

RegisterDriver wraps an existing database/sql driver with APM instrumentation and registers it under name so it can be opened via sql.Open(name, dsn) or referenced as gorm.Config.DriverName.

The wrapper emits spans for Prepare/Query/Exec/Begin/Commit/Rollback and, crucially, for prepared-statement Close roundtrips — which dominate transaction-commit cost when gorm.PrepareStmt is enabled.

Span names use apmsql.QuerySignature so they are readable in the Kibana waterfall (e.g. "SELECT FROM users (query)" instead of the raw SQL).

Registration is idempotent: calling twice with the same name is a no-op.

func RegisterStartupMetricsWithManager ¶ added in v0.8.3

func RegisterStartupMetricsWithManager(processStart time.Time, mgr *gscore.Manager)

RegisterStartupMetricsWithManager registers a StartupMetricsGatherer with the APM default tracer and wires its deregister function as a PhasePostDB closer so the gatherer is cleanly removed before the APM agent shuts down.

• processStart is the wall-clock time the process was launched. Pass time.Now() from main before any other setup runs so the duration covers the full boot sequence including dependency wiring.
• mgr is the gscore.Manager whose probe state is reflected in the metrics.

The deregister closer uses a 5 s timeout, matching RegisterDBPoolMetricsWithManager.

func RegisterWithManager ¶ added in v0.7.0

func RegisterWithManager(fn ShutdownFunc, mgr CloserRegistrar, phase int, timeout time.Duration)

RegisterWithManager registers the OTel SDK shutdown function as a PhasePostDB closer. Call this immediately after SetupOTelSDK so that in-flight spans and metrics are flushed before the process exits.

phase must be gscore.PhasePostDB (value 4). Pass 0 to use PhasePostDB. timeout=0 defaults to 15s.

shutdown, err := apmcore.SetupOTelSDK(ctx)
apmcore.RegisterWithManager(shutdown, mgr, gscore.PhasePostDB, 0)

func SetLabel ¶

func SetLabel(ctx context.Context, key, value string)

SetLabel attaches a business identifier to the APM transaction in ctx. In Kibana the value appears under `labels.<key>` and can be filtered on. No-op if ctx has no active transaction or value is empty.

Useful for late-binding identifiers that only become available after the handler ran (e.g. a generated transaction ID returned from a domain call).

func SetLabels ¶

func SetLabels(ctx context.Context, m map[string]string)

SetLabels applies SetLabel for every non-empty entry in m. Convenience for middlewares that decode known identifiers from the request body and publish them in one pass.

func TraceFastHTTPCall ¶ added in v0.5.0

func TraceFastHTTPCall(ctx context.Context, req *fasthttp.Request, resp *fasthttp.Response, do func() error) error

TraceFastHTTPCall wraps a single fasthttp client call with an APM exit span. It injects the W3C traceparent header on req, runs do, records the HTTP status code, captures errors, and ends the span.

Use it with any *fasthttp.Client / *fasthttp.HostClient / *PipelineClient method that accepts (*Request, *Response):

err := apmcore.TraceFastHTTPCall(ctx, req, resp, func() error {
    return client.Do(req, resp)
})

For DoTimeout / DoDeadline / DoRedirects, pass the matching closure. Inside a retry loop, call TraceFastHTTPCall on the *innermost* attempt so each retry produces its own sibling span (matching the apmhttp retry-pattern guidance).

If ctx has no active APM transaction the call still runs; the span is silently dropped.

func WrapHTTPTransport ¶

func WrapHTTPTransport(base http.RoundTripper) http.RoundTripper

WrapHTTPTransport wraps base with apmhttp.WrapRoundTripper so every outgoing request built with http.NewRequestWithContext gets its own APM span and the W3C traceparent header injected.

If base is nil, http.DefaultTransport is wrapped.

func WrapZapCore ¶

func WrapZapCore(c zapcore.Core) zapcore.Core

WrapZapCore decorates a zapcore.Core with apmzap.Core so that:

• Any Error/Fatal log line is auto-emitted as an APM error event, visible in Kibana → APM → Errors.
• When used together with LogCtxFields, every log line carries the current request's trace.id / transaction.id / span.id.

Wire it into your zap logger with zap.WrapCore:

logger := zap.NewProductionConfig().Build(
    zap.WrapCore(func(c zapcore.Core) zapcore.Core { return apmcore.WrapZapCore(c) }),
)

Note: at the central error-handler site, log at Warn level (not Error) to avoid double-reporting: apm.CaptureError already records the exception; an Error log here would create a second "log" error doc in Kibana with empty error.exception.type.