Built-in Functions

Built-in functions are automatically registered by iii framework modules and can be invoked from any worker without manual registration. These functions provide core engine capabilities like worker management, key-value storage, and observability.

Worker Module Functions

Functions for managing workers, channels, and registered functions.

engine::channels::create

Create a streaming channel pair for real-time communication.

buffer_size

number

Channel buffer size (default: 64, max: 1024)

writer

StreamChannelRef

Writer channel reference for sending data

reader

StreamChannelRef

Reader channel reference for receiving data

const result = await invoke('engine::channels::create', {
  buffer_size: 100
});
// { writer: { id: "...", ... }, reader: { id: "...", ... } }

engine::functions::list

List all registered functions in the engine.

include_internal

boolean

default:false

Include internal engine functions (engine.* prefix)

functions

array

Array of function information objects

Show FunctionInfo fields

function_id

string

Function identifier

description

string

Function description

request_format

object

Request schema (JSON Schema)

response_format

object

Response schema (JSON Schema)

metadata

object

Additional metadata

const result = await invoke('engine::functions::list', {
  include_internal: false
});
// { functions: [{ function_id: "myService::myFunction", ... }] }

engine::workers::list

List all connected workers with metrics.

worker_id

string

Filter by specific worker ID

workers

array

Array of worker information objects

Show WorkerInfo fields

string

Worker unique identifier

name

string

Worker name

runtime

string

Runtime environment (e.g., “node”, “rust”)

version

string

Worker version

string

Operating system

ip_address

string

IP address

status

string

Worker status

connected_at_ms

number

Connection timestamp (milliseconds)

function_count

number

Number of registered functions

functions

array

Array of function IDs

active_invocations

number

Current active invocations

latest_metrics

object

Latest worker metrics

timestamp

number

Query timestamp (milliseconds)

const result = await invoke('engine::workers::list', {});
// { workers: [{ id: "...", name: "worker-1", runtime: "node", ... }], timestamp: 1234567890 }

engine::triggers::list

List all registered triggers.

include_internal

boolean

default:false

Include internal engine triggers

triggers

array

Array of trigger information objects

Show TriggerInfo fields

string

Trigger unique identifier

trigger_type

string

Type of trigger

function_id

string

Target function ID

config

object

Trigger configuration

const result = await invoke('engine::triggers::list', {
  include_internal: false
});
// { triggers: [{ id: "...", trigger_type: "cron", function_id: "...", config: {...} }] }

engine::workers::register

_caller_worker_id

string

required

Worker ID (automatically injected)

runtime

string

Runtime environment (e.g., “node”, “rust”, “python”)

version

string

Worker version

name

string

Worker name

string

Operating system information

telemetry

object

Telemetry metadata

Show WorkerTelemetryMeta fields

language

string

Language/locale

project_name

string

Project name

framework

string

Framework name

success

boolean

Registration success status

const result = await invoke('engine::workers::register', {
  runtime: 'node',
  version: '1.0.0',
  name: 'my-worker',
  os: 'linux x64'
});
// { success: true }

KV Server Functions

Key-value storage functions for persistent state.

kv_server::get

Get a value by key from the KV store.

index

string

required

Index name (namespace)

key

string

required

Key to retrieve

value

any

The stored value, or null if not found

const value = await invoke('kv_server::get', {
  index: 'users',
  key: 'user:123'
});
// { name: "Alice", email: "[email protected]" }

kv_server::set

Set a value by key in the KV store.

index

string

required

Index name (namespace)

key

string

required

Key to set

value

any

required

Value to store (any JSON-serializable data)

key

string

The key that was set

value

any

The value that was stored

created

boolean

Whether this was a new key (true) or update (false)

const result = await invoke('kv_server::set', {
  index: 'users',
  key: 'user:123',
  value: { name: 'Alice', email: '[email protected]' }
});
// { key: "user:123", value: {...}, created: true }

kv_server::delete

Delete a value by key from the KV store.

index

string

required

Index name (namespace)

key

string

required

Key to delete

deleted

boolean

Whether the key was deleted

old_value

any

The previous value, if it existed

const result = await invoke('kv_server::delete', {
  index: 'users',
  key: 'user:123'
});
// { deleted: true, old_value: {...} }

