InitOptions

Configuration options for initializing the III SDK

The InitOptions type allows you to customize the behavior of the III SDK when connecting to the engine.

Type Definition

TypeScript

type InitOptions = {
  workerName?: string
  enableMetricsReporting?: boolean
  invocationTimeoutMs?: number
  reconnectionConfig?: Partial<IIIReconnectionConfig>
  otel?: Omit<OtelConfig, 'engineWsUrl'>
  telemetry?: TelemetryOptions
}

Python

@dataclass
class InitOptions:
    worker_name: str | None = None
    enable_metrics_reporting: bool = True
    invocation_timeout_ms: int = 30000
    reconnection_config: ReconnectionConfig | None = None
    otel: dict[str, Any] | None = None
    telemetry: TelemetryOptions | None = None

Rust

// In Rust, options are set via builder methods on the III instance:
let iii = III::new("ws://localhost:49134");
iii.set_metadata(WorkerMetadata { ... });
iii.set_otel_config(OtelConfig { ... });

Fields

Usage Examples

Basic Initialization

TypeScript

import { init } from '@iii/sdk'

const iii = init('ws://localhost:49134')

Python

from iii import III

iii = III('ws://localhost:49134')
await iii.connect()

Rust

use iii::III;

let iii = III::new("ws://localhost:49134");
iii.connect().await?;

Custom Worker Name

TypeScript

const iii = init('ws://localhost:49134', {
  workerName: 'payment-processor-1'
})

Python

iii = III('ws://localhost:49134', InitOptions(
    worker_name='payment-processor-1'
))

Rust

let metadata = WorkerMetadata {
    runtime: "rust".to_string(),
    version: env!("CARGO_PKG_VERSION").to_string(),
    name: "payment-processor-1".to_string(),
    os: std::env::consts::OS.to_string(),
    telemetry: None,
};

let iii = III::with_metadata("ws://localhost:49134", metadata);

Custom Timeout

TypeScript

const iii = init('ws://localhost:49134', {
  invocationTimeoutMs: 60000 // 60 seconds
})

Python

iii = III('ws://localhost:49134', InitOptions(
    invocation_timeout_ms=60000  # 60 seconds
))

Rust

// In Rust, timeout is specified per-invocation:
let result = iii.trigger_with_timeout(
    "function::id",
    json!({ "data": "value" }),
    Duration::from_secs(60)
).await?;

Disable Telemetry

TypeScript

const iii = init('ws://localhost:49134', {
  otel: {
    enabled: false
  }
})

Python

from iii.telemetry_types import OtelConfig

iii = III('ws://localhost:49134', InitOptions(
    otel={'enabled': False}
))

Rust

let config = OtelConfig {
    enabled: Some(false),
    ..Default::default()
};

let iii = III::new("ws://localhost:49134");
iii.set_otel_config(config);

Custom Reconnection Behavior

TypeScript

const iii = init('ws://localhost:49134', {
  reconnectionConfig: {
    initialDelayMs: 500,
    maxDelayMs: 10000,
    backoffMultiplier: 1.5,
    maxRetries: 10
  }
})

Python

iii = III('ws://localhost:49134', InitOptions(
    reconnection_config=ReconnectionConfig(
        initial_delay_ms=500,
        max_delay_ms=10000,
        backoff_multiplier=1.5,
        max_retries=10
    )
))

Rust

// Reconnection config is set via OtelConfig
let reconnection = ReconnectionConfig {
    initial_delay_ms: 500,
    max_delay_ms: 10000,
    backoff_multiplier: 1.5,
    jitter_factor: 0.3,
    max_retries: Some(10),
    max_pending_messages: 1000,
};

let config = OtelConfig {
    reconnection_config: Some(reconnection),
    ..Default::default()
};

let iii = III::new("ws://localhost:49134");
iii.set_otel_config(config);

Full Configuration

TypeScript

import { init } from '@iii/sdk'
import { PrismaInstrumentation } from '@prisma/instrumentation'

