Skip to main content

Rust Debugging and Observability

Rust stores structured SqlLogEntry values on the trusted UserContext. Keep sql and the parameter count in application diagnostics; debug_sql and params are operator-only data.

use teaql_runtime::SqlLogOptions;

context.set_sql_log_options(SqlLogOptions::select_only());
context.clear_sql_logs();

let rows = Q::schools().limit(20)
.comment("Diagnose the school search")
.purpose("Verify filters, facets, and relation loading")
.execute_for_list(&context)
.await?;

let safe = sql_evidence(&context); // projection from generated Debug Assist

Use SqlLogOptions::all(), select_only(), mutation_only(), clear_sql_logs(), and disable_sql_log(). Query and mutation switches are also independent through disable_select_sql_log() and disable_mutation_sql_log().

Run the Query, Facet, grouped aggregate, relation statistic, and deep Top-N examples from Rust advanced data operations. Inspect trace_path to separate the outer Request from each relation load; review repeated child traces for N+1 behavior and confirm Top-N stays in the provider plan.

For saves, collect mutation-only entries around .audit_as(...).save(&context) and retain the native error category. Rust Request Policy covers select, insert, update, delete, and recover, and entity data-service behavior adds a second customization boundary. Verify tenant failures and the independent SafeAuditEventSink path.

Install telemetry with context.set_runtime_telemetry(Arc::new(telemetry)). Rust also supports the environment SQL/audit levels and table/entity focus in the common guide. Rendered SQL never belongs in RuntimeTelemetry.

Finish with the shared checklist.

Order troubleshooting​

If an expression reports NotLoaded, first read SQL NULL vs an unloaded Rust field. The repair checklist distinguishes a legitimate null default from a missing projection.

For the full operation and recovery sequence, use the Rust mutation recipes: deletion, state changes and version conflicts.

Start with the Rust Order tutorial and API usage guide. Diagnose the first native error before changing a dependency or rerunning a suite. Compare the failing runtime, model and fixture against the authority for that operation.

SymptomWhat to inspectNext action
First-run build or lockfile failureCompiler version inside the extracted package, RUSTUP_TOOLCHAIN, public registry access and native C compiler.Follow the source-package setup. Keep Rust 1.97.1, the checked-in lockfile and exact published 5.0.7 pins; do not add an unpublished runtime path patch.
Database missing, wrong file or init refuses an existing fileAbsolute ORDER_DATABASE, completed initialization and whether the binary was invoked through the script.The script sets ORDER_WORKFLOW_SERVICE_CORE_DATABASE_URL; ORDER_DATABASE alone does not configure a direct binary invocation. Use a fresh file after a partial seed.
ORDER_OK is printed but the wrong Order is visibleAbsolute database path, model revision and selected fixture.The first-edit fixture has three Orders; pagination and insights use separate nine-/ten-order fixtures. Keep each in its own database and use business keys, not copied numeric IDs.
Empty result or duplicate business identityQuery cardinality and scoped predicates.Keep the expected-one check. An empty result is distinct from a provider exception. A buyer filter alone does not authorize a tenant.
Wrong total or omitted item after editFull scalar/relation loading, item bounds and money validation.Reload the complete bounded collection before calculating totals; a preview is not a full edit graph and omission is not deletion.
NotLoaded panic or lost missing-field pathThe expression read a field omitted from the projection.Select the field explicitly. The example catches a panic only to report the negative probe; normal application code should preserve the native diagnostic.
Borrowed relation value does not live long enoughA value was borrowed from a temporary relation handle.Bind let handle = order.order_item_list() first and keep it alive while using handle.value(); follow the retained graph function.
Changed item clone is absent after parent saveThe clone is detached from the saved parent graph.Use the same typed transaction and save_audited for both Order and item, as in the tutorial.
Retained IDs or cursor behavior differs from the receiptRuntime package/config or matching-set key differs; a fallback is not proof of a cursor hit.Check the recorded Cargo workspace/config and actual query plan. The pagination repair remains WORKSPACE PASS — RELEASE PENDING.
SQLite owner cannot be recovered at shutdownA context, provider or outstanding future may still retain a reference.Complete or cancel/drop request futures first, drop provider/context owners, then use the connection-ownership proof in the soak example. Do not infer physical closure from an application counter alone.

Order query troubleshooting​

Use Rust Order Queries with the matching export/insights fixture and recorded workspace. Diagnose the native plan and result carrier before changing an optimizer, cache or numeric conversion.