kv_server::update

Update a value with atomic operations.

index

string

required

Index name (namespace)

key

string

required

Key to update

ops

array

required

Array of update operations

old_value

any

The value before the update

new_value

any

The value after the update

Update Operations:

Set { path, value } - Set a field at the specified path
Merge { path, value } - Merge an object with the existing value
Increment { path, by } - Add a numeric value to a field
Decrement { path, by } - Subtract a numeric value from a field
Remove { path } - Remove a field at the specified path

import { UpdateOp } from 'iii-sdk';

const result = await invoke('kv_server::update', {
  index: 'users',
  key: 'user:123',
  ops: [
    UpdateOp.increment('loginCount', 1),
    UpdateOp.set('lastLogin', Date.now())
  ]
});
// { old_value: {...}, new_value: {...} }

kv_server::list

List all values in an index.

index

string

required

Index name (namespace)

values

array

Array of all values in the index

const result = await invoke('kv_server::list', {
  index: 'users'
});
// [{ key: "user:123", value: {...} }, { key: "user:456", value: {...} }]

kv_server::list_keys_with_prefix

List all keys with a specific prefix.

prefix

string

required

Key prefix to filter by

keys

array

Array of matching keys

const result = await invoke('kv_server::list_keys_with_prefix', {
  prefix: 'user:'
});
// ["user:123", "user:456", "user:789"]

Observability Functions

Functions for logging, tracing, metrics, and monitoring.

Logging Functions

OTEL-native logging functions with structured data support.

engine::log::info

Log an informational message.

message

string

required

Log message

data

object

Structured data/attributes

trace_id

string

Trace ID for correlation

span_id

string

Span ID for correlation

service_name

string

Service name (defaults to function name)

await invoke('engine::log::info', {
  message: 'User logged in',
  data: { userId: '123', ip: '192.168.1.1' }
});

engine::log::warn

Log a warning message. Parameters are identical to engine::log::info.

await invoke('engine::log::warn', {
  message: 'Rate limit approaching',
  data: { current: 950, limit: 1000 }
});

engine::log::error

Log an error message. Parameters are identical to engine::log::info.

await invoke('engine::log::error', {
  message: 'Database connection failed',
  data: { error: err.message, retries: 3 }
});

engine::log::debug

Log a debug message. Parameters are identical to engine::log::info.

await invoke('engine::log::debug', {
  message: 'Processing request',
  data: { requestId: '...' }
});

engine::log::trace

Log a trace-level message. Parameters are identical to engine::log::info.

await invoke('engine::log::trace', {
  message: 'Function entry',
  data: { args: [...] }
});

Baggage Functions

Access and manage OpenTelemetry baggage for context propagation.

engine::baggage::get

Get a baggage item value from the current context.

key

string

required

Baggage key to retrieve

value

string

Baggage value, or null if not found

const result = await invoke('engine::baggage::get', {
  key: 'user-id'
});
// { value: "123" }

engine::baggage::set

Set a baggage item value.

Baggage in OpenTelemetry is immutable. This function creates a new context but cannot propagate it back to the caller. For real baggage propagation, use SDK-level baggage headers.

key

string

required

Baggage key to set

value

string

required

Baggage value

await invoke('engine::baggage::set', {
  key: 'user-id',
  value: '123'
});

engine::baggage::get_all

Get all baggage items from the current context.

baggage

object

Object with all baggage key-value pairs

const result = await invoke('engine::baggage::get_all', {});
// { baggage: { "user-id": "123", "request-id": "..." } }

Traces Functions

Query and manage distributed traces.

Trace storage is only available when the OTEL exporter is set to memory or both in configuration.

engine::traces::list

List stored traces with filtering and pagination.

trace_id

string

Filter by specific trace ID

offset

number

default:0

Pagination offset

limit

number

default:100

Maximum number of spans to return

service_name

string

Filter by service name (substring match)

name

string

Filter by span name (substring match)

status

string

Filter by status (substring match)

min_duration_ms

number

Minimum span duration in milliseconds

max_duration_ms

number

Maximum span duration in milliseconds

start_time

number

Start time in Unix timestamp milliseconds

