> ## 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.

# OtelConfig

> OpenTelemetry configuration for observability

The `OtelConfig` type configures OpenTelemetry integration for distributed tracing, metrics, and logs.

## Type Definition

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    interface OtelConfig {
      enabled?: boolean
      serviceName?: string
      serviceVersion?: string
      serviceNamespace?: string
      serviceInstanceId?: string
      engineWsUrl?: string
      instrumentations?: Instrumentation[]
      metricsEnabled?: boolean
      metricsExportIntervalMs?: number
      fetchInstrumentationEnabled?: boolean
      reconnectionConfig?: Partial<ReconnectionConfig>
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    @dataclass
    class OtelConfig:
        enabled: bool | None = None
        service_name: str | None = None
        service_version: str | None = None
        service_namespace: str | None = None
        service_instance_id: str | None = None
        engine_ws_url: str | None = None
        fetch_instrumentation_enabled: bool = True
        logs_enabled: bool | None = None
        metrics_enabled: bool = True
        metrics_export_interval_ms: int = 60000
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    pub struct OtelConfig {
        pub enabled: Option<bool>,
        pub service_name: Option<String>,
        pub service_version: Option<String>,
        pub service_namespace: Option<String>,
        pub service_instance_id: Option<String>,
        pub engine_ws_url: Option<String>,
        pub metrics_enabled: Option<bool>,
        pub metrics_export_interval_ms: Option<u64>,
        pub reconnection_config: Option<ReconnectionConfig>,
        pub shutdown_timeout_ms: Option<u64>,
        pub channel_capacity: Option<usize>,
        pub logs_enabled: Option<bool>,
        pub fetch_instrumentation_enabled: Option<bool>,
    }
    ```
  </Tab>
</Tabs>

## Fields

<ParamField name="enabled" type="boolean" default="true">
  Whether OpenTelemetry export is enabled.

  Set to `false` or env `OTEL_ENABLED=false/0/no/off` to disable.
</ParamField>

<ParamField name="serviceName" type="string" default="iii-{language}">
  The service name to report in telemetry data.

  **Default values**:

  * TypeScript: `iii-node`
  * Python: `iii-python-sdk`
  * Rust: `iii-rust-sdk`

  Can be set via `OTEL_SERVICE_NAME` environment variable.
</ParamField>

<ParamField name="serviceVersion" type="string" default="unknown">
  The service version to report.

  Can be set via `SERVICE_VERSION` environment variable.
</ParamField>

<ParamField name="serviceNamespace" type="string">
  The service namespace (e.g., `production`, `staging`, `dev`).

  Can be set via `SERVICE_NAMESPACE` environment variable.
</ParamField>

<ParamField name="serviceInstanceId" type="string" default="auto-generated UUID">
  Unique identifier for this service instance.

  Can be set via `SERVICE_INSTANCE_ID` environment variable.
</ParamField>

<ParamField name="engineWsUrl" type="string" default="ws://localhost:49134">
  III Engine WebSocket URL for exporting telemetry.

  **Note**: When using `InitOptions`, this is automatically set from the III address.

  Can be set via `III_BRIDGE_URL` environment variable.
</ParamField>

<ParamField name="instrumentations" type="Instrumentation[]">
  **TypeScript only**: OpenTelemetry instrumentations to register.

  ```typescript theme={null}
  import { PrismaInstrumentation } from '@prisma/instrumentation'

  otel: {
    instrumentations: [new PrismaInstrumentation()]
  }
  ```
</ParamField>

<ParamField name="metricsEnabled" type="boolean" default="true">
  Whether OpenTelemetry metrics export is enabled.

  Set to `false` or env `OTEL_METRICS_ENABLED=false/0/no/off` to disable.
</ParamField>

<ParamField name="metricsExportIntervalMs" type="number" default="60000">
  Metrics export interval in milliseconds (60 seconds).
</ParamField>

<ParamField name="fetchInstrumentationEnabled" type="boolean" default="true">
  Whether to auto-instrument HTTP calls.

  * **TypeScript**: Instruments `globalThis.fetch` (works on Node.js, Bun, Deno)
  * **Python**: Instruments `urllib` via `URLLibInstrumentor`
  * **Rust**: Instruments `reqwest` via `execute_traced_request()`
</ParamField>

<ParamField name="logsEnabled" type="boolean" default="true">
  **Python/Rust only**: Whether to enable the log exporter.

  When enabled, logs are exported to the III Engine via OpenTelemetry.
</ParamField>

<ParamField name="reconnectionConfig" type="ReconnectionConfig">
  **TypeScript/Rust only**: Configuration for WebSocket reconnection behavior.

  See [ReconnectionConfig](/api/config/reconnection) for details.
</ParamField>

<ParamField name="shutdownTimeoutMs" type="number" default="10000">
  **Rust only**: Timeout in milliseconds for the shutdown sequence.
</ParamField>

<ParamField name="channelCapacity" type="number" default="10000">
  **Rust only**: Capacity of the internal telemetry message channel.

  Controls the in-flight message buffer between exporters and the WebSocket connection loop.
</ParamField>

## Default Configuration

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const DEFAULT_OTEL_CONFIG = {
      enabled: true,
      serviceName: 'iii-node',
      serviceVersion: 'unknown',
      engineWsUrl: 'ws://localhost:49134',
      metricsEnabled: true,
      metricsExportIntervalMs: 60000,
      fetchInstrumentationEnabled: true,
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Defaults are set in OtelConfig dataclass
    OtelConfig(
        enabled=None,  # defaults to True
        service_name=None,  # defaults to 'iii-python-sdk'
        service_version=None,  # defaults to 'unknown'
        metrics_enabled=True,
        metrics_export_interval_ms=60000,
        fetch_instrumentation_enabled=True
    )
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    impl Default for OtelConfig {
        fn default() -> Self {
            Self {
                enabled: None,  // defaults to true
                service_name: None,  // defaults to "iii-rust-sdk"
                service_version: None,  // defaults to "unknown"
                service_namespace: None,
                service_instance_id: None,
                engine_ws_url: None,  // auto-detected
                metrics_enabled: None,  // defaults to true
                metrics_export_interval_ms: Some(60000),
                reconnection_config: None,
                shutdown_timeout_ms: Some(10000),
                channel_capacity: Some(10000),
                logs_enabled: None,  // defaults to true
                fetch_instrumentation_enabled: None,  // defaults to true
            }
        }
    }
    ```
  </Tab>
</Tabs>

## Usage Examples

### Basic Telemetry Setup

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

    const iii = init('ws://localhost:49134', {
      otel: {
        serviceName: 'my-api',
        serviceVersion: '1.0.0',
        serviceNamespace: 'production'
      }
    })
    ```
  </Tab>

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

    iii = III('ws://localhost:49134', InitOptions(
        otel=OtelConfig(
            service_name='my-api',
            service_version='1.0.0',
            service_namespace='production'
        )
    ))
    ```
  </Tab>

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

    let config = OtelConfig {
        service_name: Some("my-api".to_string()),
        service_version: Some("1.0.0".to_string()),
        service_namespace: Some("production".to_string()),
        ..Default::default()
    };

    let iii = III::new("ws://localhost:49134");
    iii.set_otel_config(config);
    ```
  </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}
    iii = III('ws://localhost:49134', InitOptions(
        otel=OtelConfig(enabled=False)
    ))
    ```
  </Tab>

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

    iii.set_otel_config(config);
    ```
  </Tab>
</Tabs>

### Custom Metrics Interval

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const iii = init('ws://localhost:49134', {
      otel: {
        metricsEnabled: true,
        metricsExportIntervalMs: 30000  // 30 seconds
      }
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    iii = III('ws://localhost:49134', InitOptions(
        otel=OtelConfig(
            metrics_enabled=True,
            metrics_export_interval_ms=30000  # 30 seconds
        )
    ))
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let config = OtelConfig {
        metrics_enabled: Some(true),
        metrics_export_interval_ms: Some(30000),  // 30 seconds
        ..Default::default()
    };
    ```
  </Tab>
</Tabs>

### With Custom Instrumentation (TypeScript)

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { init } from '@iii/sdk'
    import { PrismaInstrumentation } from '@prisma/instrumentation'
    import { HttpInstrumentation } from '@opentelemetry/instrumentation-http'

    const iii = init('ws://localhost:49134', {
      otel: {
        serviceName: 'my-api',
        instrumentations: [
          new PrismaInstrumentation(),
          new HttpInstrumentation()
        ]
      }
    })
    ```
  </Tab>
</Tabs>

### Disable HTTP Auto-Instrumentation

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

  <Tab title="Python">
    ```python theme={null}
    iii = III('ws://localhost:49134', InitOptions(
        otel=OtelConfig(
            fetch_instrumentation_enabled=False
        )
    ))
    ```
  </Tab>

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

### Full Configuration

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

    const iii = init('ws://localhost:49134', {
      otel: {
        enabled: true,
        serviceName: 'my-api',
        serviceVersion: '1.0.0',
        serviceNamespace: 'production',
        serviceInstanceId: 'instance-1',
        instrumentations: [],
        metricsEnabled: true,
        metricsExportIntervalMs: 60000,
        fetchInstrumentationEnabled: true,
        reconnectionConfig: {
          initialDelayMs: 1000,
          maxDelayMs: 30000,
          backoffMultiplier: 2,
          jitterFactor: 0.3,
          maxRetries: -1
        }
      }
    })
    ```
  </Tab>

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

    iii = III('ws://localhost:49134', InitOptions(
        otel=OtelConfig(
            enabled=True,
            service_name='my-api',
            service_version='1.0.0',
            service_namespace='production',
            service_instance_id='instance-1',
            engine_ws_url='ws://localhost:49134',
            fetch_instrumentation_enabled=True,
            logs_enabled=True,
            metrics_enabled=True,
            metrics_export_interval_ms=60000
        )
    ))
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use iii::telemetry::types::{OtelConfig, ReconnectionConfig};

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

    let config = 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()),
        service_instance_id: Some("instance-1".to_string()),
        engine_ws_url: Some("ws://localhost:49134".to_string()),
        metrics_enabled: Some(true),
        metrics_export_interval_ms: Some(60000),
        reconnection_config: Some(reconnection),
        shutdown_timeout_ms: Some(10000),
        channel_capacity: Some(10000),
        logs_enabled: Some(true),
        fetch_instrumentation_enabled: Some(true),
    };

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

