anthropic/hooks

Logging and telemetry hooks for observability

This module provides optional hooks for monitoring API interactions, including request lifecycle events, errors, and streaming events.

Hook Points

on_request_start: Called before sending a request
on_request_end: Called after receiving a response (success or error)
on_retry: Called before each retry attempt
on_stream_event: Called for each streaming event

Example

let hooks = default_hooks()
  |> with_on_request_start(fn(event) {
    io.println("Starting request to " <> event.endpoint)
  })
  |> with_on_request_end(fn(event) {
    io.println("Request completed in " <> int.to_string(event.duration_ms) <> "ms")
  })

let client = new_client_with_hooks(config, hooks)

Types

Hooks

</>

Configuration for logging/telemetry hooks

pub type Hooks {
  Hooks(
    on_request_start: option.Option(fn(RequestStartEvent) -> Nil),
    on_request_end: option.Option(fn(RequestEndEvent) -> Nil),
    on_retry: option.Option(fn(RetryEvent) -> Nil),
    on_stream_event: option.Option(fn(StreamEvent) -> Nil),
  )
}

Constructors

Hooks(
  on_request_start: option.Option(fn(RequestStartEvent) -> Nil),
  on_request_end: option.Option(fn(RequestEndEvent) -> Nil),
  on_retry: option.Option(fn(RetryEvent) -> Nil),
  on_stream_event: option.Option(fn(StreamEvent) -> Nil),
)

Arguments

on_request_start: Called when a request starts
on_request_end: Called when a request ends (success or failure)
on_retry: Called before each retry attempt
on_stream_event: Called for each streaming event

RequestEndEvent

</>

Event emitted when a request ends

pub type RequestEndEvent {
  RequestEndEvent(
    endpoint: String,
    duration_ms: Int,
    success: Bool,
    response: option.Option(ResponseSummary),
    error: option.Option(error.AnthropicError),
    request_id: String,
    retry_count: Int,
  )
}

Constructors

```
RequestEndEvent(
  endpoint: String,
  duration_ms: Int,
  success: Bool,
  response: option.Option(ResponseSummary),
  error: option.Option(error.AnthropicError),
  request_id: String,
  retry_count: Int,
)
```
Arguments

endpoint

API endpoint that was called

duration_ms

Duration of the request in milliseconds

success

Whether the request succeeded

response

Response summary (if successful)

error

Error (if failed)

request_id

Unique request ID for correlation

retry_count

Number of retry attempts made

RequestStartEvent

</>

Event emitted when a request starts

pub type RequestStartEvent {
  RequestStartEvent(
    endpoint: String,
    request: RequestSummary,
    timestamp_ms: Int,
    request_id: String,
  )
}

Constructors

```
RequestStartEvent(
  endpoint: String,
  request: RequestSummary,
  timestamp_ms: Int,
  request_id: String,
)
```
Arguments

endpoint

API endpoint being called

request

Request being sent (without sensitive data)

timestamp_ms

Timestamp when request started (milliseconds since epoch)

request_id

Unique request ID for correlation

RequestSummary

</>

Summary of a request (without API key or full content)

pub type RequestSummary {
  RequestSummary(
    model: String,
    message_count: Int,
    max_tokens: Int,
    stream: Bool,
    tool_count: Int,
    has_system: Bool,
  )
}

Constructors

```
RequestSummary(
  model: String,
  message_count: Int,
  max_tokens: Int,
  stream: Bool,
  tool_count: Int,
  has_system: Bool,
)
```
Arguments

model

Model being used

message_count

Number of messages in the request

max_tokens

max_tokens setting

stream

Whether streaming is enabled

tool_count

Number of tools defined

has_system

Whether a system prompt is set

ResponseSummary

</>

Summary of a response

pub type ResponseSummary {
  ResponseSummary(
    id: String,
    model: String,
    stop_reason: option.Option(String),
    input_tokens: Int,
    output_tokens: Int,
    content_block_count: Int,
  )
}

Constructors

```
ResponseSummary(
  id: String,
  model: String,
  stop_reason: option.Option(String),
  input_tokens: Int,
  output_tokens: Int,
  content_block_count: Int,
)
```
Arguments

id

Response ID

model

Model that generated the response

stop_reason

Stop reason

input_tokens

Input tokens used

output_tokens

Output tokens generated

content_block_count

Number of content blocks

RetryEvent

</>

Event emitted before a retry attempt

