Multi-sink / `tee` Python API #10158

jprochazk · 2025-06-07T17:11:01Z

What

We want some kind of "log to multiple sinks" API, which would alleviate some long-standing issues:

Saving data to a file in case the Viewer crashes.
Saving a larger-than-RAM recording to a file that's also being streamed to a Viewer, which will GC and drop large portions of it in an unrecoverable way.

API Additions

The entrypoint for this in the Python SDK would be tee on RecordingStream:

import rerun as rr
from rerun.utilities import build_color_grid

rec = rr.RecordingStream("rerun_example_tee")
rec.tee(rr.FileSink("data.rrd"), rr.GrpcSink())

grid = build_color_grid()
rec.log("points", rr.Points3D(positions=grid.positions, colors=grid.colors))

The above snippets are functional on this PR. You must start a Viewer (or gRPC server) to connect to before running it. It logs the data to both the server and a data.rrd file.

The exposed FileSink and GrpcSink are simple dataclasses that temporarily hold information for how to setup the sink:

FileSink stores a path
GrpcSink stores a url, along with a flush timeout

The tee call then converts these sinks into their Rust equivalents, wraps them in a MultiSink, and calls set_sink on that.

Calling set_sink ensures the usual "dump backlog into the new sink" behavior is preserved, so that the initial SetStoreInfo logged by rr.init is sent through to every sink correctly.

The sink that's being set is the new MultiSink, a wrapper over Vec<Box<dyn LogSink>> which clones all received messages to every stored sink.

Currently only FileSink and GrpcSink are available. A user may use the same kind of sink multiple times, but there must not be any duplicates. For example, two GrpcSink with the same url would count as duplicates.

Open questions

What other sinks should be exposed?
- BufferedSink doesn't make that much sense. It's something we use to temporarily hold data in memory (specifically only a SetStoreInfo message) before the user sets up a real "endpoint" sink, like GRPC or a file.
- MemorySink and CallbackSink are important, as they interact with Notebook/Gradio/JS integration. We should allow for example sending data to a Viewer embedded in a notebook, and saving the same data to a file at the same time.
Needs name bikeshedding, tee makes sense, but isn't very discoverable.
Can we avoid the extra overhead of cloning all messages to every sink?
- The current LogSink trait makes this impossible, as it requires that every stored sink be passed an owned LogMsg.

github-actions · 2025-06-07T17:12:28Z

Web viewer built successfully. If applicable, you should also test it:

I have tested the web viewer

Result	Commit	Link	Manifest
✅	`af8ee6f`	https://rerun.io/viewer/pr/10158	`+nightly` `+main`

^{Note: This comment is updated whenever you push a commit.}

jleibs

Clever solution.

Not having sink-objects was the big issue we ran into before, and you kind of side-stepped that by not making, e.g. GrpcSink a first-class wrapper on top of the rust-side sinks. I don't remember why that was hard before, or if it was just work.

This could still serve as a stepping stone in that direction though.

rerun_py/rerun_sdk/rerun/sinks.py

rerun_py/src/python_bridge.rs

nikolausWest · 2025-06-10T08:01:31Z

In general I think this looks great but I think we should skip the rr.tee() api and stick to the api on the rr.RecordingStream object. Other than than let's land it!

nikolausWest · 2025-06-10T08:02:46Z

rerun_py/rerun_sdk/rerun/recording_stream.py