## Environment Variables

OpenTelemetry configuration can be controlled via environment variables:

* `OTEL_ENABLED` - Enable/disable OTel (true/false/0/1/yes/no/on/off)
* `OTEL_SERVICE_NAME` - Service name
* `SERVICE_VERSION` - Service version
* `SERVICE_NAMESPACE` - Service namespace
* `SERVICE_INSTANCE_ID` - Service instance ID
* `III_BRIDGE_URL` - Engine WebSocket URL
* `OTEL_METRICS_ENABLED` - Enable/disable metrics

**Example**:

```bash theme={null}
export OTEL_SERVICE_NAME=my-api
export SERVICE_VERSION=1.0.0
export SERVICE_NAMESPACE=production
export OTEL_METRICS_ENABLED=true
```

## Observability Features

### Distributed Tracing

All function invocations are automatically traced with W3C trace context propagation:

* Parent-child span relationships across workers
* Automatic trace ID and span ID generation
* Baggage propagation for custom context

### Metrics

Automatic metrics collection:

* Function invocation count
* Function duration
* Error rate
* Active invocations
* Worker status

### Logs

Structured logging with trace correlation:

* All logs include trace ID and span ID
* Automatic severity level detection
* Resource attributes (service name, version, etc.)

## Best Practices

1. **Always set service metadata**: Provide meaningful `serviceName`, `serviceVersion`, and `serviceNamespace`
2. **Use environment variables**: Configure via env vars for easier deployment
3. **Production monitoring**: Keep telemetry enabled in production for observability
4. **Custom instrumentation**: Add framework-specific instrumentations (Prisma, Express, etc.)
5. **Metrics tuning**: Adjust export interval based on traffic volume

## Related

* [InitOptions](/api/config/init-options)
* [ReconnectionConfig](/api/config/reconnection)
* [Observability Guide](/guides/observability)