Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
use rand::RngCore;
use reqwest::blocking::Client;
use reqwest::redirect::Policy;
use serde::{Deserialize, Serialize};
use std::env;
use std::fs;
use std::io;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use std::thread::sleep;
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
pub const STATE_SCHEMA_VERSION: u8 = 1;
const STATE_FILE: &str = "telemetry-state.json";
const REQUEST_TIMEOUT: Duration = Duration::from_secs(3);
const FLUSH_BUDGET: Duration = Duration::from_secs(6);
pub type Result<T> = std::result::Result<T, TelemetryError>;
#[derive(Debug)]
pub enum TelemetryError {
Io(io::Error),
Json(serde_json::Error),
Http(reqwest::Error),
MissingEndpoint,
InvalidState(String),
Poisoned,
}
impl From<io::Error> for TelemetryError {
fn from(error: io::Error) -> Self {
Self::Io(error)
}
}
impl From<serde_json::Error> for TelemetryError {
fn from(error: serde_json::Error) -> Self {
Self::Json(error)
}
}
impl From<reqwest::Error> for TelemetryError {
fn from(error: reqwest::Error) -> Self {
Self::Http(error)
}
}
impl std::fmt::Display for TelemetryError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Io(error) => write!(formatter, "telemetry I/O error: {error}"),
Self::Json(error) => write!(formatter, "telemetry JSON error: {error}"),
Self::Http(error) => write!(formatter, "telemetry HTTP error: {error}"),
Self::MissingEndpoint => formatter.write_str("telemetry endpoint is missing"),
Self::InvalidState(error) => write!(formatter, "invalid telemetry state: {error}"),
Self::Poisoned => formatter.write_str("telemetry state lock is poisoned"),
}
}
}
impl std::error::Error for TelemetryError {}
#[derive(Debug, Clone)]
pub struct Config {
pub enabled: bool,
pub endpoint: Option<String>,
pub max_queue: usize,
}
impl Config {
pub fn disabled_for_tests() -> Self {
Self {
enabled: true,
endpoint: None,
max_queue: 256,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EnvOverride {
Process,
Enabled,
Disabled,
}
#[derive(Debug)]
pub struct Telemetry {
state_path: PathBuf,
context: Mutex<Context>,
config: Config,
state: Mutex<Option<PersistedState>>,
session_last_step_viewed: Mutex<Option<Step>>,
flush_lock: Mutex<()>,
client: Client,
}
impl Telemetry {
pub fn open(data_dir: impl AsRef<Path>, context: Context, config: Config) -> Result<Arc<Self>> {
Self::open_with_env(data_dir, context, config, EnvOverride::Process)
}
pub fn open_with_env(
data_dir: impl AsRef<Path>,
context: Context,
config: Config,
env_override: EnvOverride,
) -> Result<Arc<Self>> {
let state_path = state_path(data_dir.as_ref());
if telemetry_disabled(env_override) || !config.enabled {
let _ = fs::remove_file(&state_path);
return Ok(Arc::new(Self::disabled(state_path, context, config)?));
}
fs::create_dir_all(data_dir.as_ref())?;
let mut state = if state_path.exists() {
let state = serde_json::from_slice::<PersistedState>(&fs::read(&state_path)?)?;
state.validate()?;
state
} else {
PersistedState::new(new_uuid())
};
if !state.activated {
if let Some(step) = state.last_step.take() {
state.push_bounded(
Event::new(EventData::SetupAbandoned { step }, context.clone()),
normalized_max_queue(config.max_queue),
);
}
}
write_state(&state_path, &state)?;
Ok(Arc::new(Self {
state_path,
context: Mutex::new(context),
config,
state: Mutex::new(Some(state)),
session_last_step_viewed: Mutex::new(None),
flush_lock: Mutex::new(()),
client: client()?,
}))
}
fn disabled(state_path: PathBuf, context: Context, config: Config) -> Result<Self> {
Ok(Self {
state_path,
context: Mutex::new(context),
config,
state: Mutex::new(None),
session_last_step_viewed: Mutex::new(None),
flush_lock: Mutex::new(()),
client: client()?,
})
}
pub fn install_id(&self) -> Option<String> {
self.state
.lock()
.ok()
.and_then(|guard| guard.as_ref().map(|state| state.install_id.clone()))
}
pub fn update_engine(&self, engine: Engine) -> Result<()> {
let mut context = self.context.lock().map_err(|_| TelemetryError::Poisoned)?;
context.engine = engine;
Ok(())
}
/// The exact process environment the desktop gives to Bun before runtime imports.
pub fn runtime_env(&self) -> std::collections::BTreeMap<String, String> {
let mut env = std::collections::BTreeMap::new();
let Some(id) = self.install_id() else {
env.insert("COPILOTKIT_TELEMETRY_DISABLED".into(), "1".into());
return env;
};
let Ok(context) = self.context.lock() else {
return env;
};
env.insert("CPK_TELEMETRY_ID".into(), id);
env.insert("COPILOTKIT_TELEMETRY_SAMPLE_RATE".into(), "1".into());
env.insert(
"OPENBOT_DISTRIBUTION".into(),
context.distribution.as_str().into(),
);
env.insert("OPENBOT_VERSION".into(), context.app_version.to_string());
env.insert("OPENBOT_PLATFORM".into(), context.platform.as_str().into());
env.insert("OPENBOT_ARCH".into(), context.arch.as_str().into());
env.insert("OPENBOT_ENGINE".into(), context.engine.as_str().into());
if let Some(version) = &context.os_version {
env.insert("OPENBOT_OS_VERSION".into(), version.to_string());
}
env
}
pub fn record(&self, data: EventData) -> Result<()> {
let context = self
.context
.lock()
.map_err(|_| TelemetryError::Poisoned)?
.clone();
let mut guard = self.state.lock().map_err(|_| TelemetryError::Poisoned)?;
let Some(state) = guard.as_mut() else {
return Ok(());
};
match &data {
EventData::StepViewed { step } => {
let mut last_step = self
.session_last_step_viewed
.lock()
.map_err(|_| TelemetryError::Poisoned)?;
if *last_step == Some(*step) {
return Ok(());
}
*last_step = Some(*step);
state.last_step = Some(*step);
}
EventData::Activated => {
if state.activated {
return Ok(());
}
state.activated = true;
state.last_step = None;
*self
.session_last_step_viewed
.lock()
.map_err(|_| TelemetryError::Poisoned)? = None;
}
EventData::SetupAbandoned { .. } => {
if state.activated {
return Ok(());
}
state.last_step = None;
*self
.session_last_step_viewed
.lock()
.map_err(|_| TelemetryError::Poisoned)? = None;
}
_ => {
*self
.session_last_step_viewed
.lock()
.map_err(|_| TelemetryError::Poisoned)? = None;
}
}
state.push_bounded(
Event::new(data, context),
normalized_max_queue(self.config.max_queue),
);
write_state(&self.state_path, state)
}
pub fn flush(&self) -> Result<()> {
self.flush_with_lock_wait(Duration::ZERO)
}
fn flush_with_lock_wait(&self, lock_wait: Duration) -> Result<()> {
let started = Instant::now();
let flush_guard = loop {
match self.flush_lock.try_lock() {
Ok(guard) => break guard,
Err(_) if started.elapsed() < lock_wait => sleep(Duration::from_millis(10)),
Err(_) => return Ok(()),
}
};
let _flush_guard = flush_guard;
let endpoint = match self.config.endpoint.as_ref() {
Some(endpoint) if !endpoint.trim().is_empty() => endpoint,
_ => return Ok(()),
};
loop {
if started.elapsed() >= FLUSH_BUDGET {
return Ok(());
}
let (install_id, event) = {
let guard = self.state.lock().map_err(|_| TelemetryError::Poisoned)?;
let Some(state) = guard.as_ref() else {
return Ok(());
};
let Some(event) = state.queue.first().cloned() else {
return Ok(());
};
(state.install_id.clone(), event)
};
let response = self
.client
.post(endpoint)
.header("X-CopilotKit-Telemetry-Id", &install_id)
.json(&event.to_sink_payload())
.send();
match response {
Ok(response) if response.status().is_success() => {
let mut guard = self.state.lock().map_err(|_| TelemetryError::Poisoned)?;
if let Some(state) = guard.as_mut() {
if let Some(index) = state
.queue
.iter()
.position(|queued| queued.event_id == event.event_id)
{
state.queue.remove(index);
write_state(&self.state_path, state)?;
}
}
}
Ok(_) => return Ok(()),
Err(error) => return Err(TelemetryError::Http(error)),
}
}
}
pub fn shutdown(&self) -> Result<()> {
let step = {
let guard = self.state.lock().map_err(|_| TelemetryError::Poisoned)?;
guard
.as_ref()
.and_then(|state| (!state.activated).then_some(state.last_step).flatten())
};
if let Some(step) = step {
self.record(EventData::SetupAbandoned { step })?;
}
self.flush_with_lock_wait(FLUSH_BUDGET)
}
pub fn snapshot(&self) -> Result<PersistedState> {
self.state
.lock()
.map_err(|_| TelemetryError::Poisoned)?
.clone()
.ok_or(TelemetryError::MissingEndpoint)
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct SinkPayload {
pub event: String,
pub event_id: String,
pub properties: serde_json::Value,
pub global_properties: serde_json::Value,
pub package: SinkPackage,
pub ts: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct SinkPackage {
pub name: String,
pub version: String,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct Context {
#[serde(rename = "openbot_distribution")]
pub distribution: Distribution,
#[serde(rename = "openbot_version")]
pub app_version: NumericVersion,
#[serde(rename = "openbot_platform")]
pub platform: Platform,
#[serde(rename = "openbot_arch")]
pub arch: Architecture,
#[serde(rename = "openbot_os_version", skip_serializing_if = "Option::is_none")]
pub os_version: Option<NumericVersion>,
#[serde(rename = "openbot_engine")]
pub engine: Engine,
pub runtime_env: RuntimeEnv,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NumericVersion {
pub parts: Vec<u32>,
}
impl NumericVersion {
pub fn new(parts: Vec<u32>) -> Result<Self> {
if (2..=4).contains(&parts.len()) {
Ok(Self { parts })
} else {
Err(TelemetryError::InvalidState(
"numeric version must have 2 to 4 dot-separated numeric parts".to_string(),
))
}
}
pub fn parse(value: &str) -> Result<Self> {
if value.len() > 32 {
return Err(TelemetryError::InvalidState(
"numeric version is too long".to_string(),
));
}
let parts = value
.split('.')
.map(|part| {
if part.is_empty() || !part.bytes().all(|byte| byte.is_ascii_digit()) {
return Err(TelemetryError::InvalidState(format!(
"numeric version contains a non-numeric part: {value}"
)));
}
part.parse::<u32>().map_err(|_| {
TelemetryError::InvalidState(format!(
"numeric version part is too large: {value}"
))
})
})
.collect::<Result<Vec<_>>>()?;
Self::new(parts)
}
}
impl std::fmt::Display for NumericVersion {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
for (index, part) in self.parts.iter().enumerate() {
if index > 0 {
formatter.write_str(".")?;
}
write!(formatter, "{part}")?;
}
Ok(())
}
}
impl Serialize for NumericVersion {
fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
serializer.serialize_str(&self.to_string())
}
}
impl<'de> Deserialize<'de> for NumericVersion {
fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
Self::parse(&value).map_err(serde::de::Error::custom)
}
}
impl Context {
fn to_global_properties(&self) -> serde_json::Value {
let mut properties = serde_json::json!({
"openbot_distribution": self.distribution,
"openbot_version": &self.app_version,
"openbot_platform": self.platform,
"openbot_arch": self.arch,
"openbot_engine": self.engine,
"runtime_env": self.runtime_env,
"sampleRate": 1,
"sampleWeight": 1,
"sampleRateAdjustmentFactor": 0
});
if let Some(os_version) = &self.os_version {
properties["openbot_os_version"] =
serde_json::to_value(os_version).unwrap_or(serde_json::Value::Null);
}
properties
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct PersistedState {
pub schema_version: u8,
pub install_id: String,
pub activated: bool,
pub last_step: Option<Step>,
pub queue: Vec<Event>,
}
impl PersistedState {
fn new(install_id: String) -> Self {
Self {
schema_version: STATE_SCHEMA_VERSION,
install_id,
activated: false,
last_step: None,
queue: Vec::new(),
}
}
fn push_bounded(&mut self, event: Event, max_queue: usize) {
self.queue.push(event);
while self.queue.len() > max_queue {
self.queue.remove(0);
}
}
fn validate(&self) -> Result<()> {
if self.schema_version != STATE_SCHEMA_VERSION {
return Err(TelemetryError::InvalidState(format!(
"unsupported telemetry state schema {}",
self.schema_version
)));
}
if !is_uuid(&self.install_id) {
return Err(TelemetryError::InvalidState(
"install_id is not a UUID".to_string(),
));
}
for event in &self.queue {
event.validate()?;
}
Ok(())
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct Event {
pub event_id: String,
pub occurred_at_ms: u64,
pub event_name: String,
pub context: Context,
pub data: EventData,
}
impl Event {
pub fn new(data: EventData, context: Context) -> Self {
let event_name = data.event_name().to_string();
Self {
event_id: new_uuid(),
occurred_at_ms: now_ms(),
event_name,
context,
data,
}
}
pub fn event_name(&self) -> &str {
&self.event_name
}
fn validate(&self) -> Result<()> {
if !is_uuid(&self.event_id) {
return Err(TelemetryError::InvalidState(
"event_id is not a UUID".to_string(),
));
}
if self.event_name != self.data.event_name() {
return Err(TelemetryError::InvalidState(format!(
"event_name {} does not match {:?}",
self.event_name, self.data
)));
}
Ok(())
}
fn to_sink_payload(&self) -> SinkPayload {
SinkPayload {
event: self.event_name.clone(),
event_id: self.event_id.clone(),
properties: serde_json::to_value(&self.data).unwrap_or_else(|_| serde_json::json!({})),
global_properties: self.context.to_global_properties(),
package: SinkPackage {
name: "openbot-desktop".to_string(),
version: self.context.app_version.to_string(),
},
ts: self.occurred_at_ms / 1000,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum EventData {
StepViewed {
step: Step,
},
HarnessChosen {
harness: Harness,
},
ModelChosen {
provider: Provider,
credential_path: CredentialPath,
custom_base_url: bool,
},
EngineDetected {
engine: Engine,
responding: bool,
},
EngineInstalled {
engine: Engine,
outcome: EngineInstallOutcome,
},
WindowsStage {
outcome: WindowsStageOutcome,
},
ImagePull {
outcome: Outcome,
duration_ms: u64,
bytes: Option<u64>,
},
SetupFailed {
step: Step,
error_class: SetupErrorClass,
},
Activated,
SetupAbandoned {
step: Step,
},
}
impl EventData {
pub fn event_name(&self) -> &'static str {
match self {
Self::StepViewed { .. } => "oss.desktop.step_viewed",
Self::HarnessChosen { .. } => "oss.desktop.harness_chosen",
Self::ModelChosen { .. } => "oss.desktop.model_chosen",
Self::EngineDetected { .. } => "oss.desktop.engine_detected",
Self::EngineInstalled { .. } => "oss.desktop.engine_installed",
Self::WindowsStage { .. } => "oss.desktop.windows_stage",
Self::ImagePull { .. } => "oss.desktop.image_pull",
Self::SetupFailed { .. } => "oss.desktop.setup_failed",
Self::Activated => "oss.desktop.activated",
Self::SetupAbandoned { .. } => "oss.desktop.setup_abandoned",
}
}
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Distribution {
Desktop,
}
impl Distribution {
fn as_str(self) -> &'static str {
"desktop"
}
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum RuntimeEnv {
Development,
Production,
Test,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Platform {
Windows,
Macos,
Linux,
Other,
}
impl Platform {
fn as_str(self) -> &'static str {
match self {
Self::Windows => "windows",
Self::Macos => "macos",
Self::Linux => "linux",
Self::Other => "other",
}
}
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Architecture {
X86_64,
Aarch64,
Other,
}
impl Architecture {
fn as_str(self) -> &'static str {
match self {
Self::X86_64 => "x86_64",
Self::Aarch64 => "aarch64",
Self::Other => "other",
}
}
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Step {
Welcome,
Harness,
Install,
Model,
Connect,
Ask,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Harness {
Crewai,
Llamaindex,
Agno,
Langgraph,
GoogleAdk,
PydanticAi,
MicrosoftAgentFramework,
ClaudeAgentSdk,
Strands,
Ag2,
Langroid,
Mastra,
ByoUrl,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Provider {
Openai,
Anthropic,
Compatible,
None,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CredentialPath {
Subscription,
ApiKey,
None,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Engine {
Docker,
Podman,
None,
}
impl Engine {
fn as_str(self) -> &'static str {
match self {
Self::Docker => "docker",
Self::Podman => "podman",
Self::None => "none",
}
}
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum EngineInstallOutcome {
Success,
Failure,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum WindowsStageOutcome {
Ready,
WslAbsent,
WslOne,
WslNoKernel,
VirtualMachinePlatformDisabled,
VirtualizationDisabled,
NotAdministrator,
CheckFailed,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Outcome {
Success,
Failure,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SetupErrorClass {
EngineUnavailable,
EngineInstallFailed,
ImagePullFailed,
InvalidConfiguration,
NetworkUnavailable,
PermissionDenied,
Unknown,
}
pub fn schema_json() -> serde_json::Value {
serde_json::json!({
"schema_version": STATE_SCHEMA_VERSION,
"event_name_prefix": "oss.desktop.",
"numeric_version_pattern": r"^\d+(?:\.\d+){1,3}$",
"context": {
"openbot_distribution": ["desktop"],
"openbot_version": { "pattern": r"^\d+(?:\.\d+){1,3}$" },
"openbot_platform": ["windows", "macos", "linux", "other"],
"openbot_arch": ["x86_64", "aarch64", "other"],
"openbot_os_version": { "optional": true, "pattern": r"^\d+(?:\.\d+){1,3}$" },
"openbot_engine": ["docker", "podman", "none"],
"runtime_env": ["development", "production", "test"]
},
"events": {
"step_viewed": { "step": ["welcome", "harness", "install", "model", "connect", "ask"] },
"harness_chosen": { "harness": ["crewai", "llamaindex", "agno", "langgraph", "google_adk", "pydantic_ai", "microsoft_agent_framework", "claude_agent_sdk", "strands", "ag2", "langroid", "mastra", "byo_url"] },
"model_chosen": { "provider": ["openai", "anthropic", "compatible", "none"], "credential_path": ["subscription", "api_key", "none"], "custom_base_url": "bool" },
"engine_detected": { "engine": ["docker", "podman", "none"], "responding": "bool" },
"engine_installed": { "engine": ["docker", "podman", "none"], "outcome": ["success", "failure"] },
"windows_stage": { "outcome": ["ready", "wsl_absent", "wsl_one", "wsl_no_kernel", "virtual_machine_platform_disabled", "virtualization_disabled", "not_administrator", "check_failed"] },
"image_pull": { "outcome": ["success", "failure"], "duration_ms": "u64", "bytes": "option_u64" },
"setup_failed": { "step": ["welcome", "harness", "install", "model", "connect", "ask"], "error_class": ["engine_unavailable", "engine_install_failed", "image_pull_failed", "invalid_configuration", "network_unavailable", "permission_denied", "unknown"] },
"activated": {},
"setup_abandoned": { "step": ["welcome", "harness", "install", "model", "connect", "ask"] }
}
})
}
pub fn state_path(data_dir: impl AsRef<Path>) -> PathBuf {
data_dir.as_ref().join(STATE_FILE)
}
fn client() -> Result<Client> {
Ok(Client::builder()
.timeout(REQUEST_TIMEOUT)
.connect_timeout(REQUEST_TIMEOUT)
.redirect(Policy::none())
.build()?)
}
fn write_state(path: &Path, state: &PersistedState) -> Result<()> {
if let Some(parent) = path.parent() {
fs::create_dir_all(parent)?;
}
crate::env::write_private_file(path, &serde_json::to_vec(state)?)?;
Ok(())
}
fn normalized_max_queue(configured: usize) -> usize {
configured.clamp(1, 256)
}
fn telemetry_disabled(env_override: EnvOverride) -> bool {
match env_override {
EnvOverride::Enabled => false,
EnvOverride::Disabled => true,
EnvOverride::Process => {
disabled_value("COPILOTKIT_TELEMETRY_DISABLED") || disabled_value("DO_NOT_TRACK")
}
}
}
fn disabled_value(name: &str) -> bool {
env::var(name)
.ok()
.map(|value| matches!(value.trim().to_ascii_lowercase().as_str(), "1" | "true"))
.unwrap_or(false)
}
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_millis()
.try_into()
.unwrap_or(u64::MAX)
}
fn is_uuid(value: &str) -> bool {
let bytes = value.as_bytes();
if bytes.len() != 36 {
return false;
}
for (index, byte) in bytes.iter().enumerate() {
if matches!(index, 8 | 13 | 18 | 23) {
if *byte != b'-' {
return false;
}
} else if !byte.is_ascii_hexdigit() {
return false;
}
}
true
}
fn new_uuid() -> String {
let mut bytes = [0u8; 16];
rand::rng().fill_bytes(&mut bytes);
bytes[6] = (bytes[6] & 0x0f) | 0x40;
bytes[8] = (bytes[8] & 0x3f) | 0x80;
format!(
"{:02x}{:02x}{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}{:02x}{:02x}{:02x}{:02x}",
bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7], bytes[8], bytes[9], bytes[10], bytes[11], bytes[12], bytes[13], bytes[14], bytes[15]
)
}
#[cfg(test)]
mod tests {
use super::*;
use std::fs;
use std::io::{Read, Write};
use std::net::TcpListener;
use std::path::PathBuf;
use std::sync::{mpsc, Barrier};
use std::thread;
use std::time::{SystemTime, UNIX_EPOCH};
fn temp_dir(name: &str) -> PathBuf {
let unique = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos();
let dir = std::env::temp_dir().join(format!("openbot-telemetry-{name}-{unique}"));
fs::create_dir_all(&dir).unwrap();
dir
}
fn context(version: &str, engine: Engine) -> Context {
Context {
distribution: Distribution::Desktop,
app_version: NumericVersion::parse(version).unwrap(),
platform: Platform::Macos,
arch: Architecture::Aarch64,
os_version: Some(NumericVersion::parse("14.5.0").unwrap()),
engine,
runtime_env: RuntimeEnv::Test,
}
}
fn enabled(endpoint: String) -> Config {
Config {
enabled: true,
endpoint: Some(endpoint),
max_queue: 256,
}
}
#[test]
fn numeric_version_accepts_only_normalized_numeric_versions() {
let version = NumericVersion::parse("1.2").unwrap();
assert_eq!(version.to_string(), "1.2");
assert_eq!(serde_json::to_value(&version).unwrap(), "1.2");
let without_os = Context {
os_version: None,
..context("1.2.3", Engine::None)
};
assert!(serde_json::to_value(&without_os)
.unwrap()
.get("openbot_os_version")
.is_none());
assert_eq!(
NumericVersion::parse("1.2.3.4").unwrap().to_string(),
"1.2.3.4"
);
assert!(NumericVersion::parse("1").is_err());
assert!(NumericVersion::parse("1.2.3.4.5").is_err());
assert!(NumericVersion::parse("1.2-beta").is_err());
assert!(NumericVersion::parse("123456789012345678901234567890123").is_err());
}
#[test]
fn event_schema_is_tagged_closed_and_exposes_centralized_name() {
let event = Event::new(
EventData::ModelChosen {
provider: Provider::Compatible,
credential_path: CredentialPath::ApiKey,
custom_base_url: true,
},
context("1.2.3", Engine::None),
);
assert_eq!(event.event_name(), "oss.desktop.model_chosen");
let json = serde_json::to_value(&event.data).unwrap();
assert_eq!(json["kind"], "model_chosen");
assert_eq!(json["provider"], "compatible");
assert_eq!(
serde_json::to_value(EventData::HarnessChosen {
harness: Harness::MicrosoftAgentFramework
})
.unwrap()["harness"],
"microsoft_agent_framework"
);
assert!(serde_json::from_value::<EventData>(serde_json::json!({
"kind": "model_chosen",
"provider": "compatible",
"credential_path": "api_key",
"custom_base_url": true,
"extra": "rejected"
}))
.is_err());
assert!(serde_json::from_value::<EventData>(serde_json::json!({
"kind": "setup_failed",
"step": "welcome",
"error_class": "raw user-facing error"
}))
.is_err());
}
#[test]
fn schema_lists_every_closed_event_kind_and_no_freeform_string_fields() {
let schema = schema_json();
let events = schema["events"].as_object().unwrap();
for sample in sample_events() {
let value = serde_json::to_value(&sample).unwrap();
let kind = value["kind"].as_str().unwrap();
assert!(events.contains_key(kind), "schema missing {kind}");
assert_string_values_are_listed(&value, &events[kind]);
}
assert_eq!(schema["numeric_version_pattern"], r"^\d+(?:\.\d+){1,3}$");
}
fn sample_events() -> Vec<EventData> {
vec![
EventData::StepViewed {
step: Step::Welcome,
},
EventData::HarnessChosen {
harness: Harness::ByoUrl,
},
EventData::ModelChosen {
provider: Provider::Openai,
credential_path: CredentialPath::Subscription,
custom_base_url: false,
},
EventData::EngineDetected {
engine: Engine::Docker,
responding: true,
},
EventData::EngineInstalled {
engine: Engine::Podman,
outcome: EngineInstallOutcome::Failure,
},
EventData::WindowsStage {
outcome: WindowsStageOutcome::WslNoKernel,
},
EventData::ImagePull {
outcome: Outcome::Success,
duration_ms: 12,
bytes: Some(34),
},
EventData::SetupFailed {
step: Step::Install,
error_class: SetupErrorClass::ImagePullFailed,
},
EventData::Activated,
EventData::SetupAbandoned { step: Step::Ask },
]
}
fn assert_string_values_are_listed(value: &serde_json::Value, schema: &serde_json::Value) {
if let Some(object) = value.as_object() {
for (key, child) in object {
if key == "kind" {
continue;
}
if let Some(string) = child.as_str() {
let allowed = schema[key]
.as_array()
.expect("string fields must be enum arrays");
assert!(
allowed.iter().any(|candidate| candidate == string),
"{key}={string} not in schema"
);
} else if child.is_object() {
assert_string_values_are_listed(child, &schema[key]);
}
}
}
}
#[test]
fn disabled_mode_drops_pending_state_without_reading_or_replaying() {
let dir = temp_dir("disabled");
let state = PersistedState {
schema_version: STATE_SCHEMA_VERSION,
install_id: "11111111-1111-4111-8111-111111111111".to_string(),
activated: false,
last_step: None,
queue: vec![Event::new(
EventData::Activated,
context("1.2.3", Engine::None),
)],
};
fs::write(state_path(&dir), serde_json::to_vec_pretty(&state).unwrap()).unwrap();
let telemetry = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
enabled("http://127.0.0.1:9/ingest".to_string()),
EnvOverride::Disabled,
)
.unwrap();
telemetry.record(EventData::Activated).unwrap();
telemetry.flush().unwrap();
assert!(telemetry.install_id().is_none());
assert!(telemetry.install_id().is_none());
assert!(!state_path(&dir).exists());
}
#[test]
fn adjacent_duplicate_step_viewed_is_suppressed_only_within_current_session() {
let dir = temp_dir("step-dedupe");
let first = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
first
.record(EventData::StepViewed {
step: Step::Welcome,
})
.unwrap();
first
.record(EventData::StepViewed {
step: Step::Welcome,
})
.unwrap();
assert_eq!(
first
.snapshot()
.unwrap()
.queue
.iter()
.filter(|event| matches!(
event.data,
EventData::StepViewed {
step: Step::Welcome
}
))
.count(),
1
);
first
.record(EventData::HarnessChosen {
harness: Harness::ByoUrl,
})
.unwrap();
first
.record(EventData::StepViewed {
step: Step::Welcome,
})
.unwrap();
assert_eq!(
first
.snapshot()
.unwrap()
.queue
.iter()
.filter(|event| matches!(
event.data,
EventData::StepViewed {
step: Step::Welcome
}
))
.count(),
2
);
drop(first);
let second = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
second
.record(EventData::StepViewed {
step: Step::Welcome,
})
.unwrap();
let state = second.snapshot().unwrap();
assert_eq!(
state
.queue
.iter()
.filter(|event| matches!(
event.data,
EventData::StepViewed {
step: Step::Welcome
}
))
.count(),
3
);
assert_eq!(
state
.queue
.iter()
.filter(|event| matches!(
event.data,
EventData::SetupAbandoned {
step: Step::Welcome
}
))
.count(),
1
);
}
#[test]
fn record_persists_before_send_and_flush_preserves_until_success() {
let dir = temp_dir("queue");
let telemetry = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
enabled("http://127.0.0.1:9/ingest".to_string()),
EnvOverride::Enabled,
)
.unwrap();
telemetry
.record(EventData::StepViewed {
step: Step::Harness,
})
.unwrap();
assert!(fs::read_to_string(state_path(&dir))
.unwrap()
.contains("step_viewed"));
assert!(telemetry.flush().is_err());
assert_eq!(
serde_json::from_str::<PersistedState>(&fs::read_to_string(state_path(&dir)).unwrap())
.unwrap()
.queue
.len(),
1
);
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let endpoint = format!("http://{}/ingest", listener.local_addr().unwrap());
let server = thread::spawn(move || {
let first = one_response(listener.try_clone().unwrap());
let second = one_response(listener);
format!("{first}\n{second}")
});
let replay = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
enabled(endpoint),
EnvOverride::Enabled,
)
.unwrap();
replay.flush().unwrap();
let request = server.join().unwrap();
assert!(request.contains("oss.desktop.step_viewed"));
assert!(request
.to_ascii_lowercase()
.contains("x-copilotkit-telemetry-id"));
assert!(request.contains("oss.desktop.setup_abandoned"));
assert!(request.contains("openbot_distribution"));
assert_eq!(
serde_json::from_str::<PersistedState>(&fs::read_to_string(state_path(&dir)).unwrap())
.unwrap()
.queue
.len(),
0
);
}
#[test]
fn concurrent_flush_does_not_drop_unsent_second_event() {
let dir = temp_dir("concurrent");
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let endpoint = format!("http://{}/ingest", listener.local_addr().unwrap());
let telemetry = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
enabled(endpoint),
EnvOverride::Enabled,
)
.unwrap();
telemetry
.record(EventData::StepViewed {
step: Step::Welcome,
})
.unwrap();
telemetry
.record(EventData::StepViewed {
step: Step::Harness,
})
.unwrap();
let server = thread::spawn(move || one_response(listener));
let barrier = Arc::new(Barrier::new(2));
let a = Arc::clone(&telemetry);
let barrier_a = Arc::clone(&barrier);
let first = thread::spawn(move || {
barrier_a.wait();
let _ = a.flush();
});
let b = Arc::clone(&telemetry);
let second = thread::spawn(move || {
barrier.wait();
let _ = b.flush();
});
first.join().unwrap();
second.join().unwrap();
let _ = server.join().unwrap();
let state = telemetry.snapshot().unwrap();
assert_eq!(state.queue.len(), 1);
assert!(matches!(
state.queue[0].data,
EventData::StepViewed {
step: Step::Harness
}
));
}
fn one_response(listener: TcpListener) -> String {
let (mut stream, _) = listener.accept().unwrap();
let mut buffer = [0u8; 8192];
let read = stream.read(&mut buffer).unwrap();
stream.write_all(b"HTTP/1.1 202 Accepted\r\nContent-Length: 11\r\nConnection: close\r\n\r\n{\"ok\":true}").unwrap();
String::from_utf8_lossy(&buffer[..read]).into_owned()
}
#[test]
fn shutdown_waits_for_active_flush_and_returns_only_after_abandonment_flushes() {
let dir = temp_dir("shutdown-active-flush");
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let endpoint = format!("http://{}/ingest", listener.local_addr().unwrap());
let telemetry = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
enabled(endpoint),
EnvOverride::Enabled,
)
.unwrap();
telemetry
.record(EventData::StepViewed {
step: Step::Welcome,
})
.unwrap();
let (first_read_tx, first_read_rx) = mpsc::channel();
let (release_tx, release_rx) = mpsc::channel();
let server = thread::spawn(move || {
let (mut first_stream, _) = listener.accept().unwrap();
let mut first_buffer = [0u8; 8192];
let first_read = first_stream.read(&mut first_buffer).unwrap();
first_read_tx.send(()).unwrap();
release_rx.recv().unwrap();
first_stream.write_all(b"HTTP/1.1 202 Accepted\r\nContent-Length: 11\r\nConnection: close\r\n\r\n{\"ok\":true}").unwrap();
let (mut second_stream, _) = listener.accept().unwrap();
let mut second_buffer = [0u8; 8192];
let second_read = second_stream.read(&mut second_buffer).unwrap();
second_stream.write_all(b"HTTP/1.1 202 Accepted\r\nContent-Length: 11\r\nConnection: close\r\n\r\n{\"ok\":true}").unwrap();
format!(
"{}\n{}",
String::from_utf8_lossy(&first_buffer[..first_read]),
String::from_utf8_lossy(&second_buffer[..second_read])
)
});
let flushing = Arc::clone(&telemetry);
let flush_thread = thread::spawn(move || flushing.flush().unwrap());
first_read_rx.recv().unwrap();
let shutting_down = Arc::clone(&telemetry);
let shutdown_thread = thread::spawn(move || shutting_down.shutdown().unwrap());
sleep(Duration::from_millis(50));
assert!(
!shutdown_thread.is_finished(),
"shutdown returned while active flush was still blocked"
);
release_tx.send(()).unwrap();
shutdown_thread.join().unwrap();
assert_eq!(telemetry.snapshot().unwrap().queue.len(), 0);
flush_thread.join().unwrap();
let requests = server.join().unwrap();
assert!(requests.contains("oss.desktop.step_viewed"));
assert!(requests.contains("oss.desktop.setup_abandoned"));
}
#[test]
fn pending_events_keep_record_time_context() {
let dir = temp_dir("context");
let telemetry = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
telemetry
.record(EventData::EngineDetected {
engine: Engine::None,
responding: false,
})
.unwrap();
telemetry.update_engine(Engine::Docker).unwrap();
let state = telemetry.snapshot().unwrap();
assert_eq!(state.queue[0].context.engine, Engine::None);
}
#[test]
fn activation_and_shutdown_abandonment_are_deduped_from_persisted_state() {
let dir = temp_dir("activation");
let telemetry = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
telemetry
.record(EventData::StepViewed { step: Step::Ask })
.unwrap();
telemetry.record(EventData::Activated).unwrap();
telemetry.record(EventData::Activated).unwrap();
telemetry.shutdown().unwrap();
let state = telemetry.snapshot().unwrap();
assert_eq!(
state
.queue
.iter()
.filter(|event| matches!(event.data, EventData::Activated))
.count(),
1
);
assert!(!state
.queue
.iter()
.any(|event| matches!(event.data, EventData::SetupAbandoned { .. })));
}
#[test]
fn quit_abandonment_is_not_duplicated_on_next_launch() {
let dir = temp_dir("quit-reopen");
let first = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
first
.record(EventData::StepViewed { step: Step::Ask })
.unwrap();
first.shutdown().unwrap();
drop(first);
let second = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
let state = second.snapshot().unwrap();
assert_eq!(
state
.queue
.iter()
.filter(|event| matches!(event.data, EventData::SetupAbandoned { step: Step::Ask }))
.count(),
1
);
}
#[test]
fn next_launch_records_abandoned_step_after_crash_before_activation() {
let dir = temp_dir("abandoned");
let first = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
first
.record(EventData::StepViewed {
step: Step::Install,
})
.unwrap();
drop(first);
let second = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled,
)
.unwrap();
let state = second.snapshot().unwrap();
assert!(state.queue.iter().any(|event| matches!(
event.data,
EventData::SetupAbandoned {
step: Step::Install
}
)));
}
#[test]
fn state_deserialize_refuses_unknown_fields_and_untyped_events() {
let dir = temp_dir("schema");
let raw = serde_json::json!({
"schema_version": 1,
"install_id": "11111111-1111-4111-8111-111111111111",
"activated": false,
"last_step": null,
"queue": [{
"event_id": "22222222-2222-4222-8222-222222222222",
"occurred_at_ms": 1,
"event_name": "oss.desktop.activated",
"context": context("1.2.3", Engine::None),
"data": { "kind": "activated" },
"unknown": true
}]
});
fs::write(state_path(&dir), serde_json::to_vec_pretty(&raw).unwrap()).unwrap();
assert!(Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config::disabled_for_tests(),
EnvOverride::Enabled
)
.is_err());
}
#[test]
fn queue_is_bounded_to_maximum() {
let dir = temp_dir("bounded");
let telemetry = Telemetry::open_with_env(
&dir,
context("1.2.3", Engine::None),
Config {
enabled: true,
endpoint: None,
max_queue: 2,
},
EnvOverride::Enabled,
)
.unwrap();
telemetry
.record(EventData::StepViewed {
step: Step::Welcome,
})
.unwrap();
telemetry
.record(EventData::StepViewed {
step: Step::Harness,
})
.unwrap();
telemetry
.record(EventData::StepViewed { step: Step::Model })
.unwrap();
let state = telemetry.snapshot().unwrap();
assert_eq!(state.queue.len(), 2);
assert!(matches!(
state.queue[0].data,
EventData::StepViewed {
step: Step::Harness
}
));
}
}