Hooks and Observability

Hooks & Observability

Register global callbacks to observe requests, responses, errors, and token usage.

Hooks are useful for logging, metrics, tracing, and debugging without wrapping every call site.

Available Hooks

• ai.OnBeforeRequest(func(model ai.Model, messages []ai.Message))
• ai.OnAfterResponse(func(model ai.Model, content string, duration time.Duration))
• ai.OnError(func(model ai.Model, err error))
• ai.OnTokens(func(model ai.Model, prompt, completion int))

Clear everything with ai.ClearHooks().

Minimal Logging Example

before, after, onErr := ai.LoggingHooks()

ai.OnBeforeRequest(before)
ai.OnAfterResponse(after)
ai.OnError(onErr)

Metrics Example

Use the built-in MetricsCollector helper:

collector := ai.NewMetricsCollector()
collector.Register()

// ... make requests ...
_, _ = ai.GPT5().Ask("hello")
_, _ = ai.Claude().Ask("hi")

fmt.Println("requests:", collector.RequestCount)
fmt.Println("errors:", collector.ErrorCount)
fmt.Println("total duration:", collector.TotalDuration)
fmt.Println("models:", collector.ModelCounts)
fmt.Println("total tokens:", collector.TotalTokens)

Notes

• Hooks are global (process-wide) and are invoked for every request.
• Hooks may be invoked multiple times if you use retries/fallbacks.