cquill/telemetry

Types

AttachError

Error types for handler operations

pub type AttachError {
  HandlerAlreadyExists(handler_id: String)
  TelemetryNotRunning
}

Constructors

HandlerAlreadyExists(handler_id: String)

Handler with this ID already exists

```
TelemetryNotRunning
```
Telemetry server not running

BatchStartEvent

</>

Emitted when a batch operation starts

pub type BatchStartEvent {
  BatchStartEvent(
    operation: String,
    table: String,
    batch_size: Int,
    start_time_us: Int,
  )
}

Constructors

```
BatchStartEvent(
  operation: String,
  table: String,
  batch_size: Int,
  start_time_us: Int,
)
```
Arguments

operation

Type of batch operation (insert, update, delete)

table

Table being operated on

batch_size

Number of records in the batch

start_time_us

Monotonic start time in microseconds

BatchStopEvent

</>

Emitted when a batch operation completes

pub type BatchStopEvent {
  BatchStopEvent(
    operation: String,
    table: String,
    affected_count: Int,
    duration_us: Int,
  )
}

Constructors

```
BatchStopEvent(
  operation: String,
  table: String,
  affected_count: Int,
  duration_us: Int,
)
```
Arguments

operation

Type of batch operation (insert, update, delete)

table

Table being operated on

affected_count

Number of records affected

duration_us

Duration in microseconds

DetachError

</>

pub type DetachError {
  HandlerNotFound(handler_id: String)
  DetachTelemetryNotRunning
}

Constructors

```
HandlerNotFound(handler_id: String)
```
Handler with this ID not found
```
DetachTelemetryNotRunning
```
Telemetry server not running

Event

</>

All telemetry event types that can be emitted

pub type Event {
  QueryStart(QueryStartEvent)
  QueryStop(QueryStopEvent)
  QueryException(QueryExceptionEvent)
  PoolCheckout(PoolCheckoutEvent)
  PoolCheckin(PoolCheckinEvent)
  PoolTimeout(PoolTimeoutEvent)
  TransactionStart(TransactionStartEvent)
  TransactionCommit(TransactionCommitEvent)
  TransactionRollback(TransactionRollbackEvent)
  SavepointCreate(SavepointCreateEvent)
  SavepointRollback(SavepointRollbackEvent)
  SavepointRelease(SavepointReleaseEvent)
  BatchStart(BatchStartEvent)
  BatchStop(BatchStopEvent)
}

Constructors

```
QueryStart(QueryStartEvent)
```
```
QueryStop(QueryStopEvent)
```
```
QueryException(QueryExceptionEvent)
```
```
PoolCheckout(PoolCheckoutEvent)
```
```
PoolCheckin(PoolCheckinEvent)
```
```
PoolTimeout(PoolTimeoutEvent)
```
```
TransactionStart(TransactionStartEvent)
```

TransactionCommit(TransactionCommitEvent)

TransactionRollback(TransactionRollbackEvent)

```
SavepointCreate(SavepointCreateEvent)
```

SavepointRollback(SavepointRollbackEvent)

```
SavepointRelease(SavepointReleaseEvent)
```
```
BatchStart(BatchStartEvent)
```
```
BatchStop(BatchStopEvent)
```

EventType

</>

Event type enumeration for handler registration

pub type EventType {
  QueryStartType
  QueryStopType
  QueryExceptionType
  PoolCheckoutType
  PoolCheckinType
  PoolTimeoutType
  TransactionStartType
  TransactionCommitType
  TransactionRollbackType
  SavepointCreateType
  SavepointRollbackType
  SavepointReleaseType
  BatchStartType
  BatchStopType
}

Constructors

```
QueryStartType
```
```
QueryStopType
```
```
QueryExceptionType
```
```
PoolCheckoutType
```
```
PoolCheckinType
```
```
PoolTimeoutType
```
```
TransactionStartType
```
```
TransactionCommitType
```
```
TransactionRollbackType
```
```
SavepointCreateType
```
```
SavepointRollbackType
```
```
SavepointReleaseType
```
```
BatchStartType
```
```
BatchStopType
```

Handler

</>

A telemetry handler function that receives events

pub type Handler =
  fn(Event, dict.Dict(String, dynamic.Dynamic)) -> Nil