end_time

number

End time in Unix timestamp milliseconds

sort_by

string

default:"start_time"

Sort field: “duration”, “start_time”, or “name”

sort_order

string

default:"asc"

Sort order: “asc” or “desc”

attributes

array

Filter by attributes (array of [key, value] pairs)

include_internal

boolean

default:false

Include internal engine traces

spans

array

Array of span objects

total

number

Total number of matching spans

offset

number

Current offset

limit

number

Current limit

const result = await invoke('engine::traces::list', {
  service_name: 'api',
  min_duration_ms: 100,
  limit: 50
});
// { spans: [...], total: 150, offset: 0, limit: 50 }

engine::traces::tree

Get trace tree with nested children for a specific trace.

trace_id

string

required

Trace ID to build the tree for

roots

array

Array of root span tree nodes with nested children

const result = await invoke('engine::traces::tree', {
  trace_id: '1234567890abcdef'
});
// { roots: [{ span: {...}, children: [...] }] }

engine::traces::clear

Clear all stored traces from memory.

success

boolean

Clear operation success status

const result = await invoke('engine::traces::clear', {});
// { success: true }

Metrics Functions

Query engine and SDK metrics.

engine::metrics::list

List current metrics values.

start_time

number

Start time in Unix timestamp milliseconds

end_time

number

End time in Unix timestamp milliseconds

metric_name

string

Filter by metric name

aggregate_interval

number

Aggregate interval in seconds

engine_metrics

object

Engine internal metrics

Show Engine metrics structure

invocations

object

Function invocation counters

workers

object

Worker lifecycle counters

performance

object

Performance statistics (avg, p50, p95, p99, min, max duration)

sdk_metrics

array

SDK-recorded metrics

aggregated_metrics

array

Time-aggregated metrics (if aggregate_interval specified)

timestamp

number

Query timestamp

const result = await invoke('engine::metrics::list', {
  start_time: Date.now() - 3600000,
  end_time: Date.now(),
  aggregate_interval: 60
});
// { engine_metrics: {...}, sdk_metrics: [...], timestamp: ... }

engine::rollups::list

Get pre-aggregated metrics rollups.

start_time

number

Start time in Unix timestamp milliseconds (default: 1 hour ago)

end_time

number

End time in Unix timestamp milliseconds (default: now)

level

number

default:0

Rollup level: 0 = 1 minute, 1 = 5 minutes, 2 = 1 hour

metric_name

string

Filter by metric name

rollups

array

Array of metric rollups

histogram_rollups

array

Array of histogram rollups

level

number

Rollup level used

const result = await invoke('engine::rollups::list', {
  level: 1, // 5-minute rollups
  metric_name: 'http.requests'
});
// { rollups: [...], histogram_rollups: [...], level: 1 }

Logs Functions

Query and manage stored logs.

engine::logs::list

List stored OTEL logs with filtering.

trace_id

string

Filter by trace ID

span_id

string

Filter by span ID

severity_min

number

Minimum severity number (1-24, higher = more severe)

severity_text

string

Filter by severity text (e.g., “ERROR”, “WARN”, “INFO”)

start_time

number

Start time in Unix timestamp milliseconds

end_time

number

End time in Unix timestamp milliseconds

offset

number

Pagination offset

limit

number

Maximum number of logs to return

logs

array

Array of log entries

total

number

Total number of matching logs

const result = await invoke('engine::logs::list', {
  severity_text: 'ERROR',
  start_time: Date.now() - 3600000
});
// { logs: [...], total: 42, timestamp: ... }

engine::logs::clear

Clear all stored OTEL logs.

success

boolean

Clear operation success status

const result = await invoke('engine::logs::clear', {});
// { success: true }

Health and Diagnostics

engine::health::check

Check system health status.

status

string

Overall health status

components

object

Health status of individual components

Show Component structure

otel

object

OTEL configuration status

metrics

object

Metrics storage status

logs

object

Logs storage status

spans

object

Spans storage status

timestamp

number

Check timestamp

version

string

Engine version

const result = await invoke('engine::health::check', {});
// { status: "healthy", components: {...}, timestamp: ..., version: "0.7.0" }

engine::sampling::rules

