pig - v0.1.0

pig/obs/events

Telemetry event definitions for the pig library.

A single Event union type with typed variants for every pig event. One emit(Event) function, one event_name(Event) accessor.

Uses a thin Erlang FFI (pig_obs_ffi) that wraps :telemetry.execute/3 and converts string-keyed dicts to atom-keyed maps. All pig telemetry events as typed variants. Construct these directly and pass to emit().

Types

Event

</> 
pub type Event {
  InferenceStart(model: String, message_count: Int)
  InferenceStop(
    model: String,
    message_count: Int,
    duration_ms: Int,
    response_id: option.Option(String),
    stop_reason: option.Option(stop_reason.StopReason),
    input_tokens: option.Option(Int),
    output_tokens: option.Option(Int),
  )
  InferenceException(
    model: String,
    message_count: Int,
    error_type: String,
  )
  ToolStart(
    tool_name: String,
    tool_call_id: String,
    arguments_json: String,
  )
  ToolStop(
    tool_name: String,
    tool_call_id: String,
    duration_ms: Int,
    result: String,
  )
  ToolException(
    tool_name: String,
    tool_call_id: String,
    arguments_json: String,
  )
}

Constructors 

  • InferenceStart(model: String, message_count: Int)
  • InferenceStop(
  model: String,
  message_count: Int,
  duration_ms: Int,
  response_id: option.Option(String),
  stop_reason: option.Option(stop_reason.StopReason),
  input_tokens: option.Option(Int),
  output_tokens: option.Option(Int),
)
  • InferenceException(
  model: String,
  message_count: Int,
  error_type: String,
)
  • ToolStart(
  tool_name: String,
  tool_call_id: String,
  arguments_json: String,
)
  • ToolStop(
  tool_name: String,
  tool_call_id: String,
  duration_ms: Int,
  result: String,
)
  • ToolException(
  tool_name: String,
  tool_call_id: String,
  arguments_json: String,
)

HookActionDetail

</>

Details of a hook’s action.

pub type HookActionDetail {
  HookActionDetail(action_type: String, description: String)
}

Constructors 

  • HookActionDetail(action_type: String, description: String)

HookPoint

</>

Hook points for lifecycle events.

pub type HookPoint {
  BeforeToolCall
  AfterToolCall
  BeforeInference
  AfterInference
  OnError
  OnComplete
  OnSessionStart
  OnSessionShutdown
}

Constructors 

  • BeforeToolCall
  • AfterToolCall
  • BeforeInference
  • AfterInference
  • OnError
  • OnComplete
  • OnSessionStart
  • OnSessionShutdown

RawCapturedEvent

</>

Internal type for raw captured telemetry data.

pub type RawCapturedEvent {
  RawCapturedEvent(
    name: List(String),
    measurements: dict.Dict(String, Int),
    metadata: dict.Dict(String, String),
  )
}

Constructors 

  • RawCapturedEvent(
  name: List(String),
  measurements: dict.Dict(String, Int),
  metadata: dict.Dict(String, String),
)

SessionEndReason

</>

Reasons why a session ended.

pub type SessionEndReason {
  NormalEnd
  ErrorEnd(error.AiError)
  MaxIterationsExceeded(Int)
  Interrupted
}

Constructors 

  • NormalEnd
  • ErrorEnd(error.AiError)
  • MaxIterationsExceeded(Int)
  • Interrupted

SessionEvent

</>

Rich session events for pig consumers (session writer, terminal printer, OTel). Carries full message content, tool args/results, token counts, and timing.

pub type SessionEvent {
  SessionStarted(
    agent_id: option.Option(String),
    agent_name: option.Option(String),
    model: String,
    provider_name: option.Option(String),
    system_prompt: option.Option(String),
  )
  InferenceStarted(model: String, message_count: Int)
  InferenceCompleted(
    message: message.Message,
    response_id: option.Option(String),
    response_model: option.Option(String),
    stop_reason: option.Option(stop_reason.StopReason),
    input_tokens: option.Option(Int),
    output_tokens: option.Option(Int),
    duration_ms: Int,
    input_messages: List(message.Message),
  )
  ToolStarted(tool_call: message.ToolCall)
  ToolExecuted(
    tool_call: message.ToolCall,
    result: String,
    duration_ms: Int,
  )
  ToolBlocked(
    tool_call: message.ToolCall,
    hook_name: String,
    reason: String,
  )
  HookActed(
    hook_name: String,
    hook_point: HookPoint,
    action: HookActionDetail,
  )
  InferenceFailed(
    error: error.AiError,
    duration_ms: Int,
    input_messages: List(message.Message),
  )
  SessionEnded(reason: SessionEndReason)
}

Constructors

Values

all_event_names

</> 
pub fn all_event_names() -> List(List(String))

All pig event names, useful for attaching a listener to everything.

decode

</> 
pub fn decode(raw: RawCapturedEvent) -> Event

Decode a raw captured event into a typed Event. Panics on unknown event names or missing fields (internal consistency).

emit

</> 
pub fn emit(event: Event) -> Nil

Emit a typed telemetry event.

emit_exception

</> 
pub fn emit_exception(
  name: List(String),
  meta: dict.Dict(String, String),
) -> Nil

Emit a custom exception event with auto-populated system_time measurement.

emit_start

</> 
pub fn emit_start(
  name: List(String),
  meta: dict.Dict(String, String),
) -> Nil

Emit a custom start event with auto-populated system_time measurement.

emit_stop

</> 
pub fn emit_stop(
  name: List(String),
  duration_ms: Int,
  meta: dict.Dict(String, String),
) -> Nil

Emit a custom stop event with duration and system_time measurements.

event_name

</> 
pub fn event_name(event: Event) -> List(String)

Get the telemetry event name for a given event.

execute_telemetry

</> 
pub fn execute_telemetry(
  name: List(String),
  measurements: dict.Dict(String, Int),
  metadata: dict.Dict(String, String),
) -> Nil

Public wrapper for the FFI execute function. This allows other modules (like the dispatcher) to emit telemetry events without exposing the FFI implementation directly.

inference_exception_name

</> 
pub fn inference_exception_name() -> List(String)

inference_start_name

</> 
pub fn inference_start_name() -> List(String)

inference_stop_name

</> 
pub fn inference_stop_name() -> List(String)

name_to_string

</> 
pub fn name_to_string(name: List(String)) -> String

Convert an event name list to a dot-separated string for display.

system_time

</> 
pub fn system_time() -> Int

Get the current monotonic system time. Used for duration measurements.

tool_blocked_name

</> 
pub fn tool_blocked_name() -> List(String)

tool_exception_name

</> 
pub fn tool_exception_name() -> List(String)

tool_start_name

</> 
pub fn tool_start_name() -> List(String)

tool_stop_name

</> 
pub fn tool_stop_name() -> List(String)
✨ Search Document