OtelConfig - III SDK

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

Type Definition

TypeScript
Python
Rust

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>
}

@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

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>,
}

Fields

Default Configuration

TypeScript
Python
Rust

const DEFAULT_OTEL_CONFIG = {
  enabled: true,
  serviceName: 'iii-node',
  serviceVersion: 'unknown',
  engineWsUrl: 'ws://localhost:49134',
  metricsEnabled: true,
  metricsExportIntervalMs: 60000,
  fetchInstrumentationEnabled: true,
}

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

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
        }
    }
}

Usage Examples

Basic Telemetry Setup

TypeScript
Python
Rust

import { init } from '@iii/sdk'

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

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'
    )
))

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);

Disable Telemetry

TypeScript
Python
Rust

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

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

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

iii.set_otel_config(config);

Custom Metrics Interval

TypeScript
Python
Rust

const iii = init('ws://localhost:49134', {
  otel: {
    metricsEnabled: true,
    metricsExportIntervalMs: 30000  // 30 seconds
  }
})

iii = III('ws://localhost:49134', InitOptions(
    otel=OtelConfig(
        metrics_enabled=True,
        metrics_export_interval_ms=30000  # 30 seconds
    )
))

let config = OtelConfig {
    metrics_enabled: Some(true),
    metrics_export_interval_ms: Some(30000),  // 30 seconds
    ..Default::default()
};

With Custom Instrumentation (TypeScript)

TypeScript

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()
    ]
  }
})

Disable HTTP Auto-Instrumentation

TypeScript
Python
Rust

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

iii = III('ws://localhost:49134', InitOptions(
    otel=OtelConfig(
        fetch_instrumentation_enabled=False
    )
))

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

Full Configuration

TypeScript
Python
Rust

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
    }
  }
})

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
    )
))

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);

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:

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

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

​Type Definition

​Fields

​Default Configuration

​Usage Examples

​Basic Telemetry Setup

​Disable Telemetry

​Custom Metrics Interval

​With Custom Instrumentation (TypeScript)

​Disable HTTP Auto-Instrumentation

​Full Configuration

​Environment Variables

​Observability Features

​Distributed Tracing

​Metrics

​Logs

​Best Practices

​Related