Telemetry & Observability
Relevant source files
The following files were used as context for generating this wiki page:
Telemetry & Observability in Coral provides visibility into the execution of sandboxed TypeScript programs, tool interactions, and system performance. The project records every program run, allowing users to review calls made to providers and system events through the Coral UI.
Sources: README.md:27, AGENTS.md:33-35
Architectural Principles
The telemetry system follows specific durability boundaries to ensure data consistency and security.
Ownership and Propagation
- Domain Modules: These modules own the timing of signals.
- Application Bootstrap: This process owns the configuration of exporters.
- Cross-Crate Propagation: The
coral-telemetrycrate manages W3C trace propagation and export filtering. - Field Safety:
coral-telemetryensures that only safe fields are exported to external observability platforms.
Sources: AGENTS.md:33-35
Core Dependencies
The observability stack is built on OpenTelemetry (OTEL) and the Tracing framework.
| Library | Version | Purpose |
|---|---|---|
opentelemetry | 0.33.1 | Core OpenTelemetry API |
opentelemetry-otlp | 0.33.1 | OTLP exporter for traces and metrics |
tracing | 0.1.44 | Instrumentation framework for Rust |
tracing-opentelemetry | 0.34.0 | Bridge between Tracing and OTEL |
tracing-subscriber | 0.3.23 | Subscriber for collecting trace data |
Sources: Cargo.toml:80-92
Observability Data Flow
The following diagram illustrates how telemetry data flows from sandboxed execution to the user interface and external exporters.
The system separates internal activity recording (for user-facing history) from system-level telemetry (for operator monitoring).
Sources: AGENTS.md:33-35, crates/coral-mcp/src/arguments.rs:198-208
Program Observation Tools
Coral provides specific Model Context Protocol (MCP) tools that enable agents and users to observe running programs in real-time.
Tool Call Observation
exec: Starts a new program run. It allows logging diagnostics viaconsole.logand returns arun_idfor further observation.wait: Observes a specific program run. It retrieves authored emissions, logs, and the current state of the run.- Cursors: Observation is non-consumptive. Using an earlier cursor allows reading the same output again.
Sources: crates/coral-mcp/src/arguments.rs:190-210
Interaction Sequence
This sequence shows how an agent interacts with the observability features.
User-Facing Activity Events
Reef (the Coral web UI) presents telemetry data as structured activity records.
Event Categories
| Kind | Display Label | Description |
|---|---|---|
program.logged | console.<level> | Internal diagnostics from the program |
program.emitted | coral.emit | Explicit program output values |
invocation.started | Operation call started | The start of a call to a provider |
invocation.ended | Operation call ended | The completion or failure of a provider call |
run.started | Program run started | Acceptance of an exec submission |
run.ended | Program run ended | Terminal state reached (success/fail/timeout) |
Sources: apps/reef/app/views/activity/detail.test.tsx:320-370
Diagnostic Representations
Errors and failures are presented with specific diagnostic codes to facilitate debugging.
- Program Rejections: Errors thrown within the TypeScript sandbox.
- Resource Limits: Exceeding memory or value size bounds.
- Coral Failures: Errors occurring in the Coral runtime (e.g.,
operation_disabled).
Sources: apps/reef/app/views/activity/detail.test.tsx:250-280, apps/reef/app/views/activity/side-panels.stories.tsx:640-660
Troubleshooting and Logs
For desktop users, Coral maintains local logs for support and debugging.
- Log Directory: The desktop application provides a path to a logs directory (e.g., in user data folders) when the runtime fails to start or crashes.
- Process Monitoring: The system tracks the status of the
Coral runtimeandCoral web serverroles, providing specific exit codes or signals when crashes occur.
Sources: apps/desktop/src/main/local-pages.ts:24-60
Conclusion
The Telemetry & Observability system in Coral ensures that sandboxed program execution is transparent and traceable. By combining OpenTelemetry for system health with high-level activity recording for program execution, Coral provides both operators and users with the necessary evidence to monitor, debug, and audit agent behavior.