Skip to content

Section 34: Logging, Auditing, and Observability

TECHSPEC-34 — Section 34 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Observability Philosophy

Programs must expose enough reliable information to understand what they did, what happened, and where failures occurred.

Logging and observability must not become substitutes for verification.

A log entry claiming that an operation succeeded is not proof that the intended result was achieved.

The language must distinguish recorded events, observed outcomes, and independently verified properties.

2. Logging Levels

The standard library must support structured logging levels:

  • TRACE: Detailed execution information.
  • DEBUG: Information useful during development.
  • INFO: Significant application events.
  • WARN: Unexpected conditions that did not prevent continued execution.
  • ERROR: Operations that failed.
  • FATAL: Failures that prevent continued execution.

Rules: - Logging levels must have consistent meanings. - Production logging configuration must be explicit. - Logging must not silently suppress required security or audit events. - Log filtering must not change program behavior.

3. Structured Log Records

Logs must use structured records rather than relying exclusively on free-form text.

A log record should support:

  • Timestamp.
  • Severity.
  • Event identifier.
  • Module and function.
  • Source location.
  • Execution or correlation identifier.
  • Relevant operation.
  • Outcome.
  • Associated error.
  • Verification status, where applicable.

Example:

LOG ERROR:
    EVENT: DATABASE_WRITE_FAILED
    MODULE: AccountService
    FUNCTION: updateBalance
    OPERATION: DATABASE.MODIFY
    OUTCOME: FAILED
    ERROR: ConnectionLost

The final serialization format remains a standard-library design decision.

4. Execution Tracing

The runtime should support tracing significant execution events.

Traceable events include: - Function entry and exit. - Contract evaluation. - State transitions. - Permission checks. - External operations. - Transaction boundaries. - Resource creation and release. - Task creation and completion. - Error propagation. - Verification checks.

Rules: - Traces must preserve meaningful event ordering. - Concurrent execution must identify separate tasks. - Trace completeness must be documented. - Sensitive values must not be exposed by default. - Tracing must not silently alter application semantics.

5. Security and Audit Logs

Security-sensitive operations require appropriate audit records.

Examples include: - Authentication attempts. - Authorization decisions. - Permission changes. - Sensitive data access. - Cryptographic key access. - Process execution. - Security configuration changes. - Administrative operations.

Rules: - Audit records must identify the operation and its outcome. - Sensitive credentials and secret material must never be logged. - Audit logging must declare its effects. - Audit records must have documented retention and access policies. - Tamper resistance must not be claimed unless supported by the storage and verification mechanisms.

6. Logging Side Effects

Logging is an observable side effect.

Proposed effects:

  • LOG.WRITE
  • LOG.READ
  • AUDIT.WRITE
  • TRACE.WRITE

Rules: - Functions must declare required logging and audit effects. - Logging failures must have defined handling behavior. - Logging must not silently become an unrestricted filesystem or network capability. - Audit requirements must not be disabled merely because ordinary logging is disabled. - Logging configuration must not expose secrets or personal data unintentionally.

7. Correlation and Causality

Related events must be traceable across function calls and external operations.

The runtime should support: - Execution identifiers. - Request identifiers. - Task identifiers. - Parent-child operation relationships. - Distributed trace identifiers.

Rules: - Identifiers must have defined scope and uniqueness requirements. - Concurrent operations must remain distinguishable. - Correlation must not be confused with proof of causation. - Missing trace information must be reported where completeness is required.

8. Metrics and Runtime Measurements

The standard library should support metrics such as: - Operation counts. - Failure counts. - Execution durations. - Resource consumption. - Queue sizes. - Active connections. - Task counts.

Rules: - Measurements must identify their units. - Measurement precision and collection overhead must be documented. - Metrics must distinguish observed values from estimated values. - Aggregated metrics must not conceal important failure conditions. - Runtime measurements must not be presented as formal correctness proofs.

9. Error and Diagnostic Integration

Logging, tracing, and compiler diagnostics must work together without becoming interchangeable.

Rules: - Compiler diagnostics identify problems in source or build analysis. - Runtime errors identify failures during execution. - Logs record selected application events. - Traces record execution relationships. - Verification reports identify the evidence supporting specific guarantees.

Each system must retain its own meaning.

10. Compiler and Runtime Responsibilities

The compiler and runtime must: - Provide structured logging APIs. - Enforce declared logging and audit effects. - Support execution and correlation identifiers. - Protect sensitive values. - Preserve meaningful event ordering. - Report logging and audit failures according to declared policies. - Distinguish observed events from verified properties. - Expose trace completeness and known limitations.

11. Verification Limitations

Observability cannot establish that every relevant event was captured or that recorded events are truthful.

Verification reports must distinguish: - Event generation attempted. - Event successfully recorded. - Event storage confirmed. - Record integrity established, where supported. - Trace completeness established, where supported. - Unobserved behavior and remaining assumptions.

12. Design Goal

An AI agent must be able to investigate execution without guessing what happened or treating its own log messages as proof.

The language must make failures, state transitions, permissions, and external operations observable while preserving the distinction between observation and verification.

Source file: TECHSPEC-34.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.