You deployed your agent to production. Users are interacting with it. Things are mostly working. Then a customer reports that the agent gave a wrong answer -- three days ago. What happened? What data did the agent see? What decisions did it make? Without structured, searchable logs, you are debugging in the dark.
FireFoundry's Log Proxy Service is the observability layer for agent workloads. It captures structured log records from every agent in your platform, correlates them to sessions and request chains, and makes them searchable. On Enterprise tiers, it adds PII redaction and encrypted storage for compliance-sensitive environments. This article explains how the Log Proxy works and why structured observability is non-negotiable for production AI.
Why Agent Logging Is Different
Traditional application logging is straightforward: your service writes log lines, they go to a log aggregator, and someone reads them when something breaks. Agent logging is harder for three reasons.
Agents make decisions. A web server processes requests deterministically. An agent interprets input, reasons about it, and chooses actions. When an agent makes a bad decision, you need to understand why -- what context it had, what tools it called, what the LLM returned. A log line that says "processed request" tells you nothing useful.
Agents span sessions. A single agent interaction might involve multiple tool calls, entity lookups, LLM invocations, and external API calls -- all within one session. If your logs are not correlated by session, reconstructing what happened during a specific interaction requires manual timestamp matching across multiple log streams.
Agents handle sensitive data. An agent processing customer records, medical documents, or financial data will inevitably log some of that data. Without automatic PII redaction, your log storage becomes a compliance liability. The agent developer should not have to think about this -- it should be handled at the infrastructure level.
How the Log Proxy Works
The Log Proxy sits between your agents and log storage. Agents write log entries through the SDK or MCP tools. The Log Proxy receives each record, attaches session and agent metadata, buffers entries for efficient writes, and stores them in a searchable index.
Structured Records, Not Text Lines
Every log record is a structured JSON object with standard fields: log level (DEBUG, INFO, WARN, ERROR), timestamp, session ID, agent ID, message, and arbitrary metadata. This structure makes logs queryable. You can filter by level, search by session, and aggregate by agent -- operations that are impossible with unstructured text logs.
// Agent writes a structured log entry
await logger.info('Document extraction completed', {
documentId: doc.id,
extractedFields: 12,
confidence: 0.94,
durationMs: 2340,
});
await logger.warn('Entity match below threshold', {
entityType: 'CustomerEntity',
matchScore: 0.61,
threshold: 0.75,
query: searchTerm,
});The Log Proxy client is separate from the Agent SDK. Agents can also write logs through MCP tools without any SDK dependency.
The metadata field is arbitrary -- put whatever context is useful for debugging. Document IDs, confidence scores, durations, entity types, tool names. When you are investigating an issue at 2 AM, this context is the difference between "something went wrong" and "the entity matcher returned a 0.61 confidence score when the threshold was 0.75, for query X against the CustomerEntity type."
Session Correlation
Every log record is tagged with a session ID. When you investigate an issue, you query all logs for that session and get the complete execution trace: what the agent did, in what order, with what results. No manual timestamp matching. No grepping through unrelated logs.
Session correlation extends to request chains. If an agent session triggers a tool call that invokes another service, the correlation ID follows the request. You can trace a user interaction from the initial message through every agent action, tool invocation, and service call that resulted.
// Search logs for a specific session
const logs = await logger.search({
sessionId: 'session-abc123',
level: 'WARN',
from: new Date('2026-03-01'),
to: new Date('2026-03-02'),
limit: 100,
});
// Each record includes full context
for (const entry of logs.records) {
console.log(
`[${entry.level}] ${entry.timestamp} - ${entry.message}`,
entry.metadata
);
}Log Levels and Verbosity Control
The Log Proxy supports four levels: DEBUG, INFO, WARN, and ERROR. Verbosity is configurable per agent or per session. In development, you might run with DEBUG to capture everything. In production, INFO and above keeps storage manageable while preserving the records you need for incident investigation.
This per-agent configurability matters when you have dozens of agents running in the same environment. A stable, well-tested agent might only need WARN and above. A newly deployed agent in its first week of production might need DEBUG temporarily. You control this at the platform level without changing agent code.
Enterprise Observability
PII Redaction
Enterprise deployments need to ensure that log storage does not become a data protection liability. The Log Proxy supports configurable redaction rules that scrub sensitive data from log records before storage. Email addresses, phone numbers, social security numbers, and custom patterns are automatically redacted at the infrastructure level.
This happens transparently. The agent developer writes normal log entries with whatever context is useful for debugging. The Log Proxy applies redaction rules before persisting the record. The stored log contains the structure and context needed for debugging, but sensitive values are replaced with redacted markers.
Encrypted Storage
For regulated industries, the Enterprise tier adds encrypted log storage with customer-controlled key rotation. Log records are encrypted at rest, and access is governed by the platform's RBAC system. This satisfies audit requirements for financial services, healthcare, and other compliance-sensitive environments without requiring any changes to agent code.
Retention Policies
Log retention is configurable by tier. Starter environments retain logs for 7 days -- enough for active debugging. Pro environments extend to 30 days for trend analysis and incident investigation. Enterprise environments have configurable retention with automatic expiry, supporting compliance policies that require specific retention windows.
Real-World Debugging Patterns
Incident Investigation
A customer reports that an agent gave an incorrect response last Tuesday. You search for the customer's session ID, pull the complete log trace, and see every step the agent took: the context it assembled, the LLM calls it made, the tools it invoked, and the response it generated. You can pinpoint exactly where the reasoning went wrong -- was it bad context? A hallucination? A tool failure? -- without guessing.
Performance Monitoring
Structured metadata enables performance analysis that is impossible with text logs. Filter for all log entries where durationMs exceeds a threshold. Aggregate tool call durations by agent type. Identify sessions with unusually high error rates. These patterns emerge from structured data, not from pattern-matching text strings.
Compliance Auditing
When a regulator asks "prove that your agent system did not leak customer data into its logs," you point to the PII redaction rules and the encrypted storage. When they ask for an audit trail of agent actions on a specific date, you export the log records with full session correlation. The Log Proxy turns compliance from a manual, expensive process into a query.
Getting Started
The Log Proxy is available on all FireFoundry tiers. Structured log capture, session correlation, and log search are included in every plan. PII redaction and encrypted storage are available on Enterprise. To start using it:
- Read the Log Proxy Service documentation for API reference and configuration options.
- Explore the developer hub for guides on integrating structured logging into your agent bundles.
- See the Notification Service and Entity Service to understand how logs integrate with the broader platform observability stack.
Production AI systems are only as trustworthy as their observability. If you cannot explain what an agent did and why, you cannot trust it with real work. The Log Proxy gives you that explanation -- structured, searchable, and correlated -- without requiring agent developers to become logging infrastructure experts. Write logs. The platform handles the rest.