+
+        Duplicate sinks are not allowed. For example, two [`GrpcSink`]s that
+        use the same `url`.
+        """


Example code might be useful here

nikolausWest · 2025-06-10T08:04:59Z

This feature will also require a how-to guide and perhaps a look over our docs in general to make sure it's discoverable. That means it should be referenced to in the right places where one might wonder about it (e.g. in the rr.init docs) fyi @pweids

Wumpf · 2025-06-13T14:27:31Z

@pweids / @nikolausWest / @jprochazk are we still taking this on for 0.24 or do we think it's too much too soon?
(I know we'd all love to have it, but seems like yet-another-feature?)

jprochazk · 2025-06-13T14:37:29Z

It's not far from completion, I think we should land it for 0.24

abey79

Very nice feature to have! My main concern is about future-proofing the naming, but I don't have the context if prior discussions that might have happened previously.

abey79 · 2025-06-19T13:37:09Z

crates/top/re_sdk/src/log_sink.rs

+    // NOTE: this is only really used for BufferedSink,
+    //       and by the time you `set_sink` you probably don't have
+    //       a buffered sink anymore
+    #[inline]
+    fn drain_backlog(&self) -> Vec<LogMsg> {
+        Vec::new()
+    }


Trusting you here—I don't have a deep enough understanding of that stuff to make a call.

Another thing which I didn't write here: which sink do you pick to call drain_backlog on? It's not clear to me at all, but luckily we probably don't need to worry about that, since you can't insert a BufferedSink into a MultiSink as a user

rerun_py/src/python_bridge.rs

abey79 · 2025-06-19T13:54:23Z

rerun_py/rerun_sdk/rerun/recording_stream.py

    get_recording_id = get_recording_id
    is_enabled = is_enabled

+    def tee(


Has there been discussion about this choice of name?

I suggest using set_sinks() instead, because it's more explicit, and it is also more future-proof (ie. I would like to drop all these weird save(), etc. APIs in favour of exposing all sinks and being explicit with plugging a stream onto them).

I agree that tee probably isn't the best name, but I like it more than set_sinks. Another followup to the list, properly document this everywhere we talk about operating modes.

I'm going to start a bikeshedding thread in Slack, since we have some time until 0.24 to change it, but leave it as is for now and merge

https://rerunio.slack.com/archives/C033K5VS2KD/p1750343062698689

The name tee suggests two sinks, which seems arbitrary to me. Wouldn't it be cleaner to have 2 (or more) calls to something like add_sink?

We decided on .attach_sinks in the slack thread. I'll merge this as-is (with review other comments addressed) and do that in a follow-up PR

Wouldn't it be cleaner to have 2 (or more) calls to something like add_sink?

The way this works under the hood would make any kind of "add sink" operation a bit more complicated. The presence of that initial SetStoreInfo message means we must set all the sinks "at once"

wip

4a431cc

jprochazk changed the title ~~RFC: Multi-sink / tee API~~ RFC: Multi-sink / tee Python API Jun 7, 2025

jprochazk added 2 commits June 7, 2025 20:15

add RecordingStream.tee

be974a6

fix lints

75c9c9c

jprochazk added enhancement New feature or request sdk-python Python logging API labels Jun 9, 2025

jprochazk added this to the 0.24.0 milestone Jun 9, 2025

jleibs reviewed Jun 9, 2025

View reviewed changes

rerun_py/rerun_sdk/rerun/sinks.py Outdated Show resolved Hide resolved

rerun_py/src/python_bridge.rs Outdated Show resolved Hide resolved

nikolausWest reviewed Jun 10, 2025

View reviewed changes

jprochazk added 12 commits June 18, 2025 12:34

Merge branch 'main' into jan/tee

cc9dd73

expose sinks directly from Rust

58bf006

add snippet

24dbfe4

undo unintentional change

b959bbb

fix GrpcSink signature

5927b50

use stateless api in tee snippet

8349ebb

don't expose stateful rr.tee

84413d5

fix mypy error

4c62ad6

add sinks to gen_common_index

fe59738

document sinks in rerun_bindings.pyi

e2d9c98

document RecordingStream.tee

d4734fd

update index

17f62e1

jprochazk added the include in changelog label Jun 18, 2025

jprochazk changed the title ~~RFC: Multi-sink / tee Python API~~ Multi-sink / tee Python API Jun 18, 2025

jprochazk marked this pull request as ready for review June 18, 2025 11:56

fix clippy lint

244f73b

fix type signatures

a1e4757

abey79 self-requested a review June 19, 2025 13:14

abey79 approved these changes Jun 19, 2025

View reviewed changes

jprochazk added 3 commits June 20, 2025 11:39

Merge branch 'main' into jan/tee

965f4c1

use pathbuf

860940f

fix annotation

af8ee6f

jprochazk merged commit 3b75b7a into main Jun 20, 2025
41 checks passed

jprochazk deleted the jan/tee branch June 20, 2025 10:36

jprochazk mentioned this pull request Jun 20, 2025

Rename to tee to set_sinks #10312

Merged

Multi-sink / tee Python API #10158

Multi-sink / tee Python API #10158

Uh oh!

Conversation

jprochazk commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

API Additions

Open questions

Uh oh!

github-actions bot commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jleibs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nikolausWest commented Jun 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nikolausWest commented Jun 10, 2025

Uh oh!

Wumpf commented Jun 13, 2025

Uh oh!

jprochazk commented Jun 13, 2025

Uh oh!

abey79 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jprochazk Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Multi-sink / `tee` Python API #10158

Multi-sink / `tee` Python API #10158

jprochazk commented Jun 7, 2025 •

edited

Loading

github-actions bot commented Jun 7, 2025 •

edited

Loading

jprochazk Jun 20, 2025 •

edited

Loading