SymptomWhat to inspectNext action
Export count is 9 instead of 8Export uses a buyer-only predicate; the ten-order fixture adds an export-buyer EUR control.Use the nine-order export database. Retained-ID and summary recipes deliberately use the ten-order database and a currency predicate.
Empty export tail looks like failureThe ascending export's final offset 9 reports CACHE_MISS, zero rows and exact total 8.Stop on the empty tail normally. For retained IDs an empty tail can instead be an ID_SET_HIT.
ID overflow shows 5 while total is 8Capacity 4, lower-bound scan and exact provider COUNT.Keep observedCount separate from the matching total; do not retain a partial set or present 5 as the exact count.
Grand total equals a page/preview sumParent page size, child preview size and predicates on every aggregate/Facet request.Aggregate the whole filtered set in the provider. In the all-USD fixture it is 8/35350, even though only three parents are visible.
Empty sum or zero buckets are unexpectedEmpty groups, the one-row overall aggregate, and include-all versus matched-only Facets.Preserve overall count 0/sum null; keep zero status buckets only for the requested all-status variant.
Store replacement or async store methods do not resolveThe helper needs mutable context for installation and IdSetStore in scope for trait calls.Keep the complete Arc<ObservedIds> wiring from the recipe; do not copy only the request-builder call.
Cursor plan disagrees with the recorded exportCheck the native observation method and exact qualified Cargo workspace/config.The retained pagination-observation repair remains RELEASE PENDING. A new process at offset 3 legitimately falls back to CACHE_MISS.
Aggregate money/count access panicsThe grouped carrier is CompactRow, not an Order entity; check the alias and nullable overall sum.Use get(key)/try_f64() as in the source. The non-null group helper is not appropriate for an empty overall SUM.

Read the plan immediately after its request; a namespace string or stale observation from another request is not proof of reuse. The existing query cases record actual provider SQL, keys, builds/hits, elapsed expiry/invalidation events and unchanged database snapshots. Use that evidence first. Fixed-data reads do not supply a concurrent-write snapshot or a distributed-cache guarantee. All original runtime pending-release and generator-deployment qualifications remain.

Order isolation troubleshooting​

Use Rust Order Isolation with the v1.1 model/library and fresh eight-order database. Inspect the facade boundary and actual provider predicates before broadening access or changing a cache namespace.

Symptom / codeWhat to inspectNext action
Wrong model or missing tenant-key APIv1.0 core/query workspace versus the v1.1 isolation library, manifest and database.Use the retained regenerated isolation set; this is a fresh-database tutorial, not a live migration. Do not hand-edit generated files.
UNAUTHENTICATED / FORGED_SCOPEServer-owned session resolution and identity/policy fields in business JSON.Keep client fields out of the session tuple; the fixture key is not a production credential.
INVALID_TRUSTED_SCOPEZero/multiple tenant roots for the resolved key.Fail closed and repair provisioning; never choose an arbitrary root.
Foreign ID gives NOT_FOUNDRoot + buyer predicates and parent-owned item resolution.Preserve the common missing/foreign response; do not make a public unscoped lookup to distinguish them.
INVALID_BOUNDS, FORBIDDEN_FIELD, FORBIDDEN_OPERATIONNative numeric type, exact patch keys and read-only actor.Use integer 1–2 and the exact note/label patch. Do not coerce identity, strip extra fields or partially save.
List is scoped but summary/cache is notSame trusted predicates on every aggregate and retained request.Expect count 2/7700 cents; cache a,b,c,a must BUILD,BUILD,BUILD,HIT on one context with distinct scope identities.
Child edit reads a partial graph or changes unrelated versionsThree-child sentinel, two-child supported bound and native save path.Detail/edit overflow returns ITEM_LIMIT; preserve scoped complete-state loading and compare unrelated rows.
Relation scope, borrow or analytic conversion does not compileThe relation predicate is with_commerce_platform_matching with a root-ID subquery; loaded relation data requires a bound handle.Keep ? provider failures, checked CompactRow values and the recorded audited direct-item save; do not translate Java method names.
Audit actor or HTTP authorization is assumed from response metadataThe example tuple is separate from native context principal and transport authentication.Wire real authenticated membership/principal mapping at the service boundary. JSON actor metadata and an audit reason do not prove that integration.

The isolation receipt checks the named console requests with SQL and SQLite snapshots. It does not certify arbitrary raw Q/database access, exhaustive hostile JSON, production migration or authorization revocation during a save. Keep runtime and generator release marks from the API scope guide.

Read the evidence in order​

QuestionExisting authority
Query shape, null state, edit, page or analytic resultCore Order receipt, this language’s native source, and the selected fixture.
Stale winner or atomic child failureConcurrent writes and the stored unchanged/authoritative database snapshots. Busy/locked and timeout errors do not qualify as version conflicts.
Request cancellation, provider statement failure or real COMMIT failureLifecycle evidence. Preserve the native error and verify rollback before retry.
Transaction, connection or task ownership after drain/closeFinite soak evidence. Separate active leases from idle owned connections and verify the final native close/lifetime end.
Published package differs from a recorded workspace PASSRelease qualifications. Keep the pending-release marker and exact runtime source/package identity.

Collect the failing phase, native error type/message, model and fixture revision, resolved runtime/package identity, and parameterized SQL shape/affected rows. Keep raw parameters and rendered SQL in the trusted operator boundary. Runtime telemetry sampling is not proof that an audit event was delivered or a transaction committed.

Reuse the existing failure and successful recovery evidence first. If a specific claim still has no authority, isolate that one operation on a disposable database and record the minimal result. Keep that reproduction scoped to the failing operation. Preserve School, every historical Order receipt, all six lifecycle/soak workspace pending-release qualifications, and the generator repairs pending deployment.

This language’s recorded advanced Order result remains WORKSPACE PASS — RELEASE PENDING.