Metadata

</>

Metadata dictionary for additional context

pub type Metadata =
  dict.Dict(String, dynamic.Dynamic)

PoolCheckinEvent

</>

Emitted when a connection is returned to the pool

pub type PoolCheckinEvent {
  PoolCheckinEvent(pool_name: String, usage_time_us: Int)
}

Constructors

```
PoolCheckinEvent(pool_name: String, usage_time_us: Int)
```
Arguments

pool_name

Name/identifier of the pool

usage_time_us

How long the connection was used (microseconds)

PoolCheckoutEvent

</>

Emitted when a connection is checked out from the pool

pub type PoolCheckoutEvent {
  PoolCheckoutEvent(
    pool_name: String,
    wait_time_us: Int,
    queue_length: Int,
  )
}

Constructors

```
PoolCheckoutEvent(
  pool_name: String,
  wait_time_us: Int,
  queue_length: Int,
)
```
Arguments

pool_name

Name/identifier of the pool

wait_time_us

Time spent waiting for a connection (microseconds)

queue_length

Number of requests waiting in queue

PoolTimeoutEvent

</>

Emitted when a pool checkout times out

pub type PoolTimeoutEvent {
  PoolTimeoutEvent(
    pool_name: String,
    wait_time_us: Int,
    queue_length: Int,
  )
}

Constructors

```
PoolTimeoutEvent(
  pool_name: String,
  wait_time_us: Int,
  queue_length: Int,
)
```
Arguments

pool_name

Name/identifier of the pool

wait_time_us

How long the request waited before timing out (microseconds)

queue_length

Number of requests waiting in queue when timeout occurred

QueryExceptionEvent

</>

Emitted when a query fails with an exception

pub type QueryExceptionEvent {
  QueryExceptionEvent(
    query: String,
    params: List(ast.Value),
    error: error.AdapterError,
    duration_us: Int,
    source: option.Option(SourceLocation),
  )
}

Constructors

QueryExceptionEvent(
  query: String,
  params: List(ast.Value),
  error: error.AdapterError,
  duration_us: Int,
  source: option.Option(SourceLocation),
)

Arguments

query: The SQL query that failed
params: Query parameters
error: The error that occurred
duration_us: Duration in microseconds until failure
source: Source location in user code

QueryStartEvent

</>

Emitted when a query starts executing

pub type QueryStartEvent {
  QueryStartEvent(
    query: String,
    params: List(ast.Value),
    source: option.Option(SourceLocation),
    start_time_us: Int,
  )
}

Constructors

```
QueryStartEvent(
  query: String,
  params: List(ast.Value),
  source: option.Option(SourceLocation),
  start_time_us: Int,
)
```
Arguments

query

The SQL query being executed

params

Query parameters

source

Source location in user code

start_time_us

Monotonic start time in microseconds

QueryStopEvent

</>

Emitted when a query completes successfully

pub type QueryStopEvent {
  QueryStopEvent(
    query: String,
    params: List(ast.Value),
    duration_us: Int,
    row_count: Int,
    source: option.Option(SourceLocation),
  )
}

Constructors

```
QueryStopEvent(
  query: String,
  params: List(ast.Value),
  duration_us: Int,
  row_count: Int,
  source: option.Option(SourceLocation),
)
```
Arguments

query

The SQL query that was executed

params

Query parameters

duration_us

Duration in microseconds

row_count

Number of rows returned/affected

source

Source location in user code

SavepointCreateEvent

</>

Emitted when a savepoint is created

pub type SavepointCreateEvent {
  SavepointCreateEvent(
    transaction_id: String,
    savepoint_name: String,
    created_at_us: Int,
  )
}

Constructors

```
SavepointCreateEvent(
  transaction_id: String,
  savepoint_name: String,
  created_at_us: Int,
)
```
Arguments

transaction_id

Transaction ID containing this savepoint

savepoint_name

Name of the savepoint

created_at_us

Monotonic time when created

SavepointReleaseEvent

</>

Emitted when a savepoint is released

pub type SavepointReleaseEvent {
  SavepointReleaseEvent(
    transaction_id: String,
    savepoint_name: String,
  )
}

Constructors

