Java Debugging and Observability
Install one trusted DebugEvidence.Sink as the RuntimeLogSink when building
TeaQLRuntime. The generated Debug Assist contains the complete reusable sink;
application diagnostics should expose only its safeEvidence() projection.
DebugEvidence.Sink evidence = new DebugEvidence.Sink();
TeaQLRuntime runtime = TeaQLRuntime.builder()
.metadata(metadata)
.dataService("default", provider)
.requestPolicy(requestPolicy)
.logSink(evidence)
.telemetry(runtimeTelemetry)
.build();
evidence.enableSelectSqlEvidence();
SmartList<School> rows = Q.schools().limit(20)
.comment("Diagnose the school search")
.purpose("Verify filters, facets, and relation loading")
.executeForList(context);
List<DebugEvidence.SafeSqlEvidence> safe = evidence.safeEvidence();
Use enableAllSqlEvidence(), enableSelectSqlEvidence(),
enableMutationSqlEvidence(), and disableSqlEvidence(). Mode changes clear
old entries. diagnosticSql() contains value-rendered operator output and must
not enter HTTP responses or telemetry.
For a Facet, grouped aggregate, relation statistic, or deep per-parent Top-N
case, run the exact Java request from
Java advanced data operations, then map each
ExecutionMetadata trace to the outer Request and selected relation. Compare
the parameterized SQL shape, elapsed time, result count, and Facet/aggregate
alias carrier—not raw values.
For Mutation diagnostics, switch to mutation-only evidence, preserve
auditAs(...), and distinguish checker failure, policy rejection, optimistic
conflict, provider failure, affected rows, and AppAuditEventSink delivery.
Java Request Policy currently has select, insert, update, delete, and recover
hooks, so tenant-negative tests should cover every one.
Query and mutation execution logging are on by default and can be disabled
independently with queryExecutionLogging(false) and
mutationExecutionLogging(false). Java also supports the environment log
levels and table/entity focus described in the
common guide. Install
OpenTelemetry through TeaQLRuntime.builder().telemetry(...); sampling never
replaces application audit delivery.
Finish with the shared checklist.
Order troubleshooting
For the full operation and recovery sequence, use the Java mutation recipes: deletion, state changes and version conflicts.
Start with the Java 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.
| Symptom | What to inspect | Next action |
|---|---|---|
| First-run build fails before compilation | JDK reported by mvn -version, public repository access and the downloaded package's pinned manifests. | Follow the source-package setup; use JDK 21 and run bash order.sh build. Do not substitute a local unpublished runtime to conceal a dependency failure. |
init refuses an existing DB, or a read says DB missing | The absolute ORDER_DATABASE and whether initialization completed. | Use a new disposable path for another fixture run. Keep the same path for read/edit/verify; initialization never deletes old data. |
ORDER_OK is printed but the wrong Order is visible | Absolute 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 identity | Query 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 edit | Full 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. |
ConcurrentModifyException with an empty message | The public exception type already identifies optimistic rejection; a text-only classifier can miss it. | Reload the full Order/item state and decide whether the edit is still valid. Keep the exact exception type and affected-row evidence. |
| COMMIT BUSY followed by failure restoring auto-commit or reusing a pooled connection | The recorded published JDBC cleanup defect is distinct from a stale version. | Use the recorded Java workspace JDBC repair for this lifecycle scope; retain the published failure. Do not add an application auto-commit reset to conceal cleanup failure. |
| Only the Order total or only the item seems changed | Inspect the actual graph being saved and the transaction boundary. | Keep the changed item in the loaded Order graph for the core save, or save all intended entities through the same explicit transaction as in the lifecycle example. |
| Idle requests appear to retain connections | Check Hikari active/waiting/total separately. An idle connection retained by a pool is not an active lease. | Compare against the warmed baseline; verify active leases return to zero and close the owned data source at application shutdown, as demonstrated by the soak console. |
Order query troubleshooting
Use Java 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.
| Symptom | What to inspect | Next action |
|---|---|---|
| Export count is 9 instead of 8 | Export 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 failure | The 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 8 | Capacity 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 sum | Parent 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 unexpected | Empty 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. |
| Composite sorting does not seek | The recorded first page reports FIRST_PAGE and the next reports ORDER_NOT_SINGLE. | Keep the native fallback; use single ID ordering for this seekable export. Do not infer failure from a supported offset fallback. |
| No retained-store hit is visible | Check IdSetStore.class.getName() registration, same context and the actual key/events. | The application wrapper delegates to the native store. Invalidate that observed key, not only the namespace string. |
| Facet value access fails | Java Facets here are typed status entities, while aggregation returns analytic rows. | Read the status code through E and the Facet count through getDynamicProperty("count"); use the explicit statusId group alias from the aggregate request. |
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 Java 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 / code | What to inspect | Next action |
|---|---|---|
| Wrong model or missing tenant-key API | v1.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_SCOPE | Server-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_SCOPE | Zero/multiple tenant roots for the resolved key. | Fail closed and repair provisioning; never choose an arbitrary root. |
Foreign ID gives NOT_FOUND | Root + 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_OPERATION | Native 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 not | Same 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 versions | Three-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. |
| Root or total handling follows a translated API | Java uses Session, in-place request builders, filterByCommercePlatform and explicit .count()/getTotalCount(). | Use the native excerpt; only Denied becomes an expected facade code. Keep published isolation separate from the pending JDBC lifecycle fix. |
| Audit actor or HTTP authorization is assumed from response metadata | The 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
| Question | Existing authority |
|---|---|
| Query shape, null state, edit, page or analytic result | Core Order receipt, this language’s native source, and the selected fixture. |
| Stale winner or atomic child failure | Concurrent 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 failure | Lifecycle evidence. Preserve the native error and verify rollback before retry. |
| Transaction, connection or task ownership after drain/close | Finite soak evidence. Separate active leases from idle owned connections and verify the final native close/lifetime end. |
| Published package differs from a recorded workspace PASS | Release 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.
The Java core/isolation/stock published passes remain valid for their recorded scopes; the later Java JDBC COMMIT-cleanup repair is RELEASE PENDING.