Google Git
Sign in
fuchsia / reference-docs / main / . / f11 / sdk / fidl / fuchsia.logger / README.md
blob: a356ef68865ef1b2d73541522c4e3a11a5cc9af4 [file] [log] [blame] [view]
<link rel="stylesheet" href="../style.css" />
[TOC]
# fuchsia.logger
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>
## **PROTOCOLS**
## Log {#Log}
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=91)*
<p>Interface for LogListenerSafe to register to listen to logs.</p>
### DumpLogsSafe {#Log.DumpLogsSafe}
<p>Dumps all cached logs by calling LogMany() followed by Done() on <code>log_listener</code>.
A null <code>options</code> indicates no filtering is requested.</p>
#### Request {#Log.DumpLogsSafe_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>log_listener</code></td>
<td>
<code><a class='link' href='#LogListenerSafe'>LogListenerSafe</a></code>
</td>
</tr>
<tr>
<td><code>options</code></td>
<td>
<code><a class='link' href='#LogFilterOptions'>LogFilterOptions</a>?</code>
</td>
</tr>
</table>
### ListenSafe {#Log.ListenSafe}
<p>Dumps all cached logs by calling LogMany() in batches followed by Log() for each new log
message.
A null <code>options</code> indicates no filtering is requested.</p>
#### Request {#Log.ListenSafe_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>log_listener</code></td>
<td>
<code><a class='link' href='#LogListenerSafe'>LogListenerSafe</a></code>
</td>
</tr>
<tr>
<td><code>options</code></td>
<td>
<code><a class='link' href='#LogFilterOptions'>LogFilterOptions</a>?</code>
</td>
</tr>
</table>
### ListenSafeWithSelectors {#Log.ListenSafeWithSelectors}
<p>Listens to new log entries by calling Log() on <code>log_listener</code>.
A null <code>options</code> indicates no filtering is requested.</p>
#### Request {#Log.ListenSafeWithSelectors_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>log_listener</code></td>
<td>
<code><a class='link' href='#LogListenerSafe'>LogListenerSafe</a></code>
</td>
</tr>
<tr>
<td><code>options</code></td>
<td>
<code><a class='link' href='#LogFilterOptions'>LogFilterOptions</a>?</code>
</td>
</tr>
<tr>
<td><code>selectors</code></td>
<td>
<code>vector&lt;<a class='link' href='../fuchsia.diagnostics/'>fuchsia.diagnostics</a>/<a class='link' href='../fuchsia.diagnostics/#LogInterestSelector'>LogInterestSelector</a>&gt;[64]</code>
</td>
</tr>
</table>
## LogListenerSafe {#LogListenerSafe}
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=159)*
<p>A listener who will notify the <code>Log</code> of the receipt of each message.</p>
### Done {#LogListenerSafe.Done}
<p>Called when this listener was passed to <code>DumpLogsSafe()</code> and all cached logs have been sent.</p>
#### Request {#LogListenerSafe.Done_Request}
&lt;EMPTY&gt;
### Log {#LogListenerSafe.Log}
<p>Called for single messages.</p>
<p>The return value is used for flow control, and implementers should acknowledge receipt of
each message in order to continue receiving future messages.</p>
#### Request {#LogListenerSafe.Log_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>log</code></td>
<td>
<code><a class='link' href='#LogMessage'>LogMessage</a></code>
</td>
</tr>
</table>
#### Response {#LogListenerSafe.Log_Response}
&lt;EMPTY&gt;
### LogMany {#LogListenerSafe.LogMany}
<p>Called when serving cached logs.</p>
<p>Max logs size per call is <code>MAX_LOG_MANY_SIZE_BYTES</code> bytes.</p>
<p>The return value is used for flow control, and implementers should acknowledge receipt of
each batch in order to continue receiving future messages.</p>
#### Request {#LogListenerSafe.LogMany_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>log</code></td>
<td>
<code>vector&lt;<a class='link' href='#LogMessage'>LogMessage</a>&gt;</code>
</td>
</tr>
</table>
#### Response {#LogListenerSafe.LogMany_Response}
&lt;EMPTY&gt;
## LogSink {#LogSink}
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=126)*
<p>Drains a program's logs.</p>
### Connect {#LogSink.Connect}
<p>Send this socket to be drained.</p>
<p>See <a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:zircon/system/ulib/syslog/include/lib/syslog/wire_format.h">wire_format.h</a>
for what is expected to be received over the socket.</p>
#### Request {#LogSink.Connect_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>socket</code></td>
<td>
<code>handle&lt;socket&gt;</code>
</td>
</tr>
</table>
### ConnectStructured {#LogSink.ConnectStructured}
<p>Send this socket to be drained, using the structured logs format.</p>
<p>See <a href="https://fuchsia.dev/fuchsia-src/reference/platform-spec/diagnostics/logs-encoding">Encoding structured records</a>
for what is expected to be received over the socket.</p>
#### Request {#LogSink.ConnectStructured_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>socket</code></td>
<td>
<code>handle&lt;socket&gt;</code>
</td>
</tr>
</table>
### WaitForInterestChange {#LogSink.WaitForInterestChange}
<p>LogSink implementers will return to this hanging-get whenever the scope of
their interest changes. Clients are expected to emit messages based on
the registered Interest. In the event that an empty interest is
conveyed, clients should emit messages based on their default
e.g. compile time configuration. Each client may only poll this once at a time.
Invoking WaitForInterestChange a second time before the first call returns will
result in an error being returned.</p>
#### Request {#LogSink.WaitForInterestChange_Request}
&lt;EMPTY&gt;
#### Response {#LogSink.WaitForInterestChange_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#LogSink_WaitForInterestChange_Result'>LogSink_WaitForInterestChange_Result</a></code>
</td>
</tr>
</table>
## **STRUCTS**
### LogFilterOptions {#LogFilterOptions data-text="LogFilterOptions"}
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=46)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="LogFilterOptions.filter_by_pid">
<td><code>filter_by_pid</code></td>
<td>
<code>bool</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogFilterOptions.pid">
<td><code>pid</code></td>
<td>
<code>uint64</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogFilterOptions.filter_by_tid">
<td><code>filter_by_tid</code></td>
<td>
<code>bool</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogFilterOptions.tid">
<td><code>tid</code></td>
<td>
<code>uint64</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogFilterOptions.verbosity">
<td><code>verbosity</code></td>
<td>
<code>uint8</code>
</td>
<td><p>If more than zero, logs would be filtered based on verbosity and
<code>min_severity</code> would be ignored.</p>
</td>
<td>No default</td>
</tr>
<tr id="LogFilterOptions.min_severity">
<td><code>min_severity</code></td>
<td>
<code><a class='link' href='#LogLevelFilter'>LogLevelFilter</a></code>
</td>
<td><p>Severity used as threshold to determine logging level.</p>
</td>
<td>No default</td>
</tr>
<tr id="LogFilterOptions.tags">
<td><code>tags</code></td>
<td>
<code>vector&lt;string&gt;[16]</code>
</td>
<td><p>If non-empty, return all messages which contain at least one specified
tag. If empty, messages will not be filtered by tag.
Passed tags should not be more than <code>MAX_TAG_LEN_BYTES</code> bytes in length
and max tags can be <code>MAX_TAGS</code>.
Listener would be discarded if the limit is not followed.</p>
</td>
<td>No default</td>
</tr>
</table>
### LogMessage {#LogMessage data-text="LogMessage"}
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=74)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="LogMessage.pid">
<td><code>pid</code></td>
<td>
<code>uint64</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogMessage.tid">
<td><code>tid</code></td>
<td>
<code>uint64</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogMessage.time">
<td><code>time</code></td>
<td>
<code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#time'>time</a></code>
</td>
<td><p><a href="https://fuchsia.dev/fuchsia-src/reference/syscalls/clock_get_monotonic.md">zx_clock_get_monotonic</a></p>
</td>
<td>No default</td>
</tr>
<tr id="LogMessage.severity">
<td><code>severity</code></td>
<td>
<code>int32</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogMessage.dropped_logs">
<td><code>dropped_logs</code></td>
<td>
<code>uint32</code>
</td>
<td><p>See <a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:zircon/system/ulib/syslog/include/lib/syslog/wire_format.h">wire_format.h</a>.
As messages can be served out of order, this should only be logged if more than
last count.</p>
</td>
<td>No default</td>
</tr>
<tr id="LogMessage.tags">
<td><code>tags</code></td>
<td>
<code>vector&lt;string&gt;[5]</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="LogMessage.msg">
<td><code>msg</code></td>
<td>
<code>string[32768]</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### LogSink_WaitForInterestChange_Response {#LogSink_WaitForInterestChange_Response data-text="LogSink_WaitForInterestChange_Response"}
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=142)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="LogSink_WaitForInterestChange_Response.data">
<td><code>data</code></td>
<td>
<code><a class='link' href='../fuchsia.diagnostics/'>fuchsia.diagnostics</a>/<a class='link' href='../fuchsia.diagnostics/#Interest'>Interest</a></code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
## **ENUMS**
### InterestChangeError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#InterestChangeError data-text="InterestChangeError"}
Type: <code>uint32</code>
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=118)*
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="InterestChangeError.CALLED_TWICE">
<td><h3 id="InterestChangeError.CALLED_TWICE" class="add-link hide-from-toc">CALLED_TWICE</h3></td>
<td><code>1</code></td>
<td><p>Incorrectly called WaitForInterestChange twice
without waiting for the first call to return.</p>
</td>
</tr>
</table>
### LogLevelFilter [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#LogLevelFilter data-text="LogLevelFilter"}
Type: <code>int8</code>
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=16)*
<p>Log levels used with log related filtering.
Filtering uses a heuristic based on a threshold of
minimum severity level - with any log equal to or
greater than the threshold being included in the
printable logs.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="LogLevelFilter.TRACE">
<td><h3 id="LogLevelFilter.TRACE" class="add-link hide-from-toc">TRACE</h3></td>
<td><code>16</code></td>
<td></td>
</tr>
<tr id="LogLevelFilter.DEBUG">
<td><h3 id="LogLevelFilter.DEBUG" class="add-link hide-from-toc">DEBUG</h3></td>
<td><code>32</code></td>
<td></td>
</tr>
<tr id="LogLevelFilter.INFO">
<td><h3 id="LogLevelFilter.INFO" class="add-link hide-from-toc">INFO</h3></td>
<td><code>48</code></td>
<td></td>
</tr>
<tr id="LogLevelFilter.WARN">
<td><h3 id="LogLevelFilter.WARN" class="add-link hide-from-toc">WARN</h3></td>
<td><code>64</code></td>
<td></td>
</tr>
<tr id="LogLevelFilter.ERROR">
<td><h3 id="LogLevelFilter.ERROR" class="add-link hide-from-toc">ERROR</h3></td>
<td><code>80</code></td>
<td></td>
</tr>
<tr id="LogLevelFilter.FATAL">
<td><h3 id="LogLevelFilter.FATAL" class="add-link hide-from-toc">FATAL</h3></td>
<td><code>96</code></td>
<td></td>
</tr>
<tr id="LogLevelFilter.NONE">
<td><h3 id="LogLevelFilter.NONE" class="add-link hide-from-toc">NONE</h3></td>
<td><code>127</code></td>
<td></td>
</tr>
</table>
## **UNIONS**
### LogSink_WaitForInterestChange_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#LogSink_WaitForInterestChange_Result data-text="LogSink_WaitForInterestChange_Result"}
*Defined in [fuchsia.logger/logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=142)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="LogSink_WaitForInterestChange_Result.response">
<td><h3 id="LogSink_WaitForInterestChange_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#LogSink_WaitForInterestChange_Response'>LogSink_WaitForInterestChange_Response</a></code>
</td>
<td></td>
</tr>
<tr id="LogSink_WaitForInterestChange_Result.err">
<td><h3 id="LogSink_WaitForInterestChange_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#InterestChangeError'>InterestChangeError</a></code>
</td>
<td></td>
</tr>
</table>
## **CONSTANTS**
<table>
<tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
<tr id="LOG_LEVEL_DEFAULT">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=38">LOG_LEVEL_DEFAULT</a></td>
<td><p>Default log level used to initialize loggers.</p>
</td>
</tr>
<tr id="LOG_SEVERITY_MAX_STEP">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=32">LOG_SEVERITY_MAX_STEP</a></td>
<td>
<code>6</code>
</td>
<td><code>uint8</code></td>
<td><p>Maximum available log severity.</p>
</td>
</tr>
<tr id="LOG_SEVERITY_STEP_SIZE">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=29">LOG_SEVERITY_STEP_SIZE</a></td>
<td>
<code>16</code>
</td>
<td><code>uint8</code></td>
<td><p>The interval between discrete log severity levels</p>
</td>
</tr>
<tr id="LOG_VERBOSITY_STEP_SIZE">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=35">LOG_VERBOSITY_STEP_SIZE</a></td>
<td>
<code>1</code>
</td>
<td><code>uint8</code></td>
<td><p>The interval between discrete log verbosity levels</p>
</td>
</tr>
<tr id="MAX_DATAGRAM_LEN_BYTES">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=72">MAX_DATAGRAM_LEN_BYTES</a></td>
<td>
<code>32768</code>
</td>
<td><code>uint32</code></td>
<td><p>Max byte size for message payload.</p>
</td>
</tr>
<tr id="MAX_LOG_MANY_SIZE_BYTES">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=156">MAX_LOG_MANY_SIZE_BYTES</a></td>
<td>
<code>16384</code>
</td>
<td><code>uint64</code></td>
<td><p>Max log bytes per call to a listener.</p>
</td>
</tr>
<tr id="MAX_TAGS">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=41">MAX_TAGS</a></td>
<td>
<code>16</code>
</td>
<td><code>uint8</code></td>
<td><p>Max number of tags that can be passed to filter by listener.</p>
</td>
</tr>
<tr id="MAX_TAGS_PER_LOG_MESSAGE">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=69">MAX_TAGS_PER_LOG_MESSAGE</a></td>
<td>
<code>5</code>
</td>
<td><code>uint8</code></td>
<td><p>Max tags that will be attached to a LogMessage.</p>
</td>
</tr>
<tr id="MAX_TAG_LEN_BYTES">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.logger/logger.fidl;l=44">MAX_TAG_LEN_BYTES</a></td>
<td>
<code>63</code>
</td>
<td><code>uint8</code></td>
<td><p>Max tag length that can be passed to filter by listener.</p>
</td>
</tr>
</table>