```
SavepointReleaseEvent(
  transaction_id: String,
  savepoint_name: String,
)
```
Arguments

transaction_id

Transaction ID containing this savepoint

savepoint_name

Name of the savepoint

SavepointRollbackEvent

</>

Emitted when a savepoint is rolled back to

pub type SavepointRollbackEvent {
  SavepointRollbackEvent(
    transaction_id: String,
    savepoint_name: String,
    reason: option.Option(String),
  )
}

Constructors

```
SavepointRollbackEvent(
  transaction_id: String,
  savepoint_name: String,
  reason: option.Option(String),
)
```
Arguments

transaction_id

Transaction ID containing this savepoint

savepoint_name

Name of the savepoint

reason

Reason for rollback (if known)

SourceLocation

</>

Source location in user code where an operation originated

pub type SourceLocation {
  SourceLocation(file: String, line: Int, function: String)
}

Constructors

SourceLocation(file: String, line: Int, function: String)

TransactionCommitEvent

</>

Emitted when a transaction commits successfully

pub type TransactionCommitEvent {
  TransactionCommitEvent(
    transaction_id: String,
    duration_us: Int,
    query_count: Int,
    source: option.Option(SourceLocation),
  )
}

Constructors

```
TransactionCommitEvent(
  transaction_id: String,
  duration_us: Int,
  query_count: Int,
  source: option.Option(SourceLocation),
)
```
Arguments

transaction_id

Unique transaction ID

duration_us

Duration of the transaction (microseconds)

query_count

Number of queries executed in the transaction

source

Source location in user code

TransactionRollbackEvent

</>

Emitted when a transaction is rolled back

pub type TransactionRollbackEvent {
  TransactionRollbackEvent(
    transaction_id: String,
    duration_us: Int,
    reason: option.Option(String),
    source: option.Option(SourceLocation),
  )
}

Constructors

```
TransactionRollbackEvent(
  transaction_id: String,
  duration_us: Int,
  reason: option.Option(String),
  source: option.Option(SourceLocation),
)
```
Arguments

transaction_id

Unique transaction ID

duration_us

Duration of the transaction (microseconds)

reason

Reason for rollback (if known)

source

Source location in user code

TransactionStartEvent

</>

Emitted when a transaction begins

pub type TransactionStartEvent {
  TransactionStartEvent(
    transaction_id: String,
    source: option.Option(SourceLocation),
    start_time_us: Int,
  )
}

Constructors

```
TransactionStartEvent(
  transaction_id: String,
  source: option.Option(SourceLocation),
  start_time_us: Int,
)
```
Arguments

transaction_id

Unique transaction ID

source

Source location in user code

start_time_us

Monotonic start time in microseconds

Values

attach

</>

pub fn attach(
  handler_id: String,
  events: List(EventType),
  handler: fn(Event, dict.Dict(String, dynamic.Dynamic)) -> Nil,
) -> Result(Nil, AttachError)

Attach a telemetry handler for specific event types

batch_start

</>

pub fn batch_start(
  operation: String,
  table: String,
  batch_size: Int,
) -> Event

Create a batch start event

batch_stop

</>

pub fn batch_stop(
  operation: String,
  table: String,
  affected_count: Int,
  duration_us: Int,
) -> Event

Create a batch stop event

debug_handler

</>

pub fn debug_handler() -> fn(
  Event,
  dict.Dict(String, dynamic.Dynamic),
) -> Nil

Debug handler that logs all events

detach

</>

pub fn detach(handler_id: String) -> Result(Nil, DetachError)

Detach a handler by ID

duration_since

</>

pub fn duration_since(start_time_us: Int) -> Int

Calculate duration in microseconds between start time and now

emit

</>

pub fn emit(
  event: Event,
  metadata: dict.Dict(String, dynamic.Dynamic),
) -> Nil

Emit an event to all registered handlers

emit_event

</>

pub fn emit_event(event: Event) -> Nil

Emit an event with empty metadata

empty_metadata

</>

pub fn empty_metadata() -> dict.Dict(String, dynamic.Dynamic)

Create empty metadata

event_type_name

</>

pub fn event_type_name(event_type: EventType) -> String

Get a human-readable name for an event type

handler_count

</>

pub fn handler_count() -> Int

Get the number of attached handlers

