Logging

Logging

When to Use

Use this skill when the user wants to capture, route, filter, or silence ovstage's log output: install a log callback, set a severity threshold, filter by channel, or flush pending messages before a checkpoint. For operation/return-code error handling (not logging), use the error-handling skill instead.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• The desired default severity threshold (LogSeverity / ovstage_log_severity_t).
• Any per-channel overrides (a comma-separated <channel>=<level> filter).
• Target API surface: C, Python, or both.
• Whether the caller needs a barrier (flush_log) before reading captured output.
• The shipped headers (ovstage.h, ovstage_types.h) and the referenced test snippet are the authoritative contract.

Prerequisites

• Use an ovstage checkout that contains the include/ headers and the referenced snippet.
• Read the relevant > **Source:** snippet before writing or explaining API usage.
• Hold a live instance/Stage when installing a callback — the callback is process-global but the runtime must be bootstrapped first.
• Do not emit ovstage/USD log messages from inside the callback (it re-enters the dispatcher and can feed back indefinitely).

Instructions

1. Install the callback: C ovstage_set_log_callback(severity, channel_filter, cb, user_data); Python set_log_callback(cb, severity=, channel_filter=). The callback receives (severity, timestamp, message). In C, message is valid only during the call, so copy it to keep it; the Python binding hands the callback an owned str, so there is no such hazard.
2. Choose the default severity threshold for channels not named in channel_filter (NONE disables all unmatched channels); add <channel>=<level> overrides as needed.
3. Do the log-producing work.
4. Call flush_log(timeout) to force pending (asynchronously-dispatched) messages through before reading your captured output.
5. Clear delivery by installing a NULL/None callback (which also flushes and tears down the dispatcher thread).

Output Format

• For explanations, cite the API names, the source snippet, the severity/threshold and channel-filter semantics, and the async-delivery + flush_log caveat.
• For code changes, summarize the files touched, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippet is the source of truth; this skill composes it and describes the surrounding logging API rather than introducing new code.
• Process-global, single callback. set_log_callback replaces any prior callback for the whole process; it is not per-instance.
• Asynchronous delivery. Messages are dispatched on a dedicated thread, so they may arrive after the call that produced them — use flush_log as a barrier before asserting on or reading captured output.
• Callback must not log. Emitting ovstage/USD messages from the callback re-enters the dispatcher; a Python callback that raises has its traceback printed and is then suppressed.
• Not an error channel. Logging is diagnostic output; operation success/failure is reported via return codes / OvstageError (see error-handling).
• Silent by default (standalone). With no callback installed, the standalone runtime prints nothing to the console — there is no default stderr/stdout sink to silence, and the callback is the only way to observe diagnostics. Inside a host application that configures its own logging, the host's console configuration governs.
• ⚠️ Draft — API in flux. Treat exact symbols/ordering as provisional against the headers.

Overview

ovstage_set_log_callback routes ovstage's log messages — and messages from its USD support layer — to one process-global callback. severity is the default threshold for channels not matched by a rule in channel_filter (messages below it are dropped); channel_filter is an optional comma-separated <channel>=<level> list (e.g. "omni.ovstage=verbose"), NULL applying severity uniformly. Delivery is asynchronous on a dispatcher thread; ovstage_flush_log(timeout) blocks until messages emitted before the call have drained.

When ovstage runs standalone (the shipped package used directly), no callback means no output: the console (stdout/stderr) stays silent at every severity — a final sanitized message on a fatal process abort is the only exception — and diagnostics exist only for callback subscribers. When ovstage is embedded in a host application that configures its own logging, console behavior follows the host's configuration. Operation failures do not depend on logging — they surface through return codes and the error string accessors (see error-handling). USD-support-layer statuses arrive at INFO (warnings and USD coding errors at WARNING, other errors at ERROR), so a callback whose threshold is the default WARNING will not see statuses; lower the threshold (or add a channel rule such as omni.ovstage.usd=info) to observe asset-resolution traffic.

Severities (ovstage_log_severity_t / LogSeverity): VERBOSE (-2), INFO (-1), WARNING (0), ERROR (1), NONE (3, a threshold sentinel that disables all logging and is never delivered).

C

Install a callback, prove a bogus channel-prefix filter with a NONE default threshold suppresses everything, flush, and clear:

Source: tests/c/test_logging.cpp snippet log-callback-filter-c

Python

The Python binding takes the callback first, then severity / channel_filter; a None callback clears delivery:

Source: tests/python/test_logging.py snippet log-callback-filter

Key Types / Functions

Troubleshooting

• No messages delivered — the default severity is too high (or NONE), or a channel filter excludes the channels you expected; lower the threshold / adjust the filter. Also confirm you called flush_log before checking (delivery is asynchronous).
• set_log_callback fails (OP_FAILED) — the runtime is not bootstrapped; create a Stage / instance first.
• Filter rejected (INVALID_ARGUMENT) — the channel_filter string failed to parse; use the <channel>=<level> form with levels verbose|debug|info|warn|warning|error|fatal|none.
• flush_log hangs — a callback that blocks stalls the dispatcher; pass a finite timeout, and never block (or log) inside the callback.
• Message text garbage after the call (C only) — the C message is valid only during the callback; copy it if it must outlive the call. The Python binding gives you an owned str.

References

• Use the > **Source:** directives in this skill to locate tested snippets before reusing API patterns.
• error-handling — operation return codes and per-op errors (the non-logging failure surface).
• loading-usd — population is a convenient source of runtime log traffic to capture.
• The shipped include/ovstage/ovstage.h / ovstage_types.h headers are the authoritative contract.