Structured Logging

Structured logs are emitted in a consistent, parsable data format like JSON, Protocol Buffers, or Avro. This contrasts with unstructured plain-text logs, which require complex regex for parsing.

• Key-Value Pairs: Each log entry is a set of defined fields (e.g., {"timestamp": "2024-01-15T10:30:00Z", "level": "INFO", "tool_name": "execute_sql_query", "user_id": "usr_123", "parameters": {...}}).
• Enables Automation: Systems can automatically index, query, and alert on specific fields without manual interpretation.

A predefined log schema dictates the structure, required fields, data types, and naming conventions for all entries. This ensures consistency across different services and over time.

• Core Audit Fields: A schema for tool-call auditing would mandate fields like invocation_id, agent_id, tool_name, input_parameters_hash, output_hash, status_code, duration_ms, and error_message.
• Validation: Logging libraries can validate entries against the schema at write-time, preventing malformed data from entering the audit trail.

Raw event data is augmented with contextual metadata to create a complete forensic record. This turns a simple log into an auditable event.

• Automated Metadata: The logging system automatically adds context such as a trace_id (for distributed tracing), session ID, hostname, service version, and parent process ID.
• Business Context: For tool calls, enrichment adds user roles, project identifiers, and the business justification or workflow step that triggered the call.

To serve as a trustworthy audit trail, structured logs must be immutable and tamper-evident. Once written, an entry cannot be altered or deleted.

• Append-Only Writes: Logs are written to Write-Once Read-Many (WORM) storage or systems that enforce append-only semantics.
• Cryptographic Verification: Techniques like hashing chains (e.g., Merkle Trees) or digital signatures provide proof that the log sequence has not been modified. Any alteration breaks the chain, providing non-repudiation.

Because fields are explicit and typed, structured logs can be efficiently indexed and queried along multiple dimensions simultaneously.

• Example Queries:
  • "Show all tool_name='send_email' calls by user_id='admin_45' in the last 24 hours."
  • "Find tool calls where duration_ms > 5000 and status_code != 200."
  • "Aggregate total API cost by project_id from logs containing cost_usd field."
• Integration: This enables direct integration with Security Information and Event Management (SIEM) systems and observability platforms for real-time monitoring and anomaly detection.

Structured logging is designed for high-volume, low-latency environments typical of AI agents making numerous tool calls.

• Efficient Serialization: Formats like JSON and Protobuf are fast to serialize/deserialize, minimizing the performance overhead on the application.
• Asynchronous Writing: Logs are often buffered and written asynchronously to prevent blocking the main application thread.
• Sampling & Filtering: Log levels (DEBUG, INFO, WARN, ERROR) and dynamic sampling rules (log 1% of DEBUG entries) control volume and cost without sacrificing audit-critical (ERROR, WARN) data.