A RecordingStream handles everything related to logging data into Rerun. More...

#include <rerun/recording_stream.hpp>

Public Member Functions
	RecordingStream (std::string_view app_id, std::string_view recording_id=std::string_view(), StoreKind store_kind=StoreKind::Recording)
	Creates a new recording stream to log to.

Properties
StoreKind	kind () const
	Returns the store kind as passed during construction.

bool	is_enabled () const
	Returns whether the recording stream is enabled.

Directing the recording stream.
Either of these needs to be called, otherwise the stream will buffer up indefinitely.
Error	connect (std::string_view tcp_addr="127.0.0.1:9876", float flush_timeout_sec=2.0) const
	Connect to a remote Rerun Viewer on the given ip:port.

Error	spawn (const SpawnOptions &options={}, float flush_timeout_sec=2.0) const
	Spawns a new Rerun Viewer process from an executable available in PATH, then connects to it over TCP.

template<typename TRep , typename TPeriod >
Error	spawn (const SpawnOptions &options={}, std::chrono::duration< TRep, TPeriod > flush_timeout=std::chrono::seconds(2)) const

Error	save (std::string_view path) const
	Stream all log-data to a given `.rrd` file.

Error	to_stdout () const
	Stream all log-data to standard output.

void	flush_blocking () const
	Initiates a flush the batching pipeline and waits for it to propagate.

Controlling log time.
void	set_time_sequence (std::string_view timeline_name, int64_t sequence_nr) const
	Set the current time of the recording, for the current calling thread.

template<typename TClock >
void	set_time (std::string_view timeline_name, std::chrono::time_point< TClock > time) const
	Set the current time of the recording, for the current calling thread.

template<typename TRep , typename TPeriod >
void	set_time (std::string_view timeline_name, std::chrono::duration< TRep, TPeriod > time) const
	Set the current time of the recording, for the current calling thread.

void	set_time_seconds (std::string_view timeline_name, double seconds) const
	Set the current time of the recording, for the current calling thread.

void	set_time_nanos (std::string_view timeline_name, int64_t nanos) const
	Set the current time of the recording, for the current calling thread.

void	disable_timeline (std::string_view timeline_name) const
	Stops logging to the specified timeline for subsequent log calls.

void	reset_time () const
	Clears out the current time of the recording, for the current calling thread.

Logging
template<typename... Ts>
void	log (std::string_view entity_path, const Ts &... archetypes_or_collectiones) const
	Logs one or more archetype and/or component batches.

template<typename... Ts>
void	log_timeless (std::string_view entity_path, const Ts &... archetypes_or_collectiones) const
	Logs one or more archetype and/or component batches as timeless data.

template<typename... Ts>
Error	try_log (std::string_view entity_path, const Ts &... archetypes_or_collectiones) const
	Logs one or more archetype and/or component batches.

template<typename... Ts>
Error	try_log_timeless (std::string_view entity_path, const Ts &... archetypes_or_collectiones) const
	Logs one or more archetype and/or component batches as timeless data, returning an error.

template<typename... Ts>
void	log_with_timeless (std::string_view entity_path, bool timeless, const Ts &... archetypes_or_collectiones) const
	Logs one or more archetype and/or component batches optionally timeless, returning an error.

template<typename... Ts>
Error	try_log_with_timeless (std::string_view entity_path, bool timeless, const Ts &... archetypes_or_collectiones) const
	Logs one or more archetype and/or component batches optionally timeless, returning an error.

Error	try_log_serialized_batches (std::string_view entity_path, bool timeless, std::vector< DataCell > batches) const
	Logs several serialized batches batches, returning an error on failure.

Error	try_log_data_row (std::string_view entity_path, size_t num_instances, size_t num_data_cells, const DataCell *data_cells, bool inject_time) const
	Bottom level API that logs raw data cells to the recording stream.

