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.

number

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

StreamChannelRef

Writer channel reference for sending data

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.

boolean

default:false

Include internal engine functions (engine.* prefix)

array

Array of function information objects

Show FunctionInfo fields

string

Function identifier

string

Function description

object

Request schema (JSON Schema)

object

Response schema (JSON Schema)

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.

string

Filter by specific worker ID

array

Array of worker information objects

Show WorkerInfo fields

string

Worker unique identifier

string

Worker name

string

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

string

Worker version

string

Operating system

string

IP address

string

Worker status

number

Connection timestamp (milliseconds)

number

Number of registered functions

array

Array of function IDs

number

Current active invocations

object

Latest worker metrics

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.

boolean

default:false

Include internal engine triggers

array

Array of trigger information objects

Show TriggerInfo fields

string

Trigger unique identifier

string

Type of trigger

string

Target function ID

object

Trigger configuration

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

engine::workers::register

string

required

Worker ID (automatically injected)

string

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

string

Worker version

string

Worker name

string

Operating system information

object

Telemetry metadata

Show WorkerTelemetryMeta fields

string

Language/locale

string

Project name

string

Framework name

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.

string

required

Index name (namespace)

string

required

Key to retrieve

any

The stored value, or null if not found

const value = await invoke('kv_server::get', {
  index: 'users',
  key: 'user:123'
});
// { name: "Alice", email: "alice@example.com" }

kv_server::set

Set a value by key in the KV store.

string

required

Index name (namespace)

string

required

Key to set

any

required

Value to store (any JSON-serializable data)

string

The key that was set

any

The value that was stored

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: 'alice@example.com' }
});
// { key: "user:123", value: {...}, created: true }

kv_server::delete

Delete a value by key from the KV store.

string

required

Index name (namespace)

string

required

Key to delete

boolean

Whether the key was deleted

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.

string

required

Index name (namespace)

string

required

Key to update

array

required

Array of update operations

any

The value before the update

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.

string

required

Index name (namespace)

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.

string

required

Key prefix to filter by

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.

string

required

Log message

object

Structured data/attributes

string

Trace ID for correlation

string

Span ID for correlation

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.

string

required

Baggage key to retrieve

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.

string

required

Baggage key to set

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.

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.

string

Filter by specific trace ID

number

default:0

Pagination offset

number

default:100

Maximum number of spans to return

string

Filter by service name (substring match)

string

Filter by span name (substring match)

string

Filter by status (substring match)

number

Minimum span duration in milliseconds

number

Maximum span duration in milliseconds

number

Start time in Unix timestamp milliseconds

number

End time in Unix timestamp milliseconds

string

default:"start_time"

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

string

default:"asc"

Sort order: “asc” or “desc”

array

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

boolean

default:false

Include internal engine traces

array

Array of span objects

number

Total number of matching spans

number

Current offset

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.

string

required

Trace ID to build the tree for

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.

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.

number

Start time in Unix timestamp milliseconds

number

End time in Unix timestamp milliseconds

string

Filter by metric name

number

Aggregate interval in seconds

object

Engine internal metrics

Show Engine metrics structure

object

Function invocation counters

object

Worker lifecycle counters

object

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

array

SDK-recorded metrics

array

Time-aggregated metrics (if aggregate_interval specified)

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.

number

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

number

End time in Unix timestamp milliseconds (default: now)

number

default:0

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

string

Filter by metric name

array

Array of metric rollups

array

Array of histogram rollups

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.

string

Filter by trace ID

string

Filter by span ID

number

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

string

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

number

Start time in Unix timestamp milliseconds

number

End time in Unix timestamp milliseconds

number

Pagination offset

number

Maximum number of logs to return

array

Array of log entries

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.

boolean

Clear operation success status

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

Health and Diagnostics

engine::health::check

Check system health status.

string

Overall health status

object

Health status of individual components

Show Component structure

object

OTEL configuration status

object

Metrics storage status

object

Logs storage status

object

Spans storage status

number

Check timestamp

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.

object

Trace sampling configuration

Show Traces sampling

number

Default sampling ratio (0.0-1.0)

array

Per-operation sampling rules

boolean

Whether to respect parent sampling decisions

object

Log sampling configuration

Show Logs sampling

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.

array

Array of alert state objects

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.

boolean

Whether evaluation occurred

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

​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

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