pub type RetryEvent {
  RetryEvent(
    endpoint: String,
    attempt: Int,
    max_attempts: Int,
    delay_ms: Int,
    error: error.AnthropicError,
    request_id: String,
  )
}

Constructors

```
RetryEvent(
  endpoint: String,
  attempt: Int,
  max_attempts: Int,
  delay_ms: Int,
  error: error.AnthropicError,
  request_id: String,
)
```
Arguments

endpoint

API endpoint being retried

attempt

Current retry attempt (1-indexed)

max_attempts

Maximum retry attempts configured

delay_ms

Delay before this retry in milliseconds

error

Error that triggered the retry

request_id

Unique request ID for correlation

StreamEvent

</>

Event emitted for streaming events

pub type StreamEvent {
  StreamEvent(
    event_type: StreamEventType,
    request_id: String,
    timestamp_ms: Int,
  )
}

Constructors

```
StreamEvent(
  event_type: StreamEventType,
  request_id: String,
  timestamp_ms: Int,
)
```
Arguments

event_type

Type of stream event

request_id

Unique request ID for correlation

timestamp_ms

Timestamp of the event

StreamEventType

</>

Types of streaming events

pub type StreamEventType {
  StreamOpened
  MessageStart
  ContentBlockStart(index: Int)
  ContentBlockDelta(index: Int, delta_type: String)
  ContentBlockStop(index: Int)
  MessageDelta
  MessageStop
  StreamClosed
  StreamError(error: String)
}

Constructors

```
StreamOpened
```
Stream connection opened
```
MessageStart
```
Message start event received
```
ContentBlockStart(index: Int)
```
Content block start event received

ContentBlockDelta(index: Int, delta_type: String)

Content block delta event received

```
ContentBlockStop(index: Int)
```
Content block stop event received
```
MessageDelta
```
Message delta event received
```
MessageStop
```
Message stop event received
```
StreamClosed
```
Stream connection closed
```
StreamError(error: String)
```
Stream error occurred

Values

combine_hooks

</>

pub fn combine_hooks(first: Hooks, second: Hooks) -> Hooks

Combine two hooks, running both callbacks when events occur

default_hooks

</>

pub fn default_hooks() -> Hooks

Create default hooks (all disabled)

emit_request_end

</>

pub fn emit_request_end(
  hooks: Hooks,
  event: RequestEndEvent,
) -> Nil

Emit a request end event

emit_request_start

</>

pub fn emit_request_start(
  hooks: Hooks,
  event: RequestStartEvent,
) -> Nil

Emit a request start event

emit_retry

</>

pub fn emit_retry(hooks: Hooks, event: RetryEvent) -> Nil

Emit a retry event

emit_stream_event

</>

pub fn emit_stream_event(hooks: Hooks, event: StreamEvent) -> Nil

Emit a stream event

generate_request_id

</>

pub fn generate_request_id() -> String

Generate a unique request ID

has_hooks

</>

pub fn has_hooks(hooks: Hooks) -> Bool

Check if any hooks are configured

metrics_hooks

</>

pub fn metrics_hooks(on_metric: fn(String, Int) -> Nil) -> Hooks

Create a metrics-focused hook (counts and timings only)

no_hooks

</>

pub fn no_hooks() -> Hooks

Create hooks with no callbacks (alias for default_hooks)

simple_logging_hooks

</>

pub fn simple_logging_hooks() -> Hooks

Create a simple logging hook that prints to stdout

summarize_request

</>

pub fn summarize_request(
  request: request.CreateMessageRequest,
) -> RequestSummary

Create a request summary from a CreateMessageRequest

summarize_response

</>

pub fn summarize_response(
  response: request.CreateMessageResponse,
) -> ResponseSummary

Create a response summary from a CreateMessageResponse

with_on_request_end

</>

pub fn with_on_request_end(
  hooks: Hooks,
  callback: fn(RequestEndEvent) -> Nil,
) -> Hooks

Set the on_request_end hook

with_on_request_start

</>

pub fn with_on_request_start(
  hooks: Hooks,
  callback: fn(RequestStartEvent) -> Nil,
) -> Hooks

Set the on_request_start hook

with_on_retry

</>

pub fn with_on_retry(
  hooks: Hooks,
  callback: fn(RetryEvent) -> Nil,
) -> Hooks

Set the on_retry hook

with_on_stream_event

</>

pub fn with_on_stream_event(
  hooks: Hooks,
  callback: fn(StreamEvent) -> Nil,
) -> Hooks

Set the on_stream_event hook