const iii = init('ws://localhost:49134', {
  workerName: 'api-server-1',
  enableMetricsReporting: true,
  invocationTimeoutMs: 30000,
  reconnectionConfig: {
    initialDelayMs: 1000,
    maxDelayMs: 30000,
    backoffMultiplier: 2,
    jitterFactor: 0.3,
    maxRetries: -1 // infinite
  },
  otel: {
    enabled: true,
    serviceName: 'my-api',
    serviceVersion: '1.0.0',
    serviceNamespace: 'production',
    instrumentations: [new PrismaInstrumentation()],
    metricsEnabled: true,
    metricsExportIntervalMs: 60000,
    fetchInstrumentationEnabled: true
  },
  telemetry: {
    language: 'en-US',
    project_name: 'my-project',
    framework: 'express'
  }
})

Python

from iii import III, InitOptions, ReconnectionConfig, TelemetryOptions
from iii.telemetry_types import OtelConfig

iii = III('ws://localhost:49134', InitOptions(
    worker_name='api-server-1',
    enable_metrics_reporting=True,
    invocation_timeout_ms=30000,
    reconnection_config=ReconnectionConfig(
        initial_delay_ms=1000,
        max_delay_ms=30000,
        backoff_multiplier=2.0,
        jitter_factor=0.3,
        max_retries=-1  # infinite
    ),
    otel=OtelConfig(
        enabled=True,
        service_name='my-api',
        service_version='1.0.0',
        service_namespace='production',
        metrics_enabled=True,
        metrics_export_interval_ms=60000,
        fetch_instrumentation_enabled=True
    ),
    telemetry=TelemetryOptions(
        language='en-US',
        project_name='my-project',
        framework='fastapi'
    )
))

await iii.connect()

Rust

use iii::{III, WorkerMetadata, WorkerTelemetryMeta};
use iii::telemetry::types::{OtelConfig, ReconnectionConfig};

let metadata = WorkerMetadata {
    runtime: "rust".to_string(),
    version: env!("CARGO_PKG_VERSION").to_string(),
    name: "api-server-1".to_string(),
    os: std::env::consts::OS.to_string(),
    telemetry: Some(WorkerTelemetryMeta {
        language: Some("en-US".to_string()),
        project_name: Some("my-project".to_string()),
        framework: Some("axum".to_string()),
        amplitude_api_key: None,
    }),
};

let reconnection = ReconnectionConfig {
    initial_delay_ms: 1000,
    max_delay_ms: 30000,
    backoff_multiplier: 2.0,
    jitter_factor: 0.3,
    max_retries: None,  // infinite
    max_pending_messages: 1000,
};

let otel = OtelConfig {
    enabled: Some(true),
    service_name: Some("my-api".to_string()),
    service_version: Some("1.0.0".to_string()),
    service_namespace: Some("production".to_string()),
    engine_ws_url: None,  // auto-detected
    metrics_enabled: Some(true),
    metrics_export_interval_ms: Some(60000),
    reconnection_config: Some(reconnection),
    fetch_instrumentation_enabled: Some(true),
    logs_enabled: Some(true),
    shutdown_timeout_ms: Some(10000),
    channel_capacity: Some(10000),
};

let iii = III::with_metadata("ws://localhost:49134", metadata);
iii.set_otel_config(otel);
iii.connect().await?;

Environment Variables

Many options can also be configured via environment variables:

• III_BRIDGE_URL - Engine WebSocket URL
• OTEL_ENABLED - Enable/disable OpenTelemetry (true/false)
• OTEL_SERVICE_NAME - Service name for telemetry
• SERVICE_VERSION - Service version
• SERVICE_NAMESPACE - Service namespace
• SERVICE_INSTANCE_ID - Service instance ID
• OTEL_METRICS_ENABLED - Enable/disable metrics

Related

• ReconnectionConfig
• OtelConfig
• Getting Started