Rerun C++ SDK
Loading...
Searching...
No Matches
recording_stream.hpp
1#pragma once
2
3#include <chrono>
4#include <cstdint> // uint32_t etc.
5#include <filesystem>
6#include <optional>
7#include <string_view>
8#include <type_traits>
9#include <vector>
10
11#include "as_components.hpp"
12#include "component_column.hpp"
13#include "error.hpp"
14#include "log_sink.hpp"
15#include "spawn_options.hpp"
16#include "time_column.hpp"
17
18namespace rerun {
19 struct ComponentBatch;
20
21 enum class StoreKind {
22 Recording,
23 Blueprint,
24 };
25
26 /// A `RecordingStream` handles everything related to logging data into Rerun.
27 ///
28 /// ## Multithreading and ordering
29 ///
30 /// A `RecordingStream` is thread-safe.
31 ///
32 /// Internally, all operations are linearized into a pipeline:
33 /// - All operations sent by a given thread will take effect in the same exact order as that
34 /// thread originally sent them in, from its point of view.
35 /// - There isn't any well defined global order across multiple threads.
36 ///
37 /// This means that e.g. flushing the pipeline (`flush_blocking`) guarantees that all
38 /// previous data sent by the calling thread has been recorded; no more, no less.
39 /// (e.g. it does not mean that all file caches are flushed)
40 ///
41 /// ## Shutdown
42 ///
43 /// The `RecordingStream` can only be shutdown by dropping all instances of it, at which point
44 /// it will automatically take care of flushing any pending data that might remain in the
45 /// pipeline.
46 ///
47 /// TODO(andreas): The only way of having two instances of a `RecordingStream` is currently to
48 /// set it as a the global.
49 ///
50 /// Shutting down cannot ever block.
51 ///
52 /// ## Logging
53 ///
54 /// Internally, the stream will automatically micro-batch multiple log calls to optimize
55 /// transport.
56 /// See [SDK Micro Batching](https://www.rerun.io/docs/reference/sdk/micro-batching) for
57 /// more information.
58 ///
59 /// The data will be timestamped automatically based on the `RecordingStream`'s
60 /// internal clock.
62 private:
63 // TODO(grtlr): Ideally we'd expose more of the `EntityPath` struct to the C++ world so
64 // that we don't have to hardcode this here.
65 static constexpr const char PROPERTIES_ENTITY_PATH[] = "__properties/";
66
67 public:
68 /// Creates a new recording stream to log to.
69 ///
70 /// \param app_id The user-chosen name of the application doing the logging.
71 /// \param recording_id The user-chosen name of the recording being logged to.
72 /// \param store_kind Whether to log to the recording store or the blueprint store.
74 std::string_view app_id, std::string_view recording_id = std::string_view(),
75 StoreKind store_kind = StoreKind::Recording
76 );
78
79 /// \private
81
82 // TODO(andreas): We could easily make the recording stream trivial to copy by bumping Rusts
83 // ref counter by adding a copy of the recording stream to the list of C recording streams.
84 // Doing it this way would likely yield the most consistent behavior when interacting with
85 // global streams (and especially when interacting with different languages in the same
86 // application).
87 /// \private
88 RecordingStream(const RecordingStream&) = delete;
89 /// \private
90 RecordingStream() = delete;
91
92 // -----------------------------------------------------------------------------------------
93 /// \name Properties
94 /// @{
95
96 /// Returns the store kind as passed during construction
97 StoreKind kind() const {
98 return _store_kind;
99 }
100
101 /// Returns whether the recording stream is enabled.
102 ///
103 /// All log functions early out if a recording stream is disabled.
104 /// Naturally, logging functions that take unserialized data will skip the serialization step as well.
105 bool is_enabled() const {
106 return _enabled;
107 }
108
109 /// @}
110
111 // -----------------------------------------------------------------------------------------
112 /// \name Controlling globally available instances of RecordingStream.
113 /// @{
114
115 /// Replaces the currently active recording for this stream's store kind in the global scope
116 /// with this one.
117 ///
118 /// Afterwards, destroying this recording stream will *not* change the global recording
119 /// stream, as it increases an internal ref-count.
120 void set_global() const;
121
122 /// Replaces the currently active recording for this stream's store kind in the thread-local
123 /// scope with this one
124 ///
125 /// Afterwards, destroying this recording stream will *not* change the thread local
126 /// recording stream, as it increases an internal ref-count.
127 void set_thread_local() const;
128
129 /// Retrieves the most appropriate globally available recording stream for the given kind.
130 ///
131 /// I.e. thread-local first, then global.
132 /// If neither was set, any operations on the returned stream will be no-ops.
133 static RecordingStream& current(StoreKind store_kind = StoreKind::Recording);
134
135 /// @}
136
137 // -----------------------------------------------------------------------------------------
138 /// \name Directing the recording stream.
139 /// \details Either of these needs to be called, otherwise the stream will buffer up indefinitely.
140 /// @{
141
142 /// Stream data to multiple sinks.
143 ///
144 /// See specific sink types for more information:
145 /// * `FileSink`
146 /// * `GrpcSink`
147 template <typename... Ts>
148 Error set_sinks(const Ts&... sinks) const {
149 LogSink out_sinks[] = {sinks...};
150 uint32_t num_sinks = sizeof...(Ts);
151 return try_set_sinks(out_sinks, num_sinks);
152 }
153
154 /// Connect to a remote Rerun Viewer on the given URL.
155 ///
156 /// Requires that you first start a Rerun Viewer by typing 'rerun' in a terminal.
157 ///
158 /// \param url The scheme must be one of `rerun://`, `rerun+http://`, or `rerun+https://`,
159 /// and the pathname must be `/proxy`. The default is `rerun+http://127.0.0.1:9876/proxy`.
160 ///
161 /// \param flush_timeout_sec The minimum time the SDK will wait during a flush before potentially
162 /// dropping data if progress is not being made. Passing a negative value indicates no
163 /// timeout, and can cause a call to `flush` to block indefinitely.
164 ///
165 /// This function returns immediately.
167 std::string_view url = "rerun+http://127.0.0.1:9876/proxy",
168 float flush_timeout_sec = 2.0
169 ) const;
170
171 /// Swaps the underlying sink for a gRPC server sink pre-configured to listen on `rerun+http://{bind_ip}:{port}/proxy`.
172 ///
173 /// The gRPC server will buffer all log data in memory so that late connecting viewers will get all the data.
174 /// You can limit the amount of data buffered by the gRPC server with the `server_memory_limit` argument.
175 /// Once reached, the earliest logged data will be dropped. Static data is never dropped.
176 ///
177 /// It is highly recommended that you set the memory limit to `0B` if both the server and client are running
178 /// on the same machine, otherwise you're potentially doubling your memory usage!
179 ///
180 /// Returns the URI of the gRPC server so you can connect to it from a viewer.
181 ///
182 /// This function returns immediately.
184 std::string_view bind_ip = "0.0.0.0", uint16_t port = 9876,
185 std::string_view server_memory_limit = "25%"
186 ) const;
187
188 /// Spawns a new Rerun Viewer process from an executable available in PATH, then connects to it
189 /// over gRPC.
190 ///
191 /// If a Rerun Viewer is already listening on this port, the stream will be redirected to
192 /// that viewer instead of starting a new one.
193 ///
194 /// \param flush_timeout_sec The minimum time the SDK will wait during a flush before potentially
195 /// dropping data if progress is not being made. Passing a negative value indicates no
196 /// timeout, and can cause a call to `flush` to block indefinitely.
197 ///
198 /// \param options See `rerun::SpawnOptions` for more information.
199 Error spawn(const SpawnOptions& options = {}, float flush_timeout_sec = 2.0) const;
200
201 /// @see RecordingStream::spawn
202 template <typename TRep, typename TPeriod>
204 const SpawnOptions& options = {},
205 std::chrono::duration<TRep, TPeriod> flush_timeout = std::chrono::seconds(2)
206 ) const {
207 using seconds_float = std::chrono::duration<float>; // Default ratio is 1:1 == seconds.
208 return spawn(options, std::chrono::duration_cast<seconds_float>(flush_timeout).count());
209 }
210
211 /// Stream all log-data to a given `.rrd` file.
212 ///
213 /// The Rerun Viewer is able to read continuously from the resulting rrd file while it is being written.
214 /// However, depending on your OS and configuration, changes may not be immediately visible due to file caching.
215 /// This is a common issue on Windows and (to a lesser extent) on MacOS.
216 ///
217 /// This function returns immediately.
218 Error save(std::string_view path) const;
219
220 /// Stream all log-data to standard output.
221 ///
222 /// Pipe the result into the Rerun Viewer to visualize it.
223 ///
224 /// If there isn't any listener at the other end of the pipe, the `RecordingStream` will
225 /// default back to `buffered` mode, in order not to break the user's terminal.
226 ///
227 /// This function returns immediately.
228 //
229 // NOTE: This should be called `stdout` like in other SDK, but turns out that `stdout` is a
230 // macro when compiling with msvc [1].
231 // [1]: https://learn.microsoft.com/en-us/cpp/c-runtime-library/stdin-stdout-stderr?view=msvc-170
233
234 /// Initiates a flush the batching pipeline and waits for it to propagate.
235 ///
236 /// See `RecordingStream` docs for ordering semantics and multithreading guarantees.
237 void flush_blocking() const;
238
239 /// @}
240
241 // -----------------------------------------------------------------------------------------
242 /// \name Controlling log time (index).
243 /// \details
244 /// @{
245
246 /// Set the index value of the given timeline as a sequence number, for the current calling thread.
247 ///
248 /// Used for all subsequent logging performed from this same thread, until the next call
249 /// to one of the time setting methods.
250 ///
251 /// For example: `rec.set_time_sequence("frame_nr", frame_nr)`.
252 ///
253 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
254 /// @see set_time_sequence, set_time_duration, set_time_duration_secs, set_time_duration_nanos, set_time_timestamp, set_time_timestamp_secs_since_epoch, set_time_timestamp_nanos_since_epoch
255 void set_time_sequence(std::string_view timeline_name, int64_t sequence_nr) const;
256
257 /// Set the index value of the given timeline as a duration, for the current calling thread.
258 ///
259 /// Used for all subsequent logging performed from this same thread, until the next call
260 /// to one of the time setting methods.
261 ///
262 /// For example: `rec.set_time_duration("runtime", time_since_start)`.
263 ///
264 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
265 /// @see set_time_sequence, set_time_duration, set_time_duration_secs, set_time_duration_nanos, set_time_timestamp, set_time_timestamp_secs_since_epoch, set_time_timestamp_nanos_since_epoch
266 template <typename TRep, typename TPeriod>
268 std::string_view timeline_name, std::chrono::duration<TRep, TPeriod> duration
269 ) const {
270 auto nanos = std::chrono::duration_cast<std::chrono::nanoseconds>(duration).count();
271 set_time_duration_nanos(timeline_name, nanos);
272 }
273
274 /// Set the index value of the given timeline as a duration in seconds, for the current calling thread.
275 ///
276 /// Used for all subsequent logging performed from this same thread, until the next call
277 /// to one of the time setting methods.
278 ///
279 /// For example: `rec.set_time_duration_secs("runtime", seconds_since_start)`.
280 ///
281 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
282 /// @see set_time_sequence, set_time_duration, set_time_duration_secs, set_time_duration_nanos, set_time_timestamp, set_time_timestamp_secs_since_epoch, set_time_timestamp_nanos_since_epoch
283 void set_time_duration_secs(std::string_view timeline_name, double secs) const {
284 set_time_duration_nanos(timeline_name, static_cast<int64_t>(1e9 * secs + 0.5));
285 }
286
287 /// Set the index value of the given timeline as a duration in nanoseconds, for the current calling thread.
288 ///
289 /// Used for all subsequent logging performed from this same thread, until the next call
290 /// to one of the time setting methods.
291 ///
292 /// For example: `rec.set_time_duration_nanos("runtime", nanos_since_start)`.
293 ///
294 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
295 /// @see set_time_sequence, set_time_duration, set_time_duration_secs, set_time_duration_nanos, set_time_timestamp, set_time_timestamp_secs_since_epoch, set_time_timestamp_nanos_since_epoch
296 void set_time_duration_nanos(std::string_view timeline_name, int64_t nanos) const;
297
298 /// Set the index value of the given timeline as a timestamp, for the current calling thread.
299 ///
300 /// Used for all subsequent logging performed from this same thread, until the next call
301 /// to one of the time setting methods.
302 ///
303 /// For example: `rec.set_time_timestamp("capture_time", now())`.
304 ///
305 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
306 /// @see set_time_sequence, set_time_duration, set_time_duration_secs, set_time_duration_nanos, set_time_timestamp, set_time_timestamp_secs_since_epoch, set_time_timestamp_nanos_since_epoch
307 template <typename TClock>
309 std::string_view timeline_name, std::chrono::time_point<TClock> timestamp
310 ) const {
312 timeline_name,
313 std::chrono::duration_cast<std::chrono::nanoseconds>(timestamp.time_since_epoch())
314 .count()
315 );
316 }
317
318 /// Set the index value of the given timeline as seconds since Unix Epoch (1970), for the current calling thread.
319 ///
320 /// Used for all subsequent logging performed from this same thread, until the next call
321 /// to one of the time setting methods.
322 ///
323 /// For example: `rec.set_time_timestamp_secs_since_epoch("capture_time", secs_since_epoch())`.
324 ///
325 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
326 /// @see set_time_sequence, set_time_duration, set_time_duration_secs, set_time_duration_nanos, set_time_timestamp, set_time_timestamp_secs_since_epoch, set_time_timestamp_nanos_since_epoch
327 void set_time_timestamp_secs_since_epoch(std::string_view timeline_name, double seconds)
328 const {
330 timeline_name,
331 static_cast<int64_t>(1e9 * seconds)
332 );
333 }
334
335 /// Set the index value of the given timeline as nanoseconds since Unix Epoch (1970), for the current calling thread.
336 ///
337 /// Used for all subsequent logging performed from this same thread, until the next call
338 /// to one of the time setting methods.
339 ///
340 /// For example: `rec.set_time_timestamp_nanos_since_epoch("capture_time", nanos_since_epoch())`.
341 ///
342 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
343 /// @see set_time_sequence, set_time_duration, set_time_duration_secs, set_time_duration_nanos, set_time_timestamp, set_time_timestamp_secs_since_epoch, set_time_timestamp_nanos_since_epoch
344 void set_time_timestamp_nanos_since_epoch(std::string_view timeline_name, int64_t nanos)
345 const;
346
347 /// Set the current time of the recording, for the current calling thread.
348 ///
349 /// Used for all subsequent logging performed from this same thread, until the next call
350 /// to one of the time setting methods.
351 ///
352 /// For example: `rec.set_time("sim_time", sim_time_secs)`.
353 ///
354 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
355 /// @see set_time_sequence, set_time_seconds, set_time_nanos, reset_time, disable_timeline
356 template <typename TClock>
357 [[deprecated("Renamed to `set_time_timestamp`")]] void set_time(
358 std::string_view timeline_name, std::chrono::time_point<TClock> time
359 ) const {
360 set_time(timeline_name, time.time_since_epoch());
361 }
362
363 /// Set the current time of the recording, for the current calling thread.
364 ///
365 /// Used for all subsequent logging performed from this same thread, until the next call
366 /// to one of the time setting methods.
367 ///
368 /// For example: `rec.set_time("sim_time", sim_time_secs)`.
369 ///
370 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
371 /// @see set_time_sequence, set_time_seconds, set_time_nanos, reset_time, disable_timeline
372 template <typename TRep, typename TPeriod>
373 [[deprecated("Renamed `set_time_duration`")]] void set_time(
374 std::string_view timeline_name, std::chrono::duration<TRep, TPeriod> time
375 ) const {
376 set_time_duration(timeline_name, time);
377 }
378
379 /// Set the current time of the recording, for the current calling thread.
380 ///
381 /// Used for all subsequent logging performed from this same thread, until the next call
382 /// to one of the time setting methods.
383 ///
384 /// For example: `rec.set_time_seconds("sim_time", sim_time_secs)`.
385 ///
386 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
387 /// @see set_time_sequence, set_time_nanos, reset_time, set_time, disable_timeline
388 [[deprecated("Use either `set_time_duration_secs` or `set_time_timestamp_secs_since_epoch`"
389 )]] void
390 set_time_seconds(std::string_view timeline_name, double seconds) const {
391 set_time_duration_secs(timeline_name, seconds);
392 }
393
394 /// Set the current time of the recording, for the current calling thread.
395 ///
396 /// Used for all subsequent logging performed from this same thread, until the next call
397 /// to one of the time setting methods.
398 ///
399 /// For example: `rec.set_time_nanos("sim_time", sim_time_nanos)`.
400 ///
401 /// You can remove a timeline from subsequent log calls again using `rec.disable_timeline`.
402 /// @see set_time_sequence, set_time_seconds, reset_time, set_time, disable_timeline
403 [[deprecated(
404 "Use either `set_time_duration_nanos` or `set_time_timestamp_nanos_since_epoch`"
405 )]] void
406 set_time_nanos(std::string_view timeline_name, int64_t nanos) const {
407 set_time_duration_nanos(timeline_name, nanos);
408 }
409
410 /// Stops logging to the specified timeline for subsequent log calls.
411 ///
412 /// The timeline is still there, but will not be updated with any new data.
413 ///
414 /// No-op if the timeline doesn't exist.
415 ///
416 /// @see set_time_sequence, set_time_seconds, set_time, reset_time
417 void disable_timeline(std::string_view timeline_name) const;
418
419 /// Clears out the current time of the recording, for the current calling thread.
420 ///
421 /// Used for all subsequent logging performed from this same thread, until the next call
422 /// to one of the time setting methods.
423 ///
424 /// For example: `rec.reset_time()`.
425 /// @see set_time_sequence, set_time_seconds, set_time_nanos, disable_timeline
426 void reset_time() const;
427
428 /// @}
429
430 // -----------------------------------------------------------------------------------------
431 /// \name Sending & logging data.
432 /// @{
433
434 /// Logs one or more archetype and/or component batches.
435 ///
436 /// This is the main entry point for logging data to rerun. It can be used to log anything
437 /// that implements the `AsComponents<T>` trait.
438 ///
439 /// When logging data, you must always provide an [entity_path](https://www.rerun.io/docs/concepts/entity-path)
440 /// for identifying the data. Note that paths prefixed with "__" are considered reserved for use by the Rerun SDK
441 /// itself and should not be used for logging user data. This is where Rerun will log additional information
442 /// such as properties and warnings.
443 ///
444 /// The most common way to log is with one of the rerun archetypes, all of which implement the `AsComponents` trait.
445 ///
446 /// For example, to log two 3D points:
447 /// ```
448 /// rec.log("my/point", rerun::Points3D({{0.0f, 0.0f, 0.0f}, {1.0f, 1.0f, 1.0f}}));
449 /// ```
450 ///
451 /// The `log` function can flexibly accept an arbitrary number of additional objects which will
452 /// be merged into the first entity, for instance:
453 /// ```
454 /// // Log three points with arrows sticking out of them:
455 /// rec.log(
456 /// "my/points",
457 /// rerun::Points3D({{0.2f, 0.5f, 0.3f}, {0.9f, 1.2f, 0.1f}, {1.0f, 4.2f, 0.3f}})
458 /// .with_radii({0.1, 0.2, 0.3}),
459 /// rerun::Arrows3D::from_vectors({{0.3f, 2.1f, 0.2f}, {0.9f, -1.1, 2.3f}, {-0.4f, 0.5f, 2.9f}})
460 /// );
461 /// ```
462 ///
463 /// Any failures that may are handled with `Error::handle`.
464 ///
465 /// \param entity_path Path to the entity in the space hierarchy.
466 /// \param as_components Any type for which the `AsComponents<T>` trait is implemented.
467 /// This is the case for any archetype as well as individual or collection of `ComponentBatch`.
468 /// You can implement `AsComponents` for your own types as well
469 ///
470 /// @see try_log, log_static, try_log_with_static
471 template <typename... Ts>
472 void log(std::string_view entity_path, const Ts&... as_components) const {
473 if (!is_enabled()) {
474 return;
475 }
476 try_log_with_static(entity_path, false, as_components...).handle();
477 }
478
479 /// Logs one or more archetype and/or component batches as static data.
480 ///
481 /// Like `log` but logs the data as static:
482 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
483 /// any temporal data of the same type.
484 ///
485 /// Failures are handled with `Error::handle`.
486 ///
487 /// \param entity_path Path to the entity in the space hierarchy.
488 /// \param as_components Any type for which the `AsComponents<T>` trait is implemented.
489 /// This is the case for any archetype as well as individual or collection of `ComponentBatch`.
490 /// You can implement `AsComponents` for your own types as well
491 ///
492 /// @see log, try_log_static, try_log_with_static
493 template <typename... Ts>
494 void log_static(std::string_view entity_path, const Ts&... as_components) const {
495 if (!is_enabled()) {
496 return;
497 }
498 try_log_with_static(entity_path, true, as_components...).handle();
499 }
500
501 /// Logs one or more archetype and/or component batches.
502 ///
503 /// See `log` for more information.
504 /// Unlike `log` this method returns an error if an error occurs.
505 ///
506 /// \param entity_path Path to the entity in the space hierarchy.
507 /// \param as_components Any type for which the `AsComponents<T>` trait is implemented.
508 /// This is the case for any archetype as well as individual or collection of `ComponentBatch`.
509 /// You can implement `AsComponents` for your own types as well
510 ///
511 /// @see log, try_log_static, try_log_with_static
512 template <typename... Ts>
513 Error try_log(std::string_view entity_path, const Ts&... as_components) const {
514 if (!is_enabled()) {
515 return Error::ok();
516 }
517 return try_log_with_static(entity_path, false, as_components...);
518 }
519
520 /// Logs one or more archetype and/or component batches as static data, returning an error.
521 ///
522 /// See `log`/`log_static` for more information.
523 /// Unlike `log_static` this method returns if an error occurs.
524 ///
525 /// \param entity_path Path to the entity in the space hierarchy.
526 /// \param as_components Any type for which the `AsComponents<T>` trait is implemented.
527 /// This is the case for any archetype as well as individual or collection of `ComponentBatch`.
528 /// You can implement `AsComponents` for your own types as well
529 /// \returns An error if an error occurs during evaluation of `AsComponents` or logging.
530 ///
531 /// @see log_static, try_log, try_log_with_static
532 template <typename... Ts>
533 Error try_log_static(std::string_view entity_path, const Ts&... as_components) const {
534 if (!is_enabled()) {
535 return Error::ok();
536 }
537 return try_log_with_static(entity_path, true, as_components...);
538 }
539
540 /// Logs one or more archetype and/or component batches optionally static, returning an error.
541 ///
542 /// See `log`/`log_static` for more information.
543 /// Returns an error if an error occurs during evaluation of `AsComponents` or logging.
544 ///
545 /// \param entity_path Path to the entity in the space hierarchy.
546 /// \param static_ If true, the logged components will be static.
547 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
548 /// any temporal data of the same type.
549 /// Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`.
550 /// Additional timelines set by `set_time_sequence` or `set_time` will also be included.
551 /// \param as_components Any type for which the `AsComponents<T>` trait is implemented.
552 /// This is the case for any archetype as well as individual or collection of `ComponentBatch`.
553 /// You can implement `AsComponents` for your own types as well
554 ///
555 /// @see log, try_log, log_static, try_log_static
556 template <typename... Ts>
557 void log_with_static(std::string_view entity_path, bool static_, const Ts&... as_components)
558 const {
559 try_log_with_static(entity_path, static_, as_components...).handle();
560 }
561
562 /// Logs one or more archetype and/or component batches optionally static, returning an error.
563 ///
564 /// See `log`/`log_static` for more information.
565 /// Returns an error if an error occurs during evaluation of `AsComponents` or logging.
566 ///
567 /// \param entity_path Path to the entity in the space hierarchy.
568 /// \param static_ If true, the logged components will be static.
569 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
570 /// any temporal data of the same type.
571 /// Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`.
572 /// Additional timelines set by `set_time_sequence` or `set_time` will also be included.
573 /// \param as_components Any type for which the `AsComponents<T>` trait is implemented.
574 /// This is the case for any archetype as well as individual or collection of `ComponentBatch`.
575 /// You can implement `AsComponents` for your own types as well
576 /// \returns An error if an error occurs during evaluation of `AsComponents` or logging.
577 ///
578 /// @see log, try_log, log_static, try_log_static
579 template <typename... Ts>
581 std::string_view entity_path, bool static_, const Ts&... as_components
582 ) const {
583 if (!is_enabled()) {
584 return Error::ok();
585 }
586 std::vector<ComponentBatch> serialized_columns;
587 Error err;
588 (
589 [&] {
590 if (err.is_err()) {
591 return;
592 }
593
594 const Result<Collection<ComponentBatch>> serialization_result =
595 AsComponents<Ts>().as_batches(as_components);
596 if (serialization_result.is_err()) {
597 err = serialization_result.error;
598 return;
599 }
600
601 if (serialized_columns.empty()) {
602 // Fast path for the first batch (which is usually the only one!)
603 serialized_columns = std::move(serialization_result.value).to_vector();
604 } else {
605 serialized_columns.insert(
606 serialized_columns.end(),
607 std::make_move_iterator(serialization_result.value.begin()),
608 std::make_move_iterator(serialization_result.value.end())
609 );
610 }
611 }(),
612 ...
613 );
614 RR_RETURN_NOT_OK(err);
615
616 return try_log_serialized_batches(entity_path, static_, std::move(serialized_columns));
617 }
618
619 /// Logs several serialized batches batches, returning an error on failure.
620 ///
621 /// This is a more low-level API than `log`/`log_static\ and requires you to already serialize the data
622 /// ahead of time.
623 ///
624 /// \param entity_path Path to the entity in the space hierarchy.
625 /// \param static_ If true, the logged components will be static.
626 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
627 /// any temporal data of the same type.
628 /// Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`.
629 /// Additional timelines set by `set_time_sequence` or `set_time` will also be included.
630 /// \param batches The serialized batches to log.
631 ///
632 /// \see `log`, `try_log`, `log_static`, `try_log_static`, `try_log_with_static`
634 std::string_view entity_path, bool static_, std::vector<ComponentBatch> batches
635 ) const;
636
637 /// Bottom level API that logs raw data cells to the recording stream.
638 ///
639 /// In order to use this you need to pass serialized Arrow data cells.
640 ///
641 /// \param entity_path Path to the entity in the space hierarchy.
642 /// \param num_data_cells Number of data cells passed in.
643 /// \param data_cells The data cells to log.
644 /// \param inject_time
645 /// If set to `true`, the row's timestamp data will be overridden using the recording
646 /// streams internal clock.
647 ///
648 /// \see `try_log_serialized_batches`
650 std::string_view entity_path, size_t num_data_cells, const ComponentBatch* data_cells,
651 bool inject_time
652 ) const;
653
654 /// Logs the file at the given `path` using all `DataLoader`s available.
655 ///
656 /// A single `path` might be handled by more than one loader.
657 ///
658 /// This method blocks until either at least one `DataLoader` starts streaming data in
659 /// or all of them fail.
660 ///
661 /// See <https://www.rerun.io/docs/reference/data-loaders/overview> for more information.
662 ///
663 /// \param filepath Path to the file to be logged.
664 /// \param entity_path_prefix What should the logged entity paths be prefixed with?
665 /// \param static_ If true, the logged components will be static.
666 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
667 /// any temporal data of the same type.
668 /// Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`.
669 /// Additional timelines set by `set_time_sequence` or `set_time` will also be included.
670 ///
671 /// \see `try_log_file_from_path`
673 const std::filesystem::path& filepath,
674 std::string_view entity_path_prefix = std::string_view(), bool static_ = false
675 ) const {
676 try_log_file_from_path(filepath, entity_path_prefix, static_).handle();
677 }
678
679 /// Logs the file at the given `path` using all `DataLoader`s available.
680 ///
681 /// A single `path` might be handled by more than one loader.
682 ///
683 /// This method blocks until either at least one `DataLoader` starts streaming data in
684 /// or all of them fail.
685 ///
686 /// See <https://www.rerun.io/docs/reference/data-loaders/overview> for more information.
687 ///
688 /// \param filepath Path to the file to be logged.
689 /// \param entity_path_prefix What should the logged entity paths be prefixed with?
690 /// \param static_ If true, the logged components will be static.
691 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
692 /// any temporal data of the same type.
693 /// Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`.
694 /// Additional timelines set by `set_time_sequence` or `set_time` will also be included.
695 ///
696 /// \see `log_file_from_path`
698 const std::filesystem::path& filepath,
699 std::string_view entity_path_prefix = std::string_view(), bool static_ = false
700 ) const;
701
702 /// Logs the given `contents` using all `DataLoader`s available.
703 ///
704 /// A single `path` might be handled by more than one loader.
705 ///
706 /// This method blocks until either at least one `DataLoader` starts streaming data in
707 /// or all of them fail.
708 ///
709 /// See <https://www.rerun.io/docs/reference/data-loaders/overview> for more information.
710 ///
711 /// \param filepath Path to the file that the `contents` belong to.
712 /// \param contents Contents to be logged.
713 /// \param contents_size Size in bytes of the `contents`.
714 /// \param entity_path_prefix What should the logged entity paths be prefixed with?
715 /// \param static_ If true, the logged components will be static.
716 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
717 /// any temporal data of the same type.
718 /// Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`.
719 /// Additional timelines set by `set_time_sequence` or `set_time` will also be included.
720 ///
721 /// \see `try_log_file_from_contents`
723 const std::filesystem::path& filepath, const std::byte* contents, size_t contents_size,
724 std::string_view entity_path_prefix = std::string_view(), bool static_ = false
725 ) const {
727 filepath,
728 contents,
729 contents_size,
730 entity_path_prefix,
731 static_
732 )
733 .handle();
734 }
735
736 /// Logs the given `contents` using all `DataLoader`s available.
737 ///
738 /// A single `path` might be handled by more than one loader.
739 ///
740 /// This method blocks until either at least one `DataLoader` starts streaming data in
741 /// or all of them fail.
742 ///
743 /// See <https://www.rerun.io/docs/reference/data-loaders/overview> for more information.
744 ///
745 /// \param filepath Path to the file that the `contents` belong to.
746 /// \param contents Contents to be logged.
747 /// \param contents_size Size in bytes of the `contents`.
748 /// \param entity_path_prefix What should the logged entity paths be prefixed with?
749 /// \param static_ If true, the logged components will be static.
750 /// Static data has no time associated with it, exists on all timelines, and unconditionally shadows
751 /// any temporal data of the same type.
752 /// Otherwise, the data will be timestamped automatically with `log_time` and `log_tick`.
753 /// Additional timelines set by `set_time_sequence` or `set_time` will also be included.
754 ///
755 /// \see `log_file_from_contents`
757 const std::filesystem::path& filepath, const std::byte* contents, size_t contents_size,
758 std::string_view entity_path_prefix = std::string_view(), bool static_ = false
759 ) const;
760
761 /// Directly log a columns of data to Rerun.
762 ///
763 /// This variant takes in arbitrary amount of `ComponentColumn`s and `ComponentColumn` collections.
764 ///
765 /// Unlike the regular `log` API, which is row-oriented, this API lets you submit the data
766 /// in a columnar form. Each `TimeColumn` and `ComponentColumn` represents a column of data that will be sent to Rerun.
767 /// The lengths of all of these columns must match, and all
768 /// data that shares the same index across the different columns will act as a single logical row,
769 /// equivalent to a single call to `RecordingStream::log`.
770 ///
771 /// Note that this API ignores any stateful time set on the log stream via the `RecordingStream::set_time_*` APIs.
772 /// Furthermore, this will _not_ inject the default timelines `log_tick` and `log_time` timeline columns.
773 ///
774 /// Any failures that may occur during serialization are handled with `Error::handle`.
775 ///
776 /// \param entity_path Path to the entity in the space hierarchy.
777 /// \param time_columns The time columns to send.
778 /// \param component_columns The columns of components to send. Both individual `ComponentColumn`s and `Collection<ComponentColumn>`s are accepted.
779 /// \see `try_send_columns`
780 template <typename... Ts>
782 std::string_view entity_path, Collection<TimeColumn> time_columns,
783 Ts... component_columns // NOLINT
784 ) const {
785 try_send_columns(entity_path, time_columns, component_columns...).handle();
786 }
787
788 /// Directly log a columns of data to Rerun.
789 ///
790 /// This variant takes in arbitrary amount of `ComponentColumn`s and `ComponentColumn` collections.
791 ///
792 /// Unlike the regular `log` API, which is row-oriented, this API lets you submit the data
793 /// in a columnar form. Each `TimeColumn` and `ComponentColumn` represents a column of data that will be sent to Rerun.
794 /// The lengths of all of these columns must match, and all
795 /// data that shares the same index across the different columns will act as a single logical row,
796 /// equivalent to a single call to `RecordingStream::log`.
797 ///
798 /// Note that this API ignores any stateful time set on the log stream via the `RecordingStream::set_time_*` APIs.
799 /// Furthermore, this will _not_ inject the default timelines `log_tick` and `log_time` timeline columns.
800 ///
801 /// \param entity_path Path to the entity in the space hierarchy.
802 /// \param time_columns The time columns to send.
803 /// \param component_columns The columns of components to send. Both individual `ComponentColumn`s and `Collection<ComponentColumn>`s are accepted.
804 /// \see `send_columns`
805 template <typename... Ts>
807 std::string_view entity_path, Collection<TimeColumn> time_columns,
808 Ts... component_columns // NOLINT
809 ) const {
810 if constexpr (sizeof...(Ts) == 1) {
811 // Directly forward if this is only a single element,
812 // skipping collection of component column vector.
813 return try_send_columns(
814 entity_path,
815 std::move(time_columns),
816 Collection(std::forward<Ts...>(component_columns...))
817 );
818 }
819
820 std::vector<ComponentColumn> flat_column_list;
821 (
822 [&] {
823 static_assert(
824 std::is_same_v<std::remove_cv_t<Ts>, ComponentColumn> ||
825 std::is_constructible_v<Collection<ComponentColumn>, Ts>,
826 "Ts must be ComponentColumn or a collection thereof"
827 );
828
829 push_back_columns(flat_column_list, std::move(component_columns));
830 }(),
831 ...
832 );
833 return try_send_columns(
834 entity_path,
835 std::move(time_columns),
836 // Need to create collection explicitly, otherwise this becomes a recursive call.
837 Collection<ComponentColumn>(std::move(flat_column_list))
838 );
839 }
840
841 /// Directly log a columns of data to Rerun.
842 ///
843 /// Unlike the regular `log` API, which is row-oriented, this API lets you submit the data
844 /// in a columnar form. Each `TimeColumn` and `ComponentColumn` represents a column of data that will be sent to Rerun.
845 /// The lengths of all of these columns must match, and all
846 /// data that shares the same index across the different columns will act as a single logical row,
847 /// equivalent to a single call to `RecordingStream::log`.
848 ///
849 /// Note that this API ignores any stateful time set on the log stream via the `RecordingStream::set_time_*` APIs.
850 /// Furthermore, this will _not_ inject the default timelines `log_tick` and `log_time` timeline columns.
851 ///
852 /// Any failures that may occur during serialization are handled with `Error::handle`.
853 ///
854 /// \param entity_path Path to the entity in the space hierarchy.
855 /// \param time_columns The time columns to send.
856 /// \param component_columns The columns of components to send.
857 /// \see `try_send_columns`
859 std::string_view entity_path, Collection<TimeColumn> time_columns,
860 Collection<ComponentColumn> component_columns
861 ) const {
862 try_send_columns(entity_path, time_columns, component_columns).handle();
863 }
864
865 /// Directly log a columns of data to Rerun.
866 ///
867 /// Unlike the regular `log` API, which is row-oriented, this API lets you submit the data
868 /// in a columnar form. Each `TimeColumn` and `ComponentColumn` represents a column of data that will be sent to Rerun.
869 /// The lengths of all of these columns must match, and all
870 /// data that shares the same index across the different columns will act as a single logical row,
871 /// equivalent to a single call to `RecordingStream::log`.
872 ///
873 /// Note that this API ignores any stateful time set on the log stream via the `RecordingStream::set_time_*` APIs.
874 /// Furthermore, this will _not_ inject the default timelines `log_tick` and `log_time` timeline columns.
875 ///
876 /// \param entity_path Path to the entity in the space hierarchy.
877 /// \param time_columns The time columns to send.
878 /// \param component_columns The columns of components to send.
879 /// \see `send_columns`
881 std::string_view entity_path, Collection<TimeColumn> time_columns,
882 Collection<ComponentColumn> component_columns
883 ) const;
884
885 /// Set a property of a recording.
886 ///
887 /// Any failures that may occur during serialization are handled with `Error::handle`.
888 ///
889 /// \param name The name of the property.
890 /// \param values The values of the property.
891 /// \see `try_send_property`
892 template <typename... Ts>
893 void send_property(std::string_view name, const Ts&... values) const {
894 try_send_property(name, values...).handle();
895 }
896
897 /// Set a property of a recording.
898 ///
899 /// Any failures that may occur during serialization are handled with `Error::handle`.
900 ///
901 /// \param name The name of the property.
902 /// \param values The values of the property.
903 /// \see `set_property`
904 template <typename... Ts>
905 Error try_send_property(std::string_view name, const Ts&... values) const {
906 return try_log_static(
907 this->PROPERTIES_ENTITY_PATH + std::string(name),
908 values... // NOLINT
909 );
910 }
911
912 /// Set the name of a recording.
913 ///
914 /// Any failures that may occur during serialization are handled with `Error::handle`.
915 ///
916 /// \param name The name of the recording.
917 /// \see `try_send_recording_name`
918 void send_recording_name(std::string_view name) const {
920 }
921
922 /// Set the name of a recording.
923 ///
924 /// \param name The name of the recording.
925 /// \see `send_recording_name`
926 Error try_send_recording_name(std::string_view name) const;
927
928 /// Set the start time of a recording.
929 ///
930 /// Any failures that may occur during serialization are handled with `Error::handle`.
931 ///
932 /// \param nanos The timestamp of the recording in nanoseconds since Unix epoch.
933 /// \see `try_send_recording_start_time`
934 void send_recording_start_time_nanos(int64_t nanos) const {
936 }
937
938 /// Set the start time of a recording.
939 ///
940 /// \param nanos The timestamp of the recording in nanoseconds since Unix epoch.
941 /// \see `set_name`
943
944 /// @}
945
946 private:
947 Error try_set_sinks(const LogSink* sinks, uint32_t num_sinks) const;
948
949 // Utility function to implement `try_send_columns` variadic template.
950 static void push_back_columns(
951 std::vector<ComponentColumn>& component_columns, Collection<ComponentColumn> new_columns
952 ) {
953 for (const auto& new_column : new_columns) {
954 component_columns.emplace_back(std::move(new_column));
955 }
956 }
957
958 static void push_back_columns(
959 std::vector<ComponentColumn>& component_columns, ComponentColumn new_column
960 ) {
961 component_columns.emplace_back(std::move(new_column));
962 }
963
964 RecordingStream(uint32_t id, StoreKind store_kind);
965
966 uint32_t _id;
967 StoreKind _store_kind;
968 bool _enabled;
969 };
970} // namespace rerun
Generic collection of elements that are roughly contiguous in memory.
Definition collection.hpp:49
Status outcome object (success or error) returned for fallible operations.
Definition error.hpp:99
void handle() const
Handle this error based on the set log handler.
bool is_err() const
Returns true if the code is not Ok.
Definition error.hpp:135
static Error ok()
Creates a new error set to ok.
Definition error.hpp:120
A RecordingStream handles everything related to logging data into Rerun.
Definition recording_stream.hpp:61
Error try_log_with_static(std::string_view entity_path, bool static_, const Ts &... as_components) const
Logs one or more archetype and/or component batches optionally static, returning an error.
Definition recording_stream.hpp:580
Error try_send_property(std::string_view name, const Ts &... values) const
Set a property of a recording.
Definition recording_stream.hpp:905
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 gRPC...
Error try_send_columns(std::string_view entity_path, Collection< TimeColumn > time_columns, Collection< ComponentColumn > component_columns) const
Directly log a columns of data to Rerun.
void log_file_from_path(const std::filesystem::path &filepath, std::string_view entity_path_prefix=std::string_view(), bool static_=false) const
Logs the file at the given path using all DataLoaders available.
Definition recording_stream.hpp:672
bool is_enabled() const
Returns whether the recording stream is enabled.
Definition recording_stream.hpp:105
void set_time_duration_nanos(std::string_view timeline_name, int64_t nanos) const
Set the index value of the given timeline as a duration in nanoseconds, for the current calling threa...
void send_property(std::string_view name, const Ts &... values) const
Set a property of a recording.
Definition recording_stream.hpp:893
Error try_send_recording_start_time_nanos(int64_t nanos) const
Set the start time of a recording.
Error try_log(std::string_view entity_path, const Ts &... as_components) const
Logs one or more archetype and/or component batches.
Definition recording_stream.hpp:513
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.
Error connect_grpc(std::string_view url="rerun+http://127.0.0.1:9876/proxy", float flush_timeout_sec=2.0) const
Connect to a remote Rerun Viewer on the given URL.
Error to_stdout() const
Stream all log-data to standard output.
void send_columns(std::string_view entity_path, Collection< TimeColumn > time_columns, Collection< ComponentColumn > component_columns) const
Directly log a columns of data to Rerun.
Definition recording_stream.hpp:858
Error try_log_file_from_path(const std::filesystem::path &filepath, std::string_view entity_path_prefix=std::string_view(), bool static_=false) const
Logs the file at the given path using all DataLoaders available.
Error save(std::string_view path) const
Stream all log-data to a given .rrd file.
Error try_log_static(std::string_view entity_path, const Ts &... as_components) const
Logs one or more archetype and/or component batches as static data, returning an error.
Definition recording_stream.hpp:533
StoreKind kind() const
Returns the store kind as passed during construction.
Definition recording_stream.hpp:97
Error spawn(const SpawnOptions &options={}, std::chrono::duration< TRep, TPeriod > flush_timeout=std::chrono::seconds(2)) const
Definition recording_stream.hpp:203
Error try_log_data_row(std::string_view entity_path, size_t num_data_cells, const ComponentBatch *data_cells, bool inject_time) const
Bottom level API that logs raw data cells to the recording stream.
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 static_=false) const
Logs the given contents using all DataLoaders available.
Definition recording_stream.hpp:722
void set_time_timestamp_secs_since_epoch(std::string_view timeline_name, double seconds) const
Set the index value of the given timeline as seconds since Unix Epoch (1970), for the current calling...
Definition recording_stream.hpp:327
void set_time_duration_secs(std::string_view timeline_name, double secs) const
Set the index value of the given timeline as a duration in seconds, for the current calling thread.
Definition recording_stream.hpp:283
void set_time_duration(std::string_view timeline_name, std::chrono::duration< TRep, TPeriod > duration) const
Set the index value of the given timeline as a duration, for the current calling thread.
Definition recording_stream.hpp:267
Error set_sinks(const Ts &... sinks) const
Stream data to multiple sinks.
Definition recording_stream.hpp:148
void flush_blocking() const
Initiates a flush the batching pipeline and waits for it to propagate.
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.
Definition recording_stream.hpp:406
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.
Definition recording_stream.hpp:373
void send_recording_start_time_nanos(int64_t nanos) const
Set the start time of a recording.
Definition recording_stream.hpp:934
void log_with_static(std::string_view entity_path, bool static_, const Ts &... as_components) const
Logs one or more archetype and/or component batches optionally static, returning an error.
Definition recording_stream.hpp:557
static RecordingStream & current(StoreKind store_kind=StoreKind::Recording)
Retrieves the most appropriate globally available recording stream for the given kind.
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.
void log(std::string_view entity_path, const Ts &... as_components) const
Logs one or more archetype and/or component batches.
Definition recording_stream.hpp:472
void set_thread_local() const
Replaces the currently active recording for this stream's store kind in the thread-local scope with t...
Error try_send_recording_name(std::string_view name) const
Set the name of a recording.
Error try_log_serialized_batches(std::string_view entity_path, bool static_, std::vector< ComponentBatch > batches) const
Logs several serialized batches batches, returning an error on failure.
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.
Definition recording_stream.hpp:357
Result< std::string > serve_grpc(std::string_view bind_ip="0.0.0.0", uint16_t port=9876, std::string_view server_memory_limit="25%") const
Swaps the underlying sink for a gRPC server sink pre-configured to listen on rerun+http://{bind_ip}:{...
void set_time_seconds(std::string_view timeline_name, double seconds) const
Set the current time of the recording, for the current calling thread.
Definition recording_stream.hpp:390
void set_time_timestamp_nanos_since_epoch(std::string_view timeline_name, int64_t nanos) const
Set the index value of the given timeline as nanoseconds since Unix Epoch (1970), for the current cal...
void send_columns(std::string_view entity_path, Collection< TimeColumn > time_columns, Ts... component_columns) const
Directly log a columns of data to Rerun.
Definition recording_stream.hpp:781
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 static_=false) const
Logs the given contents using all DataLoaders available.
void send_recording_name(std::string_view name) const
Set the name of a recording.
Definition recording_stream.hpp:918
void set_global() const
Replaces the currently active recording for this stream's store kind in the global scope with this on...
void set_time_timestamp(std::string_view timeline_name, std::chrono::time_point< TClock > timestamp) const
Set the index value of the given timeline as a timestamp, for the current calling thread.
Definition recording_stream.hpp:308
void set_time_sequence(std::string_view timeline_name, int64_t sequence_nr) const
Set the index value of the given timeline as a sequence number, for the current calling thread.
Error try_send_columns(std::string_view entity_path, Collection< TimeColumn > time_columns, Ts... component_columns) const
Directly log a columns of data to Rerun.
Definition recording_stream.hpp:806
void log_static(std::string_view entity_path, const Ts &... as_components) const
Logs one or more archetype and/or component batches as static data.
Definition recording_stream.hpp:494
A class for representing either a usable value, or an error.
Definition result.hpp:14
bool is_err() const
Returns true if error is not set to rerun::ErrorCode::Ok, implying that no value is contained,...
Definition result.hpp:44
All Rerun C++ types and functions are in the rerun namespace or one of its nested namespaces.
Definition rerun.hpp:23
Arrow-encoded data of a single batch of components together with a component descriptor.
Definition component_batch.hpp:28
Arrow-encoded data of a column of components.
Definition component_column.hpp:20
A sink for log messages.
Definition log_sink.hpp:43
Options to control the behavior of spawn.
Definition spawn_options.hpp:17