SRE & Observability

TeaQL gives operators several places to correlate business intent with runtime work, but the visibility of a comment in an application log, database log, APM system, or audit sink must be verified separately.

Current evidence boundary: the maintained Rust Golden Path executes TeaQL 4.1.1 with SQLite. Current generated-workspace environment variables and the separate teaql-runtime formatter layer have been source-reviewed. PostgreSQL and MySQL server-log propagation, production APM integrations, trace-chain formatting, and load behavior have not been executed by this documentation.

Observable Intent Boundaries

Boundary	Application contract	What it can provide	What still needs verification
Query	comment(...) → purpose(...) → execute_for_xxx(...)	Operation description and business reason attached before execution.	Exact emitted fields, redaction, provider propagation, and sink retention.
Mutation	audit_as(...) → save(...) or update(...)	Business audit description for the persisted graph.	Event completeness, transaction timing, sink failure behavior, masking, and durability.
Runtime SQL/audit/tool output	Generated-workspace environment configuration.	Selectable detail, filtering, and sink choice.	Subscriber wiring, output destination permissions, reload behavior, and performance cost.
Rust tracing	Application-installed tracing subscriber.	Runtime spans/events visible to the configured subscriber.	Field schema and export behavior for the selected subscriber/APM stack.
Database observability	Provider/driver/database logging pipeline.	Potential correlation with executed statements.	Whether comments survive preparation, normalization, proxies, server logging, and aggregation.

Intent metadata is operational evidence, not authorization. Tenant and permission constraints still belong in application policy and must be tested on every data-access path.

Current Generated-Workspace Controls

Newly generated Rust applications use the teaql-tool-core configuration path:

• TEAQL_AUDIT controls entity/audit detail;
• TEAQL_SQL controls SQL detail;
• TEAQL_SQL_TABLES restricts SQL output to named generated tables;
• TEAQL_TOOL and TEAQL_TOOL_FOCUS control context-tool output;
• TEAQL_SINK selects _stdout, _file, or _both;
• TEAQL_SCHEMA selects the parsed schema mode.

For example, a temporary diagnostic run can request full SQL details for one generated table:

TEAQL_SQL=_full TEAQL_SQL_TABLES=task TEAQL_SINK=_stdout cargo run

Use the exact generated table name. The current parser rejects an unknown table, focused tool module, or misspelled variable in its protected prefixes.

The older TEAQL_AUDIT_LOG, TEAQL_SQL_LOG, TEAQL_TOOL_LOG, and TEAQL_LOG_ENDPOINT names belong to a separate formatter compatibility layer; they are not aliases for the generated-workspace settings. Do not mix the two tables. See Environment Variables for accepted values, defaults, precedence, and validation behavior.

Application Tracing

Install a tracing subscriber in the application before expecting Rust spans or events to be visible:

tracing_subscriber::fmt::init();

The subscriber and TeaQL audit configuration are related observability surfaces, not the same mechanism. Verify which fields the generated/runtime version emits and which fields the subscriber exports.

For async stalls, use the application's Tokio instrumentation and the Concurrency and Deadlocks guide. Do not infer a database lock from a suspended Rust task without checking both runtime and database evidence.

Database Visibility Is Provider-Specific

Do not assume a query comment reaches a database log merely because it appears in source or application output. For every provider and environment, test:

1. the exact TeaQL provider, database, and driver versions;
2. prepared and unprepared query paths;
3. connection pools, proxies, gateways, and statement normalization;
4. slow-query/general logs and database performance views;
5. comment retention and truncation;
6. parameter and sensitive-value handling;
7. aggregation/cardinality effects in the monitoring system;
8. the overhead of the selected detail level under representative load.

PostgreSQL, MySQL, and SQLite have different logging surfaces. The current documentation has not retained a PostgreSQL/MySQL run proving TeaQL intent comments in server logs, and SQLite has no standalone database server log. Treat database-specific commands as deployment runbooks only after the selected combination passes this matrix.

Incident Workflow

When a slow query, unexpected mutation, or missing audit record appears:

1. Capture the application request/trace identifier and time window.
2. Record TeaQL runtime/provider/database and generated-workspace versions.
3. Confirm the handwritten request uses comment → purpose → execution, or the mutation uses audit_as before persistence.
4. Inspect application tracing, TeaQL SQL/audit output, provider logs, and the configured sink as separate evidence sources.
5. Compare the generated request and repository/provider path without editing generated code.
6. Reproduce with the smallest safe logging scope and a disposable dataset.
7. Restore normal logging after capture and retain a redacted incident record.

If application output contains the intent but the database view does not, test the driver/proxy/server pipeline. If neither contains it, inspect request construction and subscriber/sink initialization first.

Data-Safety Rules

• Do not enable full payload output until masking, authorization, retention, access, and deletion have been reviewed.
• Treat SQL, parameters, tool URLs, request bodies, user identity, and local paths as potentially sensitive.
• Use table and module filters to limit incident collection.
• Do not publish raw logs as documentation evidence without redaction.
• Do not treat TEAQL_SCHEMA=_dryrun as non-mutating: the currently generated runtime calls ensure_schema() for every parsed schema mode.
• Do not claim an audit record is durable until sink delivery, transaction timing, retries, failure behavior, and storage controls have been tested.

Verification Checklist

• Exact runtime, provider, database, and subscriber versions are recorded.
• Query comment and purpose appear at the intended application boundary.
• Mutation audit_as appears before persistence.
• Current generated-workspace variables, not formatter aliases, configure the run.
• Application logs and database/APM visibility are checked independently.
• Sensitive fields and payloads are redacted in every enabled sink.
• Logging overhead and failure behavior are tested.
• Evidence is retained with timestamps, commands, and expected/actual output.

For verified configuration details, use Environment Variables. For output shapes and module examples, use Audit Log Reference. For missing spans or events, use Observability and Tracing.