---
title: "2026-08-25 vxData storage call graph inspection"
description: "Compared the vxData SDK download, materialize, and open paths in mono PR 337 against its exact base."
image: "https://docs.virdx.dev/img/virdx-social-card.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.virdx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-08-25 vxData storage call graph inspection

## Work Done

- Inspected mono PR 337 at `HEAD` against exact base `790fac112990338295efc7611342b2aa69fed89e`.
- Derived minimal before/after call graphs for SDK storage download and DataFrame materialization.
- Confirmed that `storage.open` is new and materializes through the same download engine into a temporary directory.
- Traced the related API batch-presign and prefix-list routes through the MinIO service layer.
- Reviewed the custom JSONL telemetry sink and compared it with standard Python logging.
- Checked the root README, SDK README, and API agent guide against the implementation.
- Replaced the SDK-owned JSONL telemetry sink with one structured `storage_download` log event per successful transfer call, following the repository's `extra={"event": event}` convention; failures propagate unchanged to their caller.
- Kept the download-path edit narrow after an initial over-broad error-logging wrapper made the method harder to review.
- Removed the dedicated logging test at the reviewer’s request.
- Restored `VXDATA_TELEMETRY_DIR` as minimal standard logging configuration in `vxdata/sdk/logging.py`: it attaches a process-specific JSONL `FileHandler` to `vxdata.sdk`, without restoring the custom telemetry sink.
- Manually smoke-tested JSONL file creation, then ran SDK format, lint, typecheck, and all 41 remaining tests successfully; left monorepo changes uncommitted for review.
- Read Copilot's PR review: confirmed unresolved destination-path collisions, unconditional 416 handling, known-size `Content-Range` drift, and blocking S3 HEAD work inside an async FastAPI route; the telemetry lifecycle and docstring comments are superseded by later changes.
- Fixed the relevant API finding by making `/s3/presign/batch` synchronous so FastAPI runs its blocking MinIO HEAD work in a worker thread; API quality checks and five storage service tests passed.
- Cleared the route lint surfaced by staging `storage.py`: `read_parquet` now raises `ValueError` and relies on the API's global 400 handler instead of raising `HTTPException` directly.
- Ran the thermo-nuclear maintainability review. The strongest simplification is to remove or isolate the unknown-size legacy probe path, then delete stale download/list helpers; additional findings cover untyped storage wire envelopes, duplicate concurrency knobs, repeated direct-mode selection, shared-logger mutation, and concurrent URL-refresh duplication.

## Lessons Learned: Pitfalls

- The infrastructure SOP index was broader than needed for this read-only code comparison. The repository's local API guide and exact git objects were the useful sources.
- The batch-presign endpoint already existed at the base, but base downloads did not call it. Looking only at route existence would have produced an incorrect graph.
- The old SDK README was already obsolete, so separating useful documentation repair from PR-specific claims required checking the base implementation.

## Lessons Learned: Improvements

- For storage reviews, distinguish endpoint availability from the SDK path that actually invokes it.
- Compare both direct-object and prefix downloads. Their size discovery differs at `HEAD`: direct objects request sizes during batch presign, while prefix listings already carry sizes.
- Prefer application-configured structured logging for SDK diagnostics unless an SDK-owned file sink has a firm requirement and explicit lifecycle, rollover, and writer semantics.
- README examples should be exercised as snippets; this review found inconsistent client variable names and an incorrect shape-preservation claim.

Source: https://docs.virdx.dev/knowledge/inbox/2026-08-25-infrastructure-vxdata-storage-call-graph-inspection/index.mdx