Skip to content

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

7.5 KB
Raw Blame
use std::path::PathBuf;

use anyhow::{anyhow, Result};
use tracing::info;

use crate::{
    api::{
        self,
        releases::ReleaseBuilder,
        symbol_sets::{dedup_uploads_by_chunk_id, SymbolSetUpload, MAX_FILE_SIZE},
    },
    debug_symbols::{discover, package_dsym_bundles, report_problems},
    sourcemaps::args::{pack_version, ReleaseArgs, UploadConflictArgs},
    utils::git::get_git_info,
};

#[derive(clap::Args, Clone)]
pub struct Args {
    /// The directory to scan for native debug symbol files (e.g. target/release).
    /// ELF and Mach-O executables, shared libraries, and `objcopy
    /// --only-keep-debug` companions with debug info are uploaded, as are Apple
    /// `.dSYM` bundles (macOS only — needs `dwarfdump` from Xcode); everything
    /// else is skipped.
    #[arg(short, long)]
    pub directory: PathBuf,

    #[clap(flatten)]
    pub release: ReleaseArgs,

    #[clap(flatten)]
    pub conflict: UploadConflictArgs,

    /// Include source code files in the upload.
    /// When enabled, project source files referenced by DWARF debug info are
    /// bundled in, allowing PostHog to display source context around frames.
    /// Implies --force unless --skip-on-conflict is set.
    #[arg(long, default_value_t = false)]
    pub include_source: bool,

    /// Limit uploaded source files to this directory. Requires --include-source.
    #[arg(long, requires = "include_source")]
    pub source_root: Option<PathBuf>,
}

pub fn upload(args: &Args) -> Result<()> {
    let Args {
        directory,
        release,
        conflict,
        include_source,
        source_root,
    } = args;
    let release_args = release.resolve_info_plist()?;
    let source_root = source_root
        .as_ref()
        .map(|root| -> Result<PathBuf> {
            let root = root.canonicalize().map_err(|e| {
                anyhow!(
                    "Source root {} canonicalization failed: {e}",
                    root.display()
                )
            })?;
            if !root.is_dir() {
                anyhow::bail!("Source root {} is not a directory", root.display());
            }
            Ok(root)
        })
        .transpose()?;

    let directory = directory.canonicalize().map_err(|e| {
        anyhow!(
            "Path {} canonicalization failed: {}",
            directory.display(),
            e
        )
    })?;

    if !directory.is_dir() {
        anyhow::bail!("Path {} is not a directory", directory.display());
    }

    let report = discover(&directory)?;
    report_problems(&report, &directory)?;

    info!(
        "Found {} native debug file(s) and {} dSYM bundle(s)",
        report.files.len(),
        report.dsym_bundles.len()
    );

    // Package everything first, with no release id yet, so we only create a
    // release once we know there's something to upload. dSYM packaging
    // logs-and-skips failures (e.g. a missing dwarfdump), so a dSYM-only
    // directory can yield zero uploads — creating the release up front would
    // leave a release record behind with no symbols attached to it.
    let mut native_uploads = Vec::with_capacity(report.files.len());
    for file in report.files {
        info!(
            "Processing {} (debug id {})",
            file.path.display(),
            file.debug_id
        );
        native_uploads.push(file.into_upload(None, *include_source, source_root.as_deref())?);
    }

    // A failed or oversized dSYM leaves a matching standalone Mach-O as the
    // fallback. Successfully packaged, uploadable dSYMs take priority.
    let dsym_uploads = package_dsym_bundles(
        &report.dsym_bundles,
        *include_source,
        source_root.as_deref(),
    );
    let mut uploads = merge_uploads_prefer_dsym(dsym_uploads, native_uploads, MAX_FILE_SIZE);

    if uploads.is_empty() {
        anyhow::bail!(
            "No debug symbols could be packaged for upload from {}",
            directory.display()
        );
    }

    // Now that there's something to upload, set up the release (explicit flags
    // win, git info is metadata/fallback) and stamp it on every set.
    let mut release_builder = ReleaseBuilder::default();
    if let Ok(Some(git_info)) = get_git_info(Some(directory.clone())) {
        release_builder.with_git(git_info);
    }
    if let Some(ref release_name) = release_args.name {
        release_builder.with_name(release_name);
    }
    if let Some(version) = pack_version(&release_args.version, &release_args.build) {
        release_builder.with_version(&version);
    }

    let created_release = release_builder
        .can_create()
        .then(|| release_builder.fetch_or_create())
        .transpose()?;
    if let Some(release) = created_release {
        let release_id = release.id.to_string();
        for upload in &mut uploads {
            upload.release_id = Some(release_id.clone());
        }
    }

    info!("Uploading {} debug symbol file(s)...", uploads.len());
    // --include-source implies force unless the user explicitly asked to keep
    // existing symbol sets with --skip-on-conflict.
    let effective_force = conflict.force || (*include_source && !conflict.skip_on_conflict);
    let (_summary, upload_result) = api::symbol_sets::upload_with_retry(
        uploads,
        10,
        release_args.skip_release_on_fail,
        effective_force,
        conflict.skip_on_conflict,
    );
    upload_result?;
    info!("Debug symbol upload complete");

    Ok(())
}

/// Merge packaged native symbols, preferring an uploadable dSYM when both
/// inputs carry the same uppercase Mach-O UUID. Oversized dSYMs come last so a
/// matching native upload wins, but remain available when there is no fallback
/// and the upload layer can preserve its existing warning behavior. ELF ids
/// remain lowercase and cannot collide.
fn merge_uploads_prefer_dsym(
    dsym_uploads: Vec<SymbolSetUpload>,
    native_uploads: Vec<SymbolSetUpload>,
    max_file_size: usize,
) -> Vec<SymbolSetUpload> {
    let (mut preferred_dsyms, oversized_dsyms): (Vec<_>, Vec<_>) = dsym_uploads
        .into_iter()
        .partition(|upload| upload.data.len() <= max_file_size);
    preferred_dsyms.extend(native_uploads);
    preferred_dsyms.extend(oversized_dsyms);
    // Casing must never be normalized here: the SDK matches chunk_ids case-sensitively, per
    // format, and lowercase ELF ids never collide with uppercase Mach-O ones.
    dedup_uploads_by_chunk_id(preferred_dsyms)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn merge_uploads_prefers_dsym_over_matching_macho() {
        let uuid = "77C2F55F-C959-487A-9601-6A715A9BB5DE";
        let upload = |chunk_id: &str, data: &[u8]| SymbolSetUpload {
            chunk_id: chunk_id.to_string(),
            release_id: None,
            data: data.to_vec(),
            content_hash: None,
        };

        let uploads = merge_uploads_prefer_dsym(
            vec![upload(uuid, b"dsym")],
            vec![upload(uuid, b"macho")],
            10,
        );

        assert_eq!(uploads.len(), 1);
        assert_eq!(uploads[0].data, b"dsym");
    }

    #[test]
    fn merge_uploads_uses_macho_when_matching_dsym_is_oversized() {
        let uuid = "77C2F55F-C959-487A-9601-6A715A9BB5DE";
        let upload = |data: &[u8]| SymbolSetUpload {
            chunk_id: uuid.to_string(),
            release_id: None,
            data: data.to_vec(),
            content_hash: None,
        };

        let uploads =
            merge_uploads_prefer_dsym(vec![upload(b"oversized-dsym")], vec![upload(b"macho")], 5);

        assert_eq!(uploads.len(), 1);
        assert_eq!(uploads[0].data, b"macho");
    }
}