AgentSessionManager.AuditLogger (AgentSessionManager v0.8.0)

Audit log persistence for observability and compliance.

This module provides functions to persist audit events to the SessionStore in append-only order. Events are immutable once stored and provide a complete audit trail of all run lifecycle events.

Event Types

:run_started - Logged when a run begins
:run_completed - Logged when a run completes successfully
:run_failed - Logged when a run fails
:error_occurred - Logged when an error occurs during execution
:token_usage_updated - Logged when usage metrics are reported

Configuration

Audit logging is enabled by default. Disable it via application config (global baseline) or at runtime per-process:

# Global baseline (config.exs)
config :agent_session_manager, audit_logging_enabled: false

# Per-process override (safe in concurrent tests)
AgentSessionManager.AuditLogger.set_enabled(false)

Usage

alias AgentSessionManager.AuditLogger

# Log lifecycle events
AuditLogger.log_run_started(store, run, session)
AuditLogger.log_run_completed(store, run, session, result)
AuditLogger.log_run_failed(store, run, session, error)

# Query audit log
{:ok, events} = AuditLogger.get_audit_log(store, session_id)

Telemetry Integration

The AuditLogger can automatically log events from telemetry:

AuditLogger.attach_telemetry_handlers(store)

This will create audit log entries for all telemetry events emitted by the Telemetry module.

Summary

Functions

attach_telemetry_handlers(store)

Attaches telemetry handlers to automatically log audit events.

detach_telemetry_handlers()

Detaches the telemetry handlers.

enabled?()

Returns whether audit logging is enabled.

get_audit_log(store, session_id, opts \\ [])

Retrieves audit events for a session.

log_error(store, run, session, error)

Logs an error_occurred audit event.

log_run_completed(store, run, session, result)

Logs a run_completed audit event.

log_run_failed(store, run, session, error)

Logs a run_failed audit event.

log_run_started(store, run, session)

Logs a run_started audit event.

log_usage_metrics(store, session, metrics, opts \\ [])

Logs a token_usage_updated audit event.

set_enabled(enabled)

Enables or disables audit logging for the current process.

Functions

attach_telemetry_handlers(store)

@spec attach_telemetry_handlers(AgentSessionManager.Ports.SessionStore.store()) :: :ok

Attaches telemetry handlers to automatically log audit events.

When attached, telemetry events emitted by the Telemetry module will automatically create corresponding audit log entries.

Parameters

store - The session store instance to use for logging

detach_telemetry_handlers()

@spec detach_telemetry_handlers() :: :ok

Detaches the telemetry handlers.

enabled?()

@spec enabled?() :: boolean()

Returns whether audit logging is enabled.

Checks the process-local override first, then Application environment, then defaults to true. See AgentSessionManager.Config for details.

get_audit_log(store, session_id, opts \\ [])

@spec get_audit_log(
  AgentSessionManager.Ports.SessionStore.store(),
  String.t(),
  keyword()
) ::
  {:ok, [AgentSessionManager.Core.Event.t()]}

Retrieves audit events for a session.

Parameters

store - The session store instance
session_id - The session ID to query
opts - Optional filters:
- :run_id - Filter by run ID
- :type - Filter by event type
- :since - Events after this timestamp

Returns

{:ok, [Event.t()]} - List of events in append order

log_error(store, run, session, error)

@spec log_error(
  AgentSessionManager.Ports.SessionStore.store(),
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  map()
) :: :ok

Logs an error_occurred audit event.

Parameters

store - The session store instance
run - The run where the error occurred
session - The session containing the run
error - The error details

log_run_completed(store, run, session, result)

@spec log_run_completed(
  AgentSessionManager.Ports.SessionStore.store(),
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  map()
) :: :ok

Logs a run_completed audit event.

Parameters

store - The session store instance
run - The run that completed
session - The session containing the run
result - The result of the run including token_usage

log_run_failed(store, run, session, error)

@spec log_run_failed(
  AgentSessionManager.Ports.SessionStore.store(),
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  map()
) :: :ok

Logs a run_failed audit event.

Parameters

store - The session store instance
run - The run that failed
session - The session containing the run
error - The error that caused the failure

log_run_started(store, run, session)

@spec log_run_started(
  AgentSessionManager.Ports.SessionStore.store(),
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t()
) :: :ok

Logs a run_started audit event.

Parameters

store - The session store instance
run - The run that started
session - The session containing the run

log_usage_metrics(store, session, metrics, opts \\ [])

@spec log_usage_metrics(
  AgentSessionManager.Ports.SessionStore.store(),
  AgentSessionManager.Core.Session.t(),
  map(),
  keyword()
) :: :ok

Logs a token_usage_updated audit event.

Parameters

store - The session store instance
session - The session for the usage metrics
metrics - The usage metrics map
opts - Optional keyword list:
- :run_id - The run ID to associate with the metrics

set_enabled(enabled)

@spec set_enabled(boolean()) :: :ok

Enables or disables audit logging for the current process.

The override is process-local and automatically cleaned up when the process exits. This is safe to call in concurrent tests.