Logging & Observability
Relevant source files
The following files were used as context for generating this wiki page:
- apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt
- apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt
- AGENT_NOTES.md
- apps/web/src/lib/api/types.ts
- apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt
- apps/api/src/test/kotlin/com/briefy/api/application/briefing/BriefingGenerationServiceTest.kt
Logging and observability within Briefy are centered on tracking complex asynchronous workflows, particularly around AI execution and content processing. The system employs a combination of structured event logging, state machine tracking for long-running jobs, and detailed metrics for tool usage and AI provider performance. This ensures that developers can trace a request from initial ingestion through multi-persona synthesis.
Key observability components include execution run summaries, subagent tool statistics, and error tracking for transient failures during AI calls or external tool execution.
AI Execution & Subagent Observability
The AI subagent system provides deep visibility into the "thought process" of personas. Each subagent run tracks its attempts, tool calls, and curated outputs.
Tool Call Tracking
When an AiSubagentExecutionRunner operates, it records every tool interaction (such as web search or page fetching). This includes the duration of the call and its success status, which is then serialized into toolStatsJson.
The diagram shows how tool execution metadata is captured within the subagent loop and persisted in the final result.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:37-75
Execution State Machine
Observability is integrated into the briefing state machine. Transitions are validated and each accepted transition persists an idempotent event.
| Component | Description |
|---|---|
briefing_run | High-level status of a briefing generation attempt. |
subagent_run | Metrics for individual persona executions, including toolStats. |
run_events | Idempotent event log of all state transitions. |
failureCode | Standardized error codes (e.g., runner_error, timeout, http_429). |
Sources: AGENT_NOTES.md:124-129, apps/web/src/lib/api/types.ts:250-320
AI Provider Metrics
The system monitors interactions with LLM providers (e.g., Google GenAI, ZhipuAI, Minimax). This is critical for identifying platform-specific issues or transient network errors.
- UseCase Tracking: AI calls are tagged with
useCaseidentifiers likesubagent_execution_personaKey,synthesis_execution, ortopic_extraction. - Error Categorization: Errors are analyzed to determine if they are transient (retryable) or permanent.
The sequence shows the error handling and retry determination logic used for AI observability.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:190-205, apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt:55-75
Distributed Tracing & Events
Briefy utilizes OpenTelemetry for distributed tracing (OTLP) and Spring's internal event system for triggering downstream observability tasks.
OpenTelemetry Configuration
Spring OTLP exporters for Langfuse are configured as dedicated beans. This prevents initialization order issues where spans might be dropped if produced before the exporter is fully initialized.
Sources: AGENT_NOTES.md:118-121
Functional Event Triggers
Key observability events are emitted upon successful processing of content:
SourceContentFinalizedEvent: The canonical trigger for finalized source text, used by downstream services to begin further analysis or logging.ApplicationEventPublisher: Used in services likeSourceServiceto broadcast state changes.
Sources: AGENT_NOTES.md:122-125, apps/api/src/test/kotlin/com/briefy/api/application/briefing/BriefingGenerationServiceTest.kt:36-40
Frontend Observability Interfaces
The frontend provides real-time feedback to users regarding the observability of their requests.
Polling & Status UI
Clients use executionRunId surfaced in briefing responses to poll the /api/briefings/runs/{id} endpoint. This allows the UI to show:
- Current execution status (Queued, Running, Succeeded, Failed).
- Progress of individual subagent personas.
- Error messages with retry options for failed formatting or AI generation.
Sources: AGENT_NOTES.md:158-161, apps/web/src/lib/api/types.ts:322-335
Structured Error Responses
The API returns a standardized BriefingErrorResponse for failed runs, enabling precise UI messaging.
| Field | Type | Description |
|---|---|---|
code | String | Machine-readable error identifier. |
message | String | Human-readable description. |
retryable | Boolean | Indicates if the user should be prompted to retry. |
details | Map | Key-value pairs providing extra context for debugging. |
Sources: apps/web/src/lib/api/types.ts:238-243
Conclusion
The logging and observability framework in Briefy provides a structured way to monitor complex AI workflows. By combining state machine persistence with granular tool-call logging and standardized error reporting, the system allows for effective debugging and monitoring of multi-stage synthesis and extraction processes.