feat(telemetry): add telemetry options to SDK init (#27)

- Node.js: Add TelemetryOptions to InitOptions, send in registerWorkerMetadata
- Python: Add TelemetryOptions to InitOptions, include in _get_worker_metadata
- Rust: Add WorkerTelemetryMeta to WorkerMetadata, auto-detect language from LANG

Author: ytallo

packages/node/iii/src/iii.ts

@@ -74,6 +74,13 @@ function getDefaultWorkerName(): string {
 /** Callback type for connection state changes */
 export type ConnectionStateCallback = (state: IIIConnectionState) => void
 
+export type TelemetryOptions = {
+  language?: string
+  project_name?: string
+  framework?: string
+  amplitude_api_key?: string
+}
+
 export type InitOptions = {
   workerName?: string
   enableMetricsReporting?: boolean
@@ -85,6 +92,7 @@ export type InitOptions = {
    * Set `{ enabled: false }` or env `OTEL_ENABLED=false/0/no/off` to disable.
    * The engineWsUrl is set automatically from the III address. */
   otel?: Omit<OtelConfig, 'engineWsUrl'>
+  telemetry?: TelemetryOptions
 }
 
 class Sdk implements ISdk {
@@ -114,7 +122,7 @@ class Sdk implements ISdk {
 
   constructor(
     private readonly address: string,
-    options?: InitOptions,
+    private readonly options?: InitOptions,
   ) {
     this.workerName = options?.workerName ?? getDefaultWorkerName()
     this.metricsReportingEnabled = options?.enableMetricsReporting ?? true
@@ -297,11 +305,23 @@ class Sdk implements ISdk {
   }
 
   private registerWorkerMetadata(): void {
+    const telemetryOpts = this.options?.telemetry
+    const language =
+      telemetryOpts?.language ??
+      Intl.DateTimeFormat().resolvedOptions().locale ??
+      process.env.LANG?.split('.')[0]
+
     this.triggerVoid(EngineFunctions.REGISTER_WORKER, {
       runtime: 'node',
       version: SDK_VERSION,
       name: this.workerName,
       os: getOsInfo(),
+      telemetry: {
+        language,
+        project_name: telemetryOpts?.project_name,
+        framework: telemetryOpts?.framework,
+        amplitude_api_key: telemetryOpts?.amplitude_api_key,
+      },
     })
   }
 

packages/python/iii/src/iii/iii.py

@@ -72,6 +72,16 @@ class FunctionRef:
     unregister: Callable[[], None]
 
 
+@dataclass
+class TelemetryOptions:
+    """Telemetry metadata to be reported to the engine."""
+
+    language: str | None = None
+    project_name: str | None = None
+    framework: str | None = None
+    amplitude_api_key: str | None = None
+
+
 @dataclass
 class InitOptions:
     """Options for configuring the III SDK."""
@@ -81,6 +91,7 @@ class InitOptions:
     invocation_timeout_ms: int = DEFAULT_INVOCATION_TIMEOUT_MS
     reconnection_config: ReconnectionConfig | None = None
     otel: dict[str, Any] | None = None
+    telemetry: TelemetryOptions | None = None
 
 
 class III:
@@ -593,11 +604,26 @@ def _get_worker_metadata(self) -> dict[str, Any]:
 
         worker_name = self._options.worker_name or f"{platform.node()}:{os.getpid()}"
 
+        telemetry_opts = self._options.telemetry
+        language = (
+            (telemetry_opts.language if telemetry_opts else None)
+            or os.environ.get("LANG", "").split(".")[0]
+            or None
+        )
+
+        telemetry: dict[str, Any] = {
+            "language": language,
+            "project_name": telemetry_opts.project_name if telemetry_opts else None,
+            "framework": telemetry_opts.framework if telemetry_opts else None,
+            "amplitude_api_key": telemetry_opts.amplitude_api_key if telemetry_opts else None,
+        }
+
         return {
             "runtime": "python",
             "version": sdk_version,
             "name": worker_name,
             "os": f"{platform.system()} {platform.release()} ({platform.machine()})",
+            "telemetry": telemetry,
         }
 
     def _register_worker_metadata(self) -> None:

packages/rust/iii/Cargo.lock

@@ -86,13 +86,28 @@ pub struct TriggerInfo {
     pub config: Value,
 }
 
+/// Telemetry metadata provided by the SDK to the engine.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct WorkerTelemetryMeta {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub language: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub project_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub framework: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub amplitude_api_key: Option<String>,
+}
+
 /// Worker metadata for auto-registration
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct WorkerMetadata {
     pub runtime: String,
     pub version: String,
     pub name: String,
     pub os: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub telemetry: Option<WorkerTelemetryMeta>,
 }
 
 impl Default for WorkerMetadata {
@@ -108,11 +123,21 @@ impl Default for WorkerMetadata {
             std::env::consts::FAMILY
         );
 
+        let language = std::env::var("LANG")
+            .or_else(|_| std::env::var("LC_ALL"))
+            .ok()
+            .filter(|s| !s.is_empty())
+            .map(|s| s.split('.').next().unwrap_or(&s).to_string());
+
         Self {
             runtime: "rust".to_string(),
             version: SDK_VERSION.to_string(),
             name: format!("{}:{}", hostname, pid),
             os: os_info,
+            telemetry: Some(WorkerTelemetryMeta {
+                language,
+                ..Default::default()
+            }),
         }
     }
 }