Expose raft::memory_tracking_resources to C/Python/Java/Rust

c/include/cuvs/core/c_api.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -87,6 +87,33 @@ typedef uintptr_t cuvsResources_t;
  */
 CUVS_EXPORT cuvsError_t cuvsResourcesCreate(cuvsResources_t* res);
 
+/**
+ * @brief Create an opaque C handle for C++ type `raft::resources` whose memory
+ *        allocations are tracked and written as CSV samples from a background
+ *        thread.
+ *
+ * The returned handle wraps all reachable memory resources (host, pinned,
+ * managed, device, workspace, large_workspace) with allocation-tracking
+ * adaptors and replaces the global host and device memory resources for the
+ * lifetime of the handle. It is otherwise indistinguishable from a handle
+ * created by ::cuvsResourcesCreate and can be used wherever a
+ * ::cuvsResources_t is accepted. The CSV reporter is stopped and the global
+ * memory resources are restored when the handle is destroyed via
+ * ::cuvsResourcesDestroy.
+ *
+ * @param[out] res                 cuvsResources_t opaque C handle
+ * @param[in]  csv_path            Path to the output CSV file
+ *                                 (created/truncated). Must be a non-empty,
+ *                                 null-terminated UTF-8 string.
+ * @param[in]  sample_interval_ms  Minimum time in milliseconds between
+ *                                 successive CSV samples. Pass 10 to match the
+ *                                 C++ default.
+ * @return cuvsError_t
+ */
+CUVS_EXPORT cuvsError_t cuvsResourcesCreateWithMemoryTracking(cuvsResources_t* res,
+                                                              const char* csv_path,
+                                                              int64_t sample_interval_ms);
+
 /**
  * @brief Destroy and de-allocate opaque C handle for C++ type `raft::resources`
  *

c/src/core/c_api.cpp

@@ -1,12 +1,13 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #include <cuvs/core/c_api.h>
 #include <cuvs/version_config.h>
 
 #include <raft/core/device_resources_snmg.hpp>
+#include <raft/core/memory_tracking_resources.hpp>
 #include <raft/core/resource/cuda_stream.hpp>
 #include <raft/core/resource/device_id.hpp>
 #include <raft/core/resource/resource_types.hpp>
@@ -23,8 +24,11 @@
 
 #include "../core/exceptions.hpp"
 
+#include <chrono>
 #include <cstdint>
 #include <memory>
+#include <stdexcept>
+#include <string>
 #include <thread>
 
 extern "C" cuvsError_t cuvsResourcesCreate(cuvsResources_t* res)
@@ -35,6 +39,23 @@ extern "C" cuvsError_t cuvsResourcesCreate(cuvsResources_t* res)
   });
 }
 
+extern "C" cuvsError_t cuvsResourcesCreateWithMemoryTracking(cuvsResources_t* res,
+                                                             const char* csv_path,
+                                                             int64_t sample_interval_ms)
+{
+  return cuvs::core::translate_exceptions([=] {
+    if (csv_path == nullptr || csv_path[0] == '\0') {
+      throw std::invalid_argument("csv_path must be a non-empty string");
+    }
+    if (sample_interval_ms < 0) {
+      throw std::invalid_argument("sample_interval_ms must be >= 0");
+    }
+    auto res_ptr = new raft::memory_tracking_resources{
+      std::string{csv_path}, std::chrono::milliseconds{sample_interval_ms}};
+    *res = reinterpret_cast<uintptr_t>(res_ptr);
+  });
+}
+
 extern "C" cuvsError_t cuvsResourcesDestroy(cuvsResources_t res)
 {
   return cuvs::core::translate_exceptions([=] {

fern/pages/api_basics.md

@@ -2,6 +2,7 @@
 
 - [Memory management](#memory-management)
 - [Resource management](#resource-management)
+- [Memory tracking](#memory-tracking)
 
 ## Memory management
 
@@ -78,3 +79,85 @@ res = pylibraft.common.DeviceResources()
 ```rust
 let res = cuvs::Resources::new()?;
 ```
+
+## Memory tracking
+
+A resources handle whose memory allocations are tracked and written as CSV samples from a background thread can be created in any of the supported languages. The handle wraps all reachable memory resources (host, pinned, managed, device, workspace, large_workspace) with allocation-tracking adaptors and replaces the global host and device memory resources for the lifetime of the handle. It is otherwise indistinguishable from a regular resources handle and can be passed to every cuVS API that accepts one. The CSV reporter is stopped and the global memory resources are restored when the handle is destroyed.
+
+<Note>
+
+- The handle replaces the **global** host and device memory resources while it is alive. Do not create multiple tracking handles concurrently and make sure the handle outlives every consumer (matrices, indexes, search results, ...) that allocates memory through cuVS.
+- The CSV file is flushed eagerly: the header is flushed on construction and every sample row is flushed as soon as it is written, so the file can be tailed while the handle is alive. Destroying the handle stops the background sampler and writes one final row.
+- The sample interval is a *minimum* time between samples. The background thread blocks until an allocation/deallocation occurs, then sleeps for at least `sample_interval` before writing the next row; quiescent periods do not produce extra rows.
+
+</Note>
+
+### C
+
+```c
+#include <cuda_runtime.h>
+#include <cuvs/core/c_api.h>
+
+cuvsResources_t res;
+// 10 ms sampling matches the C++ default.
+cuvsResourcesCreateWithMemoryTracking(&res, "/tmp/allocations.csv", 10);
+
+// ... do some processing ...
+
+cuvsResourcesDestroy(res);
+```
+
+### C++
+
+```c++
+#include <raft/core/memory_tracking_resources.hpp>
+
+// Sample interval defaults to std::chrono::milliseconds{10}.
+raft::memory_tracking_resources res{"/tmp/allocations.csv"};
+
+// ... do some processing ...
+// `res` is implicitly convertible to raft::resources& and can be passed
+// to any cuVS / raft API that accepts a resources handle.
+```
+
+### Python
+
+```python
+from cuvs.common import Resources
+
+res = Resources(
+    memory_tracking_csv_path="/tmp/allocations.csv",
+    memory_tracking_sample_interval_ms=10,
+)
+
+# ... do some processing ...
+
+del res  # flushes the CSV and restores the global memory resources
+```
+
+### Java
+
+```java
+import com.nvidia.cuvs.CuVSResources;
+import com.nvidia.cuvs.spi.CuVSProvider;
+import java.nio.file.Path;
+import java.time.Duration;
+
+try (var res = CuVSResources.create(
+        CuVSProvider.tempDirectory(),
+        Path.of("/tmp/allocations.csv"),
+        Duration.ofMillis(10))) {
+    // ... do some processing ...
+}
+```
+
+### Rust
+
+```rust
+use std::time::Duration;
+
+let res = cuvs::Resources::with_memory_tracking(
+    "/tmp/allocations.csv",
+    Some(Duration::from_millis(10)),
+)?;
+```

fern/pages/other/memory_management.md

@@ -466,3 +466,9 @@ Use a pool for repeatable performance measurements. Allocator behavior can other
 Keep the memory resource alive for at least as long as the allocations that use it. In C++ this means the pool object must outlive arrays allocated from it. In C, Java, Rust, and Go this means resetting the NVIDIA cuVS memory resource after NVIDIA cuVS objects have been destroyed.
 
 Avoid changing memory resources in the middle of a workflow unless the application has a clear ownership boundary. The safest pattern is to configure once, allocate and run NVIDIA cuVS work, destroy NVIDIA cuVS objects, then reset.
+
+### Tracking memory usage
+
+To understand how much memory a workload allocates over time, create a resources handle that tracks its allocations and writes CSV samples from a background thread.
+This wraps all reachable memory resources with allocation-tracking adaptors and logs a timeline that can be tailed while the handle is alive.
+See [Memory tracking](/user-guide/api-guides/core-types/resources#memory-tracking) in the Resources guide for the per-language usage examples and caveats.

fern/pages/other/resources.md

@@ -510,12 +510,113 @@ raft::resource::set_large_workspace_resource(
 | --- | --- | --- |
 | `raft::device_resources` | Single-GPU C++ APIs | The usual C++ resources object for one GPU. |
 | `raft::resources` | Lower-level C++ RAFT and NVIDIA cuVS APIs | A resource container used by C++ algorithms and advanced applications. |
+| `raft::memory_tracking_resources` | C++ diagnostics | A `raft::resources` handle that wraps all reachable memory resources and logs allocation samples to a CSV file from a background thread. See [Memory tracking](#memory-tracking). |
+| `raft::memory_stats_resources` | C++ diagnostics | A `raft::resources` handle that wraps all reachable memory resources with statistics adaptors so peak/current byte usage and allocation counts can be queried in-process via `get_bytes_peak()`, `get_bytes_current()`, and related accessors. |
 | `raft::device_resources_snmg` | Single-node multi-GPU C++ APIs | A convenience layer for one process controlling multiple GPUs. See [Multi-GPU](/user-guide/api-guides/core-types/multi-gpu). |
 | `cuvsResources_t` | C API and language bindings | Opaque handle over RAFT resources for ABI-stable bindings. |
 | `Resources` | Python and Rust | Language wrapper around `cuvsResources_t`. |
 | `Resource` | Go | Go wrapper around `cuvsResources_t`. |
 | `CuVSResources` | Java | Java `AutoCloseable` wrapper around native NVIDIA cuVS resources. |
 
+
+### Memory tracking
+
+A resources handle whose memory allocations are tracked and written as CSV samples from a background thread can be created in any of the supported languages.
+The handle wraps all reachable memory resources (host, pinned, managed, device, workspace, large_workspace) with allocation-tracking adaptors and replaces the global host and device memory resources for the lifetime of the handle.
+It is otherwise indistinguishable from a regular resources handle and can be passed to every NVIDIA cuVS API that accepts one.
+The CSV reporter is stopped and the global memory resources are restored when the handle is destroyed.
+
+<Note>
+
+- The handle replaces the **global** host and device memory resources while it is alive.
+  Do not create multiple tracking handles concurrently and make sure the handle outlives every consumer (matrices, indexes, search results, ...) that allocates memory through NVIDIA cuVS.
+- The CSV file is flushed eagerly: the header is flushed on construction and every sample row is flushed as soon as it is written, so the file can be tailed while the handle is alive.
+  This helps during debugging, if the program has segfaulted.
+  Destroying the handle stops the background sampler and writes one final row.
+- The sample interval is a *minimum* time between samples.
+  The background thread blocks until an allocation/deallocation occurs, then sleeps for at least `sample_interval` before writing the next row; quiescent periods do not produce extra rows.
+
+</Note>
+
+<Tabs>
+<Tab title="C">
+
+```c
+#include <cuvs/core/c_api.h>
+
+#include <cuda_runtime.h>
+
+cuvsResources_t res;
+// 10 ms sampling matches the C++ default.
+cuvsResourcesCreateWithMemoryTracking(&res, "/tmp/allocations.csv", 10);
+
+// ... do some processing ...
+
+cuvsResourcesDestroy(res);
+```
+
+</Tab>
+<Tab title="C++">
+
+```cpp
+#include <raft/core/memory_tracking_resources.hpp>
+
+// Sample interval defaults to std::chrono::milliseconds{10}.
+raft::memory_tracking_resources res{"/tmp/allocations.csv"};
+
+// ... do some processing ...
+// `res` is implicitly convertible to raft::resources& and can be passed
+// to any cuVS / RAFT API that accepts a resources handle.
+```
+
+</Tab>
+<Tab title="Python">
+
+```python
+from cuvs.common import Resources
+
+res = Resources(
+    memory_tracking_csv_path="/tmp/allocations.csv",
+    memory_tracking_sample_interval_ms=10,
+)
+
+# ... do some processing ...
+
+del res  # flushes the CSV and restores the global memory resources
+```
+
+</Tab>
+<Tab title="Java">
+
+```java
+import com.nvidia.cuvs.CuVSResources;
+import com.nvidia.cuvs.spi.CuVSProvider;
+import java.nio.file.Path;
+import java.time.Duration;
+
+try (var res = CuVSResources.create(
+        CuVSProvider.tempDirectory(),
+        Path.of("/tmp/allocations.csv"),
+        Duration.ofMillis(10))) {
+    // ... do some processing ...
+}
+```
+
+</Tab>
+<Tab title="Rust">
+
+```rust
+use std::time::Duration;
+
+let res = cuvs::Resources::with_memory_tracking(
+    "/tmp/allocations.csv",
+    Some(Duration::from_millis(10)),
+)?;
+```
+
+</Tab>
+</Tabs>
+
 ## Practical Guidance
 
 Use the default resources behavior for simple one-off calls.

java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java

@@ -1,11 +1,12 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 package com.nvidia.cuvs;
 
 import com.nvidia.cuvs.spi.CuVSProvider;
 import java.nio.file.Path;
+import java.time.Duration;
 
 /**
  * Used for allocating resources for cuVS
@@ -78,4 +79,34 @@ static CuVSResources create() throws Throwable {
   static CuVSResources create(Path tempDirectory) throws Throwable {
     return CuVSProvider.provider().newCuVSResources(tempDirectory);
   }
+
+  /**
+   * Creates a new resources whose memory allocations are tracked and written as
+   * CSV samples from a background thread.
+   * <p>
+   * The returned handle wraps all reachable memory resources (host, pinned,
+   * managed, device, workspace, large_workspace) with allocation-tracking
+   * adaptors and replaces the global host and device memory resources for the
+   * lifetime of the handle. It is otherwise indistinguishable from a handle
+   * created by {@link #create(Path)} and can be used wherever a
+   * {@link CuVSResources} is accepted. The CSV reporter is stopped and the
+   * global memory resources are restored when the handle is closed.
+   *
+   * @param tempDirectory                   the temporary directory to use for
+   *                                        intermediate operations
+   * @param memoryTrackingCsvPath           path to the output CSV file
+   *                                        (created/truncated)
+   * @param memoryTrackingSampleInterval    minimum interval between successive
+   *                                        CSV samples
+   * @throws UnsupportedOperationException if the provider does not support cuvs
+   * @throws LibraryException if the native library cannot be loaded
+   */
+  static CuVSResources create(
+      Path tempDirectory,
+      Path memoryTrackingCsvPath,
+      Duration memoryTrackingSampleInterval) throws Throwable {
+    return CuVSProvider.provider()
+        .newCuVSResources(
+            tempDirectory, memoryTrackingCsvPath, memoryTrackingSampleInterval);
+  }
 }