> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/iii-hq/sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    type InitOptions = {
      workerName?: string
      enableMetricsReporting?: boolean
      invocationTimeoutMs?: number
      reconnectionConfig?: Partial<IIIReconnectionConfig>
      otel?: Omit<OtelConfig, 'engineWsUrl'>
      telemetry?: TelemetryOptions
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    @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
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // 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 { ... });
    ```
  </Tab>
</Tabs>

## Fields

<ParamField name="workerName" type="string">
  Custom name for this worker instance. Useful for identifying workers in logs and dashboards.

  **Default**: `hostname:pid` (e.g., `myserver:12345`)
</ParamField>

<ParamField name="enableMetricsReporting" type="boolean">
  Whether to enable automatic metrics collection and reporting for this worker.

  **Default**: `true`
</ParamField>

<ParamField name="invocationTimeoutMs" type="number">
  Default timeout in milliseconds for function invocations. Can be overridden per-invocation.

  **Default**: `30000` (30 seconds)
</ParamField>

<ParamField name="reconnectionConfig" type="ReconnectionConfig">
  Configuration for WebSocket reconnection behavior. See [ReconnectionConfig](/api/config/reconnection) for details.

  **Default**: Exponential backoff starting at 1s, max 30s, infinite retries
</ParamField>

<ParamField name="otel" type="OtelConfig">
  OpenTelemetry configuration. OTel is initialized automatically by default. See [OtelConfig](/api/config/otel-config) for details.

  **Default**: Enabled with automatic engine URL detection
</ParamField>

<ParamField name="telemetry" type="TelemetryOptions">
  Additional telemetry metadata to report to the engine.

  ```typescript theme={null}
  type TelemetryOptions = {
    language?: string
    project_name?: string
    framework?: string
    amplitude_api_key?: string
  }
  ```
</ParamField>

## Usage Examples

### Basic Initialization

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { init } from '@iii/sdk'

    const iii = init('ws://localhost:49134')
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from iii import III

    iii = III('ws://localhost:49134')
    await iii.connect()
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use iii::III;

    let iii = III::new("ws://localhost:49134");
    iii.connect().await?;
    ```
  </Tab>
</Tabs>

### Custom Worker Name

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const iii = init('ws://localhost:49134', {
      workerName: 'payment-processor-1'
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    iii = III('ws://localhost:49134', InitOptions(
        worker_name='payment-processor-1'
    ))
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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);
    ```
  </Tab>
</Tabs>

### Custom Timeout

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const iii = init('ws://localhost:49134', {
      invocationTimeoutMs: 60000 // 60 seconds
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    iii = III('ws://localhost:49134', InitOptions(
        invocation_timeout_ms=60000  # 60 seconds
    ))
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // In Rust, timeout is specified per-invocation:
    let result = iii.trigger_with_timeout(
        "function::id",
        json!({ "data": "value" }),
        Duration::from_secs(60)
    ).await?;
    ```
  </Tab>
</Tabs>

### Disable Telemetry

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const iii = init('ws://localhost:49134', {
      otel: {
        enabled: false
      }
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from iii.telemetry_types import OtelConfig

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

  <Tab title="Rust">
    ```rust theme={null}
    let config = OtelConfig {
        enabled: Some(false),
        ..Default::default()
    };

    let iii = III::new("ws://localhost:49134");
    iii.set_otel_config(config);
    ```
  </Tab>
</Tabs>

### Custom Reconnection Behavior

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const iii = init('ws://localhost:49134', {
      reconnectionConfig: {
        initialDelayMs: 500,
        maxDelayMs: 10000,
        backoffMultiplier: 1.5,
        maxRetries: 10
      }
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    iii = III('ws://localhost:49134', InitOptions(
        reconnection_config=ReconnectionConfig(
            initial_delay_ms=500,
            max_delay_ms=10000,
            backoff_multiplier=1.5,
            max_retries=10
        )
    ))
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // 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);
    ```
  </Tab>
</Tabs>

### Full Configuration

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    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'
      }
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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?;
    ```
  </Tab>
</Tabs>

## 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](/api/config/reconnection)
* [OtelConfig](/api/config/otel-config)
* [Getting Started](/quickstart)