Get active sampling rules configuration.

traces

object

Trace sampling configuration

Show Traces sampling

default_ratio

number

Default sampling ratio (0.0-1.0)

rules

array

Per-operation sampling rules

parent_based

boolean

Whether to respect parent sampling decisions

logs

object

Log sampling configuration

Show Logs sampling

sampling_ratio

number

Log sampling ratio (0.0-1.0)

const result = await invoke('engine::sampling::rules', {});
// { traces: { default_ratio: 1.0, rules: [...], parent_based: true }, logs: { sampling_ratio: 1.0 } }

Alerts Functions

Manage and query alert states.

engine::alerts::list

List current alert states.

alerts

array

Array of alert state objects

firing_count

number

Number of currently firing alerts

const result = await invoke('engine::alerts::list', {});
// { alerts: [...], firing_count: 2, timestamp: ... }

engine::alerts::evaluate

Manually trigger alert evaluation.

evaluated

boolean

Whether evaluation occurred

triggered_alerts

array

Array of alerts that triggered

const result = await invoke('engine::alerts::evaluate', {});
// { evaluated: true, triggered_alerts: [...], timestamp: ... }

Error Handling

All built-in functions return errors in a consistent format:

{
  code: "error_code",
  message: "Human-readable error message"
}

Common error codes:

memory_exporter_not_enabled - Trace/log storage not available
serialization_error - Failed to serialize response data
invalid_input - Invalid input parameters

Best Practices

Use Internal Filtering

Set include_internal: false when querying functions, triggers, or traces to exclude engine internals from results.

Batch KV Operations

Use kv_server::update with multiple operations instead of multiple set calls for better performance.

Monitor Memory Usage

When using memory exporters, regularly clear old traces and logs to prevent memory growth.

Use Structured Logging

Always include the data parameter with structured attributes in log functions for better queryability.

Modules Overview

Learn about iii framework modules

Observability

Configure OTEL and monitoring

State Management

Using the KV store for state

Custom Modules

Creating custom modules

Get Started

Core Concepts

Modules

SDKs

Deployment

Advanced

​Worker Module Functions

​engine::channels::create

​engine::functions::list

​engine::workers::list

​engine::triggers::list

​engine::workers::register

​KV Server Functions

​kv_server::get

​kv_server::set

​kv_server::delete

​kv_server::update

​kv_server::list

​kv_server::list_keys_with_prefix

​Observability Functions

​Logging Functions

​engine::log::info

​engine::log::warn

​engine::log::error

​engine::log::debug

​engine::log::trace

​Baggage Functions

​engine::baggage::get

​engine::baggage::set

​engine::baggage::get_all

​Traces Functions

​engine::traces::list

​engine::traces::tree

​engine::traces::clear

​Metrics Functions

​engine::metrics::list

​engine::rollups::list

​Logs Functions

​engine::logs::list

​engine::logs::clear

​Health and Diagnostics

​engine::health::check

​engine::sampling::rules

​Alerts Functions

​engine::alerts::list

​engine::alerts::evaluate

​Error Handling

​Best Practices

Use Internal Filtering

Batch KV Operations

Monitor Memory Usage

Use Structured Logging

​Related Resources

Modules Overview

Observability

State Management

Custom Modules

Build docs developers (and LLMs) love

Worker Module Functions

engine::channels::create

engine::functions::list

engine::workers::list

engine::triggers::list

engine::workers::register

KV Server Functions

kv_server::get

kv_server::set

kv_server::delete

kv_server::update

kv_server::list

kv_server::list_keys_with_prefix

Observability Functions

Logging Functions

engine::log::info

engine::log::warn

engine::log::error

engine::log::debug

engine::log::trace

Baggage Functions

engine::baggage::get

engine::baggage::set

engine::baggage::get_all

Traces Functions

engine::traces::list

engine::traces::tree

engine::traces::clear

Metrics Functions

engine::metrics::list

engine::rollups::list

Logs Functions

engine::logs::list

engine::logs::clear

Health and Diagnostics

engine::health::check

engine::sampling::rules

Alerts Functions

engine::alerts::list

engine::alerts::evaluate

Error Handling

Best Practices

Related Resources