list_handlers

</>

pub fn list_handlers() -> List(#(String, List(EventType)))

List all attached handlers

logger_handler

</>

pub fn logger_handler() -> fn(
  Event,
  dict.Dict(String, dynamic.Dynamic),
) -> Nil

Logger handler that prints query events to stdout/stderr

metrics_handler

</>

pub fn metrics_handler(
  on_query_complete: fn(String, Int, Int) -> Nil,
  on_query_error: fn(String) -> Nil,
  on_pool_timeout: fn(String) -> Nil,
) -> fn(Event, dict.Dict(String, dynamic.Dynamic)) -> Nil

Metrics handler builder - returns a handler that calls the provided callbacks

now_us

</>

pub fn now_us() -> Int

Get current monotonic time in microseconds Uses Erlang’s monotonic time converted to microseconds

pool_timeout

</>

pub fn pool_timeout(
  pool_name: String,
  wait_time_us: Int,
  queue_length: Int,
) -> Event

Create a pool timeout event

query_exception

</>

pub fn query_exception(
  query: String,
  params: List(ast.Value),
  err: error.AdapterError,
  duration_us: Int,
  source: option.Option(SourceLocation),
) -> Event

Create a query exception event

query_span

</>

pub fn query_span(
  query: String,
  params: List(ast.Value),
  source: option.Option(SourceLocation),
  metadata: dict.Dict(String, dynamic.Dynamic),
  f: fn() -> Result(#(a, Int), error.AdapterError),
) -> Result(#(a, Int), error.AdapterError)

Execute a function with query start/stop telemetry

query_start

</>

pub fn query_start(
  query: String,
  params: List(ast.Value),
  source: option.Option(SourceLocation),
) -> Event

Create a query start event

query_stop

</>

pub fn query_stop(
  query: String,
  params: List(ast.Value),
  duration_us: Int,
  row_count: Int,
  source: option.Option(SourceLocation),
) -> Event

Create a query stop event

slow_query_handler

</>

pub fn slow_query_handler(
  threshold_ms: Int,
) -> fn(Event, dict.Dict(String, dynamic.Dynamic)) -> Nil

Slow query handler that logs queries exceeding a threshold

source_location

</>

pub fn source_location(
  file: String,
  line: Int,
  function: String,
) -> SourceLocation

Create a source location

start

</>

pub fn start() -> Result(Nil, actor.StartError)

Start the telemetry server Returns Ok(Nil) on success, Error on failure

stop

</>

pub fn stop() -> Nil

Stop the telemetry server

timed

</>

pub fn timed(f: fn() -> a) -> #(a, Int)

Time a function and return its result along with duration

transaction_commit

</>

pub fn transaction_commit(
  transaction_id: String,
  duration_us: Int,
  query_count: Int,
  source: option.Option(SourceLocation),
) -> Event

Create a transaction commit event

transaction_rollback

</>

pub fn transaction_rollback(
  transaction_id: String,
  duration_us: Int,
  reason: option.Option(String),
  source: option.Option(SourceLocation),
) -> Event

Create a transaction rollback event

transaction_span

</>

pub fn transaction_span(
  transaction_id: String,
  source: option.Option(SourceLocation),
  metadata: dict.Dict(String, dynamic.Dynamic),
  f: fn() -> Result(#(a, Int), String),
) -> Result(a, String)

Execute a function with transaction start/commit/rollback telemetry

transaction_start

</>

pub fn transaction_start(
  transaction_id: String,
  source: option.Option(SourceLocation),
) -> Event

Create a transaction start event

with_bool

</>

pub fn with_bool(
  metadata: dict.Dict(String, dynamic.Dynamic),
  key: String,
  value: Bool,
) -> dict.Dict(String, dynamic.Dynamic)

Add a bool to metadata

with_int

</>

pub fn with_int(
  metadata: dict.Dict(String, dynamic.Dynamic),
  key: String,
  value: Int,
) -> dict.Dict(String, dynamic.Dynamic)

Add an int to metadata

with_string

</>

pub fn with_string(
  metadata: dict.Dict(String, dynamic.Dynamic),
  key: String,
  value: String,
) -> dict.Dict(String, dynamic.Dynamic)

Add a string to metadata