Skip to main content

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()
    .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.