void	log_file_from_path (const std::filesystem::path &filepath, std::string_view entity_path_prefix=std::string_view(), bool timeless=false) const
	Logs the file at the given `path` using all `DataLoader`s available.

Error	try_log_file_from_path (const std::filesystem::path &filepath, std::string_view entity_path_prefix=std::string_view(), bool timeless=false) const
	Logs the file at the given `path` using all `DataLoader`s available.

void	log_file_from_contents (const std::filesystem::path &filepath, const std::byte *contents, size_t contents_size, std::string_view entity_path_prefix=std::string_view(), bool timeless=false) const
	Logs the given `contents` using all `DataLoader`s available.

Error	try_log_file_from_contents (const std::filesystem::path &filepath, const std::byte *contents, size_t contents_size, std::string_view entity_path_prefix=std::string_view(), bool timeless=false) const
	Logs the given `contents` using all `DataLoader`s available.

Controlling globally available instances of RecordingStream.
void	set_global () const
	Replaces the currently active recording for this stream's store kind in the global scope with this one.

void	set_thread_local () const
	Replaces the currently active recording for this stream's store kind in the thread-local scope with this one.

static RecordingStream &	current (StoreKind store_kind=StoreKind::Recording)
	Retrieves the most appropriate globally available recording stream for the given kind.

Detailed Description

A RecordingStream handles everything related to logging data into Rerun.

Multithreading and ordering

A RecordingStream is thread-safe.

Internally, all operations are linearized into a pipeline:

All operations sent by a given thread will take effect in the same exact order as that thread originally sent them in, from its point of view.
There isn't any well defined global order across multiple threads.

This means that e.g. flushing the pipeline (flush_blocking) guarantees that all previous data sent by the calling thread has been recorded; no more, no less. (e.g. it does not mean that all file caches are flushed)

Shutdown

The RecordingStream can only be shutdown by dropping all instances of it, at which point it will automatically take care of flushing any pending data that might remain in the pipeline.

TODO(andreas): The only way of having two instances of a RecordingStream is currently to set it as a the global.

Shutting down cannot ever block.

Logging

Internally, the stream will automatically micro-batch multiple log calls to optimize transport. See SDK Micro Batching for more information.

The data will be timestamped automatically based on the RecordingStream's internal clock.

Constructor & Destructor Documentation

◆ RecordingStream()

rerun::RecordingStream::RecordingStream	(	std::string_view	app_id,
		std::string_view	recording_id = `std::string_view()`,
		StoreKind	store_kind = `StoreKind::Recording`
	)

Creates a new recording stream to log to.

Parameters

app_id	The user-chosen name of the application doing the logging.
recording_id	The user-chosen name of the recording being logged to.
store_kind	Whether to log to the recording store or the blueprint store.

Member Function Documentation

◆ is_enabled()

bool rerun::RecordingStream::is_enabled ( ) const

inline

Returns whether the recording stream is enabled.

All log functions early out if a recording stream is disabled. Naturally, logging functions that take unserialized data will skip the serialization step as well.

◆ set_global()

void rerun::RecordingStream::set_global ( ) const

Replaces the currently active recording for this stream's store kind in the global scope with this one.

Afterwards, destroying this recording stream will not change the global recording stream, as it increases an internal ref-count.

◆ set_thread_local()

void rerun::RecordingStream::set_thread_local ( ) const

Replaces the currently active recording for this stream's store kind in the thread-local scope with this one.

Afterwards, destroying this recording stream will not change the thread local recording stream, as it increases an internal ref-count.

◆ current()

static RecordingStream & rerun::RecordingStream::current ( StoreKind store_kind = StoreKind::Recording )

static

Retrieves the most appropriate globally available recording stream for the given kind.

I.e. thread-local first, then global. If neither was set, any operations on the returned stream will be no-ops.

◆ connect()

Error rerun::RecordingStream::connect	(	std::string_view	tcp_addr = `"127.0.0.1:9876"`,
		float	flush_timeout_sec = `2.0`
	)		const

