:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use anyhow::Result;
use inquire::{
validator::{ErrorMessage, Validation},
CustomUserError,
};
use posthog_rs::{ErrorTrackingOptionsBuilder, Event};
use reqwest::blocking::Client;
use std::{
io::{self, IsTerminal},
path::PathBuf,
sync::{Mutex, OnceLock},
thread::JoinHandle,
time::Duration,
};
use tracing::debug;
use uuid::Uuid;
use crate::{
api::client::PHClient,
utils::auth::{env_id_validator, get_token, host_validator, token_validator},
};
// I've decided in my infinite wisdom that global state is fine, actually.
pub static INVOCATION_CONTEXT: OnceLock<InvocationContext> = OnceLock::new();
pub struct InvocationContext {
pub config: InvocationConfig,
pub client: PHClient,
pub is_terminal: bool,
handles: Mutex<Vec<JoinHandle<()>>>,
}
struct TelemetryContext {
invocation_id: String,
command_name: Option<String>,
env_id: Option<String>,
is_terminal: bool,
}
static TELEMETRY_CONTEXT: OnceLock<Mutex<TelemetryContext>> = OnceLock::new();
fn telemetry_context() -> &'static Mutex<TelemetryContext> {
TELEMETRY_CONTEXT.get_or_init(|| {
Mutex::new(TelemetryContext {
invocation_id: Uuid::now_v7().to_string(),
command_name: None,
env_id: None,
is_terminal: io::stdout().is_terminal(),
})
})
}
pub fn set_telemetry_command_name(command_name: &str) {
if let Ok(mut context) = telemetry_context().lock() {
context.command_name = Some(command_name.to_string());
}
}
fn set_telemetry_env_id(env_id: &str) {
if let Ok(mut context) = telemetry_context().lock() {
context.env_id = Some(env_id.to_string());
}
}
/// Attaches the project id from the environment to telemetry, for commands that
/// never load stored credentials (notably `api` with env-var auth). Values that
/// don't look like a real project id are ignored so telemetry can never pick up
/// an arbitrary string from a misconfigured environment.
pub fn set_telemetry_env_id_from_environment() {
const ENV_ID_ENV_VARS: &[&str] = &[
"POSTHOG_CLI_PROJECT_ID",
"POSTHOG_CLI_ENV_ID",
"POSTHOG_PROJECT_ID",
];
let Some(env_id) = ENV_ID_ENV_VARS
.iter()
.find_map(|name| std::env::var(name).ok().filter(|value| !value.is_empty()))
else {
return;
};
if !matches!(env_id_validator(&env_id), Ok(Validation::Valid)) {
return;
}
set_telemetry_env_id(&env_id);
}
/// Whether this event is a panic from std's `print!`/`eprintln!` machinery
/// failing on a closed pipe. These fire when the reader of stdout/stderr goes
/// away mid-command; the writer fix in `main.rs` keeps them from aborting the
/// command, and dropping them here keeps the residual noise out of error
/// tracking so a broken pipe never self-reports as an issue.
fn is_broken_pipe_panic(event: &Event) -> bool {
if event.event_name() != "$exception" {
return false;
}
let Some(items) = event
.properties()
.get("$exception_list")
.and_then(|list| list.as_array())
else {
return false;
};
items.iter().any(|item| {
item.get("value")
.and_then(|value| value.as_str())
.is_some_and(|message| {
message.contains("failed printing to std") && message.contains("Broken pipe")
})
})
}
fn apply_telemetry_properties(event: &mut Event) {
let _ = event.insert_prop("cli_version", env!("CARGO_PKG_VERSION"));
let _ = event.insert_prop("invocation_id", telemetry_invocation_id());
let _ = event.insert_prop("is_ci", std::env::var_os("CI").is_some());
let _ = event.insert_prop("is_terminal", telemetry_is_terminal());
let _ = event.insert_prop("os", std::env::consts::OS);
let _ = event.insert_prop("arch", std::env::consts::ARCH);
if let Some(command_name) = telemetry_command_name() {
let _ = event.insert_prop("command_name", command_name);
}
if let Some(env_id) = telemetry_env_id() {
let _ = event.insert_prop("env_id", env_id);
}
}
fn telemetry_invocation_id() -> String {
telemetry_context()
.lock()
.map(|context| context.invocation_id.clone())
.unwrap_or_else(|_| "unknown".to_string())
}
pub fn current_invocation_id() -> String {
telemetry_invocation_id()
}
/// Captures the `posthog cli command run` usage event without requiring an
/// `InvocationContext` — the `api` command usually runs without one, which left
/// it with no usage telemetry at all. Callers must join the handle before the
/// process exits so the event reaches the queue ahead of the final flush.
pub fn capture_command_run_without_context() -> JoinHandle<()> {
std::thread::spawn(|| {
debug!("Capturing command run event");
posthog_rs::capture(Event::new_anon("posthog cli command run"));
debug!("Event queued successfully");
})
}
fn telemetry_command_name() -> Option<String> {
telemetry_context()
.lock()
.ok()
.and_then(|context| context.command_name.clone())
}
pub fn current_telemetry_command_name() -> Option<String> {
telemetry_command_name()
}
fn telemetry_env_id() -> Option<String> {
telemetry_context()
.lock()
.ok()
.and_then(|context| context.env_id.clone())
}
fn telemetry_is_terminal() -> bool {
telemetry_context()
.lock()
.map(|context| context.is_terminal)
.unwrap_or_else(|_| io::stdout().is_terminal())
}
pub fn context() -> &'static InvocationContext {
INVOCATION_CONTEXT.get().expect("Context has been set up")
}
pub fn init_posthog_telemetry() {
let Some(token) = option_env!("POSTHOG_API_TOKEN") else {
debug!("Posthog api token not set at build time - is this a debug build?");
return;
};
let error_tracking = ErrorTrackingOptionsBuilder::default()
.capture_panics(true)
.build()
.expect("Building error tracking config succeeds");
let ph_config = posthog_rs::ClientOptionsBuilder::default()
.api_key(token.to_string())
.request_timeout_seconds(5) // It's a CLI, 5 seconds is an eternity
.error_tracking(error_tracking)
.before_send(|mut event| {
if is_broken_pipe_panic(&event) {
return None;
}
apply_telemetry_properties(&mut event);
Some(event)
})
.build()
.expect("Building PH config succeeds");
match posthog_rs::init_global(ph_config) {
Ok(()) => {}
Err(posthog_rs::Error::AlreadyInitialized) => {
debug!("PostHog client already initialized");
}
Err(err) => {
debug!("PostHog client unavailable: {err:?}");
}
}
}
pub fn init_context(
host: Option<String>,
skip_ssl: bool,
rate_limit: Option<usize>,
env_file: Option<PathBuf>,
) -> Result<()> {
let token = get_token(env_file)?;
let config = InvocationConfig {
api_key: token.token.clone(),
host: host.unwrap_or(token.host.unwrap_or("https://us.i.posthog.com".into())),
env_id: token.env_id.clone(),
skip_ssl,
rate_limit: rate_limit.unwrap_or(480),
};
config.validate()?;
set_telemetry_env_id(&config.env_id);
let client: PHClient = PHClient::from_config(config.clone())?;
INVOCATION_CONTEXT.get_or_init(|| InvocationContext::new(config, client));
Ok(())
}
#[derive(Clone)]
pub struct InvocationConfig {
pub api_key: String,
pub host: String,
pub env_id: String,
pub skip_ssl: bool,
pub rate_limit: usize, // max number of requests per minute
}
impl InvocationConfig {
pub fn validate(&self) -> Result<()> {
fn handle_validation(
validation: Result<Validation, CustomUserError>,
context: &str,
) -> Result<()> {
let validation = validation.map_err(|err| anyhow::anyhow!("{context}: {err}"))?;
if let Validation::Invalid(ErrorMessage::Custom(msg)) = validation {
anyhow::bail!("{context}: {msg:?}");
}
Ok(())
}
handle_validation(token_validator(&self.api_key), "Invalid Personal API key")?;
handle_validation(host_validator(&self.host), "Invalid Host")?;
handle_validation(env_id_validator(&self.env_id), "Invalid Environment ID")?;
Ok(())
}
}
impl InvocationContext {
pub fn new(config: InvocationConfig, client: PHClient) -> Self {
Self {
config,
client,
is_terminal: io::stdout().is_terminal(),
handles: Default::default(),
}
}
pub fn build_http_client(&self) -> Result<Client> {
let client = Client::builder()
.danger_accept_invalid_certs(self.config.skip_ssl)
.build()?;
Ok(client)
}
/// Upload client: fails fast on unreachable hosts so retries can reroute to
/// the fallback endpoint quickly. Downloads keep the default timeouts
/// because they have no retry or fallback path, and a slow connect there is
/// better than a failed one.
pub fn build_upload_http_client(&self) -> Result<Client> {
let client = Client::builder()
.danger_accept_invalid_certs(self.config.skip_ssl)
.connect_timeout(Duration::from_secs(5))
.build()?;
Ok(client)
}
pub fn capture_command_invoked(&self, command: &str) {
set_telemetry_command_name(command);
self.capture_event("posthog cli command run", Vec::new());
}
pub fn capture_event(&self, event_name: &str, props: Vec<(&str, serde_json::Value)>) {
let event_name = event_name.to_string();
let props: Vec<(String, serde_json::Value)> =
props.into_iter().map(|(k, v)| (k.to_string(), v)).collect();
let handle = std::thread::spawn(move || {
let mut event = Event::new_anon(event_name);
for (key, value) in &props {
event
.insert_prop(key, value)
.expect("Inserting prop succeeds");
}
debug!("Capturing event");
posthog_rs::capture(event);
debug!("Event queued successfully");
});
self.handles.lock().unwrap().push(handle);
}
pub fn finish(&self) {
self.handles
.lock()
.unwrap()
.drain(..)
.for_each(|handle| handle.join().unwrap());
posthog_rs::flush();
}
}
#[cfg(test)]
mod tests {
use super::*;
fn exception_event(message: &str) -> Event {
let mut event = Event::new_anon("$exception");
event
.insert_prop(
"$exception_list",
serde_json::json!([{ "type": "Panic", "value": message }]),
)
.unwrap();
event
}
#[test]
fn detects_broken_pipe_printing_panics() {
assert!(is_broken_pipe_panic(&exception_event(
"failed printing to stderr: Broken pipe (os error 32)"
)));
assert!(is_broken_pipe_panic(&exception_event(
"failed printing to stdout: Broken pipe (os error 32)"
)));
}
#[test]
fn ignores_other_events() {
assert!(!is_broken_pipe_panic(&exception_event(
"index out of bounds"
)));
assert!(!is_broken_pipe_panic(&Event::new_anon(
"posthog cli command run"
)));
}
}