class TracingSession

Configure the session passing the trace config.

If a writable file handle is given through |fd|, the trace will

automatically written to that file. Otherwise you should call ReadTrace()

to retrieve the trace data. This call does not take ownership of |fd|.

TODO(primiano): add an error callback.

Enable tracing asynchronously. Use SetOnStartCallback() to get a

notification when the session has fully started.

Enable tracing and block until tracing has started. Note that if data

sources are registered after this call was initiated, the call may return

before the additional data sources have started. Also, if other producers

(e.g., with system-wide tracing) have registered data sources without start

notification support, this call may return before those data sources have

started.

This callback will be invoked when all data sources have acknowledged that

tracing has started. This callback will be invoked on an internal perfetto

thread.

This callback can be used to get a notification when some error occurred

(e.g., peer disconnection). Error type will be passed as an argument. This

callback will be invoked on an internal perfetto thread.

Issues a flush request, asking all data sources to ack the request, within

the specified timeout. A "flush" is a fence to ensure visibility of data in

the async tracing pipeline. It guarantees that all data written before the

Flush() call will be visible in the trace buffer and hence by the

ReadTrace() / ReadTraceBlocking() methods.

Args:

callback: will be invoked on an internal perfetto thread when all data

sources have acked, or the timeout is reached. The bool argument

will be true if all data sources acked within the timeout, false if

the timeout was hit or some other error occurred (e.g. the tracing

session wasn't started or ended).

timeout_ms: how much time the service will wait for data source acks. If

0, the global timeout specified in the TraceConfig (flush_timeout_ms)

will be used. If flush_timeout_ms is also unspecified, a default value

of 5s will be used.

Known issues:

Because flushing is still based on service-side scraping, the very last

trace packet for each data source thread will not be visible. Fixing

this requires either propagating the Flush() to the data sources or

changing the order of atomic operations in the service (b/162206162).

Until then, a workaround is to make sure to call

DataSource::Trace([](TraceContext ctx) { ctx.Flush(); }) just before

stopping, on each thread where DataSource::Trace has been previously

called.

Blocking version of Flush(). Waits until all data sources have acked and

returns the success/failure status.

Disable tracing asynchronously.

Use SetOnStopCallback() to get a notification when the tracing session is

fully stopped and all data sources have acked.

Disable tracing and block until tracing has stopped.

This callback will be invoked when tracing is disabled.

This can happen either when explicitly calling TracingSession.Stop() or

when the trace reaches its |duration_ms| time limit.

This callback will be invoked on an internal perfetto thread.

Changes the TraceConfig for an active tracing session. The session must

have been configured and started before. Note that the tracing service

only supports changing a subset of TraceConfig fields,

see ConsumerEndpoint::ChangeTraceConfig().

Synchronous version of ReadTrace(). It blocks the calling thread until all

the trace contents are read. This is slow and inefficient (involves more

copies) and is mainly intended for testing.

Synchronous version of GetTraceStats() for convenience.

Synchronous version of QueryServiceState() for convenience.