Connect to a remote Rerun Viewer on the given ip:port.

Requires that you first start a Rerun Viewer by typing 'rerun' in a terminal.

flush_timeout_sec: The minimum time the SDK will wait during a flush before potentially dropping data if progress is not being made. Passing a negative value indicates no timeout, and can cause a call to flush to block indefinitely.

This function returns immediately.

◆ spawn() [1/2]

Error rerun::RecordingStream::spawn	(	const SpawnOptions &	options = `{}`,
		float	flush_timeout_sec = `2.0`
	)		const

Spawns a new Rerun Viewer process from an executable available in PATH, then connects to it over TCP.

If a Rerun Viewer is already listening on this TCP port, the stream will be redirected to that viewer instead of starting a new one.

Parameters

options: See rerun::SpawnOptions for more information.

flush_timeout_sec: The minimum time the SDK will wait during a flush before potentially dropping data if progress is not being made. Passing a negative value indicates no timeout, and can cause a call to flush to block indefinitely.

◆ spawn() [2/2]

template<typename TRep , typename TPeriod >

Error rerun::RecordingStream::spawn	(	const SpawnOptions &	options = `{}`,
		std::chrono::duration< TRep, TPeriod >	flush_timeout = `std::chrono::seconds(2)`
	)		const

inline

See also: RecordingStream::spawn

◆ save()

Error rerun::RecordingStream::save ( std::string_view path ) const

Stream all log-data to a given .rrd file.

This function returns immediately.

◆ to_stdout()

Error rerun::RecordingStream::to_stdout ( ) const

Stream all log-data to standard output.

Pipe the result into the Rerun Viewer to visualize it.

If there isn't any listener at the other end of the pipe, the RecordingStream will default back to buffered mode, in order not to break the user's terminal.

This function returns immediately.

◆ flush_blocking()

void rerun::RecordingStream::flush_blocking ( ) const

Initiates a flush the batching pipeline and waits for it to propagate.

See RecordingStream docs for ordering semantics and multithreading guarantees.

◆ set_time_sequence()

void rerun::RecordingStream::set_time_sequence	(	std::string_view	timeline_name,
		int64_t	sequence_nr
	)		const

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time_sequence("frame_nr", frame_nr).

You can remove a timeline from subsequent log calls again using rec.disable_timeline.

See also: set_time_seconds, set_time_nanos, reset_time, set_time, disable_timeline

◆ set_time() [1/2]

template<typename TClock >

void rerun::RecordingStream::set_time	(	std::string_view	timeline_name,
		std::chrono::time_point< TClock >	time
	)		const

inline

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time("sim_time", sim_time_secs).

You can remove a timeline from subsequent log calls again using rec.disable_timeline.

See also: set_time_sequence, set_time_seconds, set_time_nanos, reset_time, disable_timeline

◆ set_time() [2/2]

template<typename TRep , typename TPeriod >

void rerun::RecordingStream::set_time	(	std::string_view	timeline_name,
		std::chrono::duration< TRep, TPeriod >	time
	)		const

inline

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time("sim_time", sim_time_secs).

You can remove a timeline from subsequent log calls again using rec.disable_timeline.

See also: set_time_sequence, set_time_seconds, set_time_nanos, reset_time, disable_timeline

◆ set_time_seconds()

void rerun::RecordingStream::set_time_seconds	(	std::string_view	timeline_name,
		double	seconds
	)		const

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time_seconds("sim_time", sim_time_secs).

You can remove a timeline from subsequent log calls again using rec.disable_timeline.

See also: set_time_sequence, set_time_nanos, reset_time, set_time, disable_timeline

◆ set_time_nanos()

void rerun::RecordingStream::set_time_nanos	(	std::string_view	timeline_name,
		int64_t	nanos
	)		const

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time_nanos("sim_time", sim_time_nanos).

You can remove a timeline from subsequent log calls again using rec.disable_timeline.

See also: set_time_sequence, set_time_seconds, reset_time, set_time, disable_timeline

◆ disable_timeline()

void rerun::RecordingStream::disable_timeline ( std::string_view timeline_name ) const

Stops logging to the specified timeline for subsequent log calls.

The timeline is still there, but will not be updated with any new data.

No-op if the timeline doesn't exist.

See also: set_time_sequence, set_time_seconds, set_time, reset_time

◆ reset_time()

void rerun::RecordingStream::reset_time ( ) const

Clears out the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.reset_time().

See also: set_time_sequence, set_time_seconds, set_time_nanos, disable_timeline

◆ log()

template<typename... Ts>

void rerun::RecordingStream::log	(	std::string_view	entity_path,
		const Ts &...	archetypes_or_collectiones
	)		const

inline

Logs one or more archetype and/or component batches.

This is the main entry point for logging data to rerun. It can be used to log anything that implements the AsComponents<T> trait.

When logging data, you must always provide an entity_path for identifying the data. Note that the path prefix "rerun/" is considered reserved for use by the Rerun SDK itself and should not be used for logging user data. This is where Rerun will log additional information such as warnings.

The most common way to log is with one of the rerun archetypes, all of which implement the AsComponents trait.

For example, to log two 3D points:

rec.log("my/point", rerun::Points3D({{0.0f, 0.0f, 0.0f}, {1.0f, 1.0f, 1.0f}}));

rerun::archetypes::Points3D

Archetype: A 3D point cloud with positions and optional colors, radii, labels, etc.

Definition points3d.hpp:66

The log function can flexibly accept an arbitrary number of additional objects which will be merged into the first entity so long as they don't expose conflicting components, for instance:

// Log three points with arrows sticking out of them:
rec.log(
    "my/points",
    rerun::Points3D({{0.2f, 0.5f, 0.3f}, {0.9f, 1.2f, 0.1f}, {1.0f, 4.2f, 0.3f}})
            .with_radii({0.1, 0.2, 0.3}),
    rerun::Arrows3D::from_vectors({{0.3f, 2.1f, 0.2f}, {0.9f, -1.1, 2.3f}, {-0.4f, 0.5f, 2.9f}})
);

Any failures that may occur during serialization are handled with Error::handle.

Parameters

entity_path	Path to the entity in the space hierarchy.
archetypes_or_collectiones	Any type for which the `AsComponents<T>` trait is implemented. This is the case for any archetype or `std::vector`/`std::array`/C-array of components implements.

See also: try_log, log_timeless, try_log_with_timeless

◆ log_timeless()

template<typename... Ts>

void rerun::RecordingStream::log_timeless	(	std::string_view	entity_path,
		const Ts &...	archetypes_or_collectiones
	)		const

inline

Logs one or more archetype and/or component batches as timeless data.

Like log but logs the data as timeless: Timeless data is present on all timelines and behaves as if it was recorded infinitely far into the past.

Failures are handled with Error::handle.

Parameters

entity_path	Path to the entity in the space hierarchy.
archetypes_or_collectiones	Any type for which the `AsComponents<T>` trait is implemented. This is the case for any archetype or `std::vector`/`std::array`/C-array of components implements.

See also: log, try_log_timeless, try_log_with_timeless

◆ try_log()

template<typename... Ts>

Error rerun::RecordingStream::try_log	(	std::string_view	entity_path,
		const Ts &...	archetypes_or_collectiones
	)		const

inline

Logs one or more archetype and/or component batches.

See log for more information. Unlike log this method returns an error if an error occurs during serialization or logging.

Parameters

entity_path	Path to the entity in the space hierarchy.
archetypes_or_collectiones	Any type for which the `AsComponents<T>` trait is implemented. This is the case for any archetype or `std::vector`/`std::array`/C-array of components implements.

See also: log, try_log_timeless, try_log_with_timeless

◆ try_log_timeless()

template<typename... Ts>

Error rerun::RecordingStream::try_log_timeless	(	std::string_view	entity_path,
		const Ts &...	archetypes_or_collectiones
	)		const

inline

Logs one or more archetype and/or component batches as timeless data, returning an error.

See log/log_timeless for more information. Unlike log_timeless this method returns if an error occurs during serialization or logging.

Parameters

entity_path	Path to the entity in the space hierarchy.
archetypes_or_collectiones	Any type for which the `AsComponents<T>` trait is implemented. This is the case for any archetype or `std::vector`/`std::array`/C-array of components implements.

Returns: An error if an error occurs during serialization or logging.

See also: log_timeless, try_log, try_log_with_timeless

◆ log_with_timeless()

template<typename... Ts>

void rerun::RecordingStream::log_with_timeless	(	std::string_view	entity_path,
		bool	timeless,
		const Ts &...	archetypes_or_collectiones
	)		const

inline

Logs one or more archetype and/or component batches optionally timeless, returning an error.

See log/log_timeless for more information. Returns an error if an error occurs during serialization or logging.

Parameters

entity_path	Path to the entity in the space hierarchy.
timeless	If true, the logged components will be timeless. Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`. Additional timelines set by `set_time_sequence` or `set_time` will also be included.
archetypes_or_collectiones	Any type for which the `AsComponents<T>` trait is implemented. This is the case for any archetype or `std::vector`/`std::array`/C-array of components implements.

See also: log, try_log, log_timeless, try_log_timeless

◆ try_log_with_timeless()

template<typename... Ts>

Error rerun::RecordingStream::try_log_with_timeless	(	std::string_view	entity_path,
		bool	timeless,
		const Ts &...	archetypes_or_collectiones
	)		const

inline

Logs one or more archetype and/or component batches optionally timeless, returning an error.

See log/log_timeless for more information. Returns an error if an error occurs during serialization or logging.

Parameters

entity_path	Path to the entity in the space hierarchy.
timeless	If true, the logged components will be timeless. Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`. Additional timelines set by `set_time_sequence` or `set_time` will also be included.
archetypes_or_collectiones	Any type for which the `AsComponents<T>` trait is implemented. This is the case for any archetype or `std::vector`/`std::array`/C-array of components implements.

Returns: An error if an error occurs during serialization or logging.

See also: log, try_log, log_timeless, try_log_timeless

◆ try_log_serialized_batches()

Error rerun::RecordingStream::try_log_serialized_batches	(	std::string_view	entity_path,
		bool	timeless,
		std::vector< DataCell >	batches
	)		const

Logs several serialized batches batches, returning an error on failure.

This is a more low-level API than log/`log_timeless\ and requires you to already serialize the data ahead of time.

Parameters

entity_path	Path to the entity in the space hierarchy.
timeless	If true, the logged components will be timeless. Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`. Additional timelines set by `set_time_sequence` or `set_time` will also be included.
batches	The serialized batches to log.

See also: log, try_log, log_timeless, try_log_timeless, try_log_with_timeless

◆ try_log_data_row()

Error rerun::RecordingStream::try_log_data_row	(	std::string_view	entity_path,
		size_t	num_instances,
		size_t	num_data_cells,
		const DataCell *	data_cells,
		bool	inject_time
	)		const

Bottom level API that logs raw data cells to the recording stream.

In order to use this you need to pass serialized Arrow data cells.

Parameters

entity_path	Path to the entity in the space hierarchy.
num_instances	Each cell is expected to hold exactly `num_instances` instances.
num_data_cells	Number of data cells passed in.
data_cells	The data cells to log.
inject_time	If set to `true`, the row's timestamp data will be overridden using the recording streams internal clock.

See also: try_log_serialized_batches

◆ log_file_from_path()

void rerun::RecordingStream::log_file_from_path	(	const std::filesystem::path &	filepath,
		std::string_view	entity_path_prefix = `std::string_view()`,
		bool	timeless = `false`
	)		const

inline

Logs the file at the given path using all DataLoaders available.

A single path might be handled by more than one loader.

This method blocks until either at least one DataLoader starts streaming data in or all of them fail.

See https://www.rerun.io/docs/reference/data-loaders/overview for more information.

Parameters

filepath	Path to the file to be logged.
entity_path_prefix	What should the logged entity paths be prefixed with?
timeless	Should the logged data be timeless?

See also: try_log_file_from_path

◆ try_log_file_from_path()

Error rerun::RecordingStream::try_log_file_from_path	(	const std::filesystem::path &	filepath,
		std::string_view	entity_path_prefix = `std::string_view()`,
		bool	timeless = `false`
	)		const

Logs the file at the given path using all DataLoaders available.

A single path might be handled by more than one loader.

This method blocks until either at least one DataLoader starts streaming data in or all of them fail.

See https://www.rerun.io/docs/reference/data-loaders/overview for more information.

Parameters

filepath	Path to the file to be logged.
entity_path_prefix	What should the logged entity paths be prefixed with?
timeless	Should the logged data be timeless?

See also: log_file_from_path

◆ log_file_from_contents()

void rerun::RecordingStream::log_file_from_contents	(	const std::filesystem::path &	filepath,
		const std::byte *	contents,
		size_t	contents_size,
		std::string_view	entity_path_prefix = `std::string_view()`,
		bool	timeless = `false`
	)		const

inline

Logs the given contents using all DataLoaders available.

A single path might be handled by more than one loader.

This method blocks until either at least one DataLoader starts streaming data in or all of them fail.

See https://www.rerun.io/docs/reference/data-loaders/overview for more information.

Parameters

filepath	Path to the file that the `contents` belong to.
contents	Contents to be logged.
contents_size	Size in bytes of the `contents`.
entity_path_prefix	What should the logged entity paths be prefixed with?
timeless	Should the logged data be timeless?

See also: try_log_file_from_contents

◆ try_log_file_from_contents()

Error rerun::RecordingStream::try_log_file_from_contents	(	const std::filesystem::path &	filepath,
		const std::byte *	contents,
		size_t	contents_size,
		std::string_view	entity_path_prefix = `std::string_view()`,
		bool	timeless = `false`
	)		const

Logs the given contents using all DataLoaders available.

A single path might be handled by more than one loader.

This method blocks until either at least one DataLoader starts streaming data in or all of them fail.

See https://www.rerun.io/docs/reference/data-loaders/overview for more information.

Parameters

filepath	Path to the file that the `contents` belong to.
contents	Contents to be logged.
contents_size	Size in bytes of the `contents`.
entity_path_prefix	What should the logged entity paths be prefixed with?
timeless	Should the logged data be timeless?

See also: log_file_from_contents

The documentation for this class was generated from the following file:

rerun/recording_stream.hpp

Public Member Functions

Controlling globally available instances of RecordingStream.

Detailed Description

Multithreading and ordering

Shutdown

Logging

Constructor & Destructor Documentation

◆ RecordingStream()

Member Function Documentation

◆ is_enabled()

◆ set_global()

◆ set_thread_local()

◆ current()

◆ connect()

◆ spawn() [1/2]

Parameters

◆ spawn() [2/2]

◆ save()

◆ to_stdout()

◆ flush_blocking()

◆ set_time_sequence()

◆ set_time() [1/2]

◆ set_time() [2/2]

◆ set_time_seconds()

◆ set_time_nanos()

◆ disable_timeline()

◆ reset_time()

◆ log()

◆ log_timeless()

◆ try_log()

◆ try_log_timeless()

◆ log_with_timeless()

◆ try_log_with_timeless()

◆ try_log_serialized_batches()

◆ try_log_data_row()

◆ log_file_from_path()

◆ try_log_file_from_path()

◆ log_file_from_contents()

◆ try_log_file_from_contents()