ADR-0001 — SP telemetry via flat span attributes, not SYSTEM$SET_RETURN_VALUE
Status: accepted Date: 2026-05-31
Context
Snowflake Tasks support SYSTEM$SET_RETURN_VALUE to pass data between task runs.
Early SP implementations used it as the observability mechanism — the SP wrote a
JSON payload as the return value, and monitoring queries parsed it.
Two problems emerged:
1. SYSTEM$SET_RETURN_VALUE couples the SP to the Task runtime — a SP called directly
(in tests, on-demand) has no Task context and the call fails or silently does nothing.
2. JSON string payloads in QUERY_HISTORY / EVENT_TABLE require PARSE_JSON() at query
time — every monitoring query pays the parsing cost and becomes fragile against schema changes.
Decision
SP observability uses sp_trace() with flat span attributes written to EVENT_TABLE.
SYSTEM$SET_RETURN_VALUE is never called from SP code.
DAG-to-SP data passing uses load_kwargs() on input and v_return_values dict on output —
the Task wrapper layer reads v_return_values and calls SYSTEM$SET_RETURN_VALUE on behalf
of the SP, keeping the SP decoupled.
Consequences
- SPs are callable directly (tests, on-demand) without a Task context.
- EVENT_TABLE span attributes are flat key-value pairs — queryable with
WHERE resource_attributes['key'] = 'value', no JSON parsing. - The Task wrapper is the only code that knows about
SYSTEM$SET_RETURN_VALUE— one place to change if Snowflake evolves this API. - Monitoring dashboards are simpler and faster.