Database Schema

Purpose and Scope

This document details Telescope's three-table database schema used to persist monitoring entries, their tags, and monitoring configuration. The schema is defined in the migration file and provides the foundation for Telescope's data storage layer. For information about the repository pattern and how this schema is accessed programmatically, see Repository Pattern.

Schema Overview

Telescope uses a three-table relational schema to store application monitoring data:

Table	Purpose	Key Characteristics
telescope_entries	Stores individual monitoring entries (requests, queries, jobs, etc.)	Main data table with JSON content storage
telescope_entries_tags	Junction table linking entries to tags	Enables tag-based filtering and querying
telescope_monitoring	Stores monitoring tags for active monitoring	Simple key-value table for configuration

The schema is created via a Hypervel migration that reads the database connection from config('telescope.storage.database.connection'), allowing Telescope to use a separate database connection if needed database/migrations/2025_02_08_000000_create_telescope_entries_table.php17-18

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php1-69

---

Entity Relationship Diagram

This diagram illustrates the relationships between the three tables:

• telescope_entries is the central table containing all monitoring data
• telescope_entries_tags creates a many-to-many relationship between entries and tags
• telescope_monitoring stores tags that are being actively monitored, which can be cross-referenced with tagged entries

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php28-55

---

telescope_entries Table

The telescope_entries table is the primary storage location for all monitoring data collected by Telescope's watchers.

Column Definitions

Column	Type	Constraints	Description
sequence	bigIncrements	Primary Key	Auto-incrementing numeric identifier for ordering
uuid	uuid	Unique	Globally unique identifier for the entry
batch_id	uuid	Indexed	Groups entries from the same request/execution context
family_hash	string	Nullable, Indexed	Hash to group similar entries (e.g., same query pattern)
should_display_on_index	boolean	Default: true	Controls visibility in the main UI listing
type	string(20)	Indexed	Entry type identifier (e.g., "request", "query", "cache")
content	longText	-	JSON-encoded entry data with full details
created_at	dateTime	Nullable, Indexed	Timestamp of when the entry was recorded

Key Characteristics

UUID-based Identity: Each entry has both a sequence (for efficient ordering) and a uuid (for distributed systems and external references). The uuid column has a unique constraint database/migrations/2025_02_08_000000_create_telescope_entries_table.php38

Batch Grouping: The batch_id field groups all entries that occur within the same request or execution context. This enables viewing all monitoring data for a single request together. See Context and Batch Management for how batch IDs are generated.

Family Hashing: The family_hash field groups similar entries together (e.g., the same database query run multiple times with different parameters). This enables aggregation and deduplication in the UI.

Type Classification: The type field stores one of 18+ entry types corresponding to the different watchers (e.g., "request", "query", "exception", "job"). See Watchers System for the complete list.

JSON Content Storage: The content column stores the full entry data as JSON, allowing flexible schema-less storage of heterogeneous entry types. Each entry type has its own content structure defined by its watcher.

Display Control: The should_display_on_index flag allows certain entries to be hidden from the main listing while remaining queryable, useful for reducing noise from high-frequency events.

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php28-43

---

telescope_entries_tags Table

The telescope_entries_tags table implements a many-to-many relationship between entries and tags, enabling powerful filtering and categorization of monitoring data.

Column Definitions

Column	Type	Constraints	Description
entry_uuid	uuid	Primary Key (composite), Foreign Key	References telescope_entries.uuid
tag	string	Primary Key (composite), Indexed	Tag value (e.g., user ID, job class, endpoint)

Composite Primary Key

The table uses a composite primary key on ['entry_uuid', 'tag'] database/migrations/2025_02_08_000000_create_telescope_entries_table.php49 which:

• Ensures each entry-tag pair is unique
• Prevents duplicate tag assignments
• Provides efficient lookups in both directions

Tag Index

A separate index on the tag column database/migrations/2025_02_08_000000_create_telescope_entries_table.php50 enables fast queries like "find all entries with tag X" without scanning the composite primary key.

Tag Sources

Tags are automatically generated by watchers and can also be manually added via Telescope::tag(). Common tag patterns include:

• User IDs: App\Models\User:{id}
• Job Classes: Fully qualified class names
• Endpoints: HTTP method and URI path
• Exception Classes: Exception type names
• Custom Tags: Application-specific identifiers

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php45-51

---

telescope_monitoring Table

The telescope_monitoring table stores tags that are currently being actively monitored. This enables Telescope to apply special handling to entries with monitored tags.

Column Definitions

Column	Type	Constraints	Description
tag	string	Primary Key	The tag value being monitored

Purpose

This table serves as a simple configuration store for monitoring specific tags. When a tag appears in this table, Telescope may:

• Ensure entries with this tag are always stored, regardless of global recording settings
• Display monitored entries prominently in the UI
• Apply special retention policies to monitored entries

The table's simplicity (single string primary key) allows efficient lookups to check if a tag is being monitored.

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php53-55

---

Indexing Strategy

Telescope's indexing strategy is designed to support common query patterns in the web UI and repository operations.

Index Overview

Index Descriptions

telescope_entries Indexes:

1. UNIQUE(uuid) database/migrations/2025_02_08_000000_create_telescope_entries_table.php38

   • Enforces uniqueness of entry identifiers
   • Supports fast lookups by UUID when viewing individual entries

2. INDEX(batch_id) database/migrations/2025_02_08_000000_create_telescope_entries_table.php39

   • Enables efficient queries for all entries within a single request/context
   • Critical for the "View All Entries in Batch" feature in the UI

3. INDEX(family_hash) database/migrations/2025_02_08_000000_create_telescope_entries_table.php40

   • Groups similar entries together for aggregation
   • Used by QueryWatcher to identify duplicate query patterns

4. INDEX(created_at) database/migrations/2025_02_08_000000_create_telescope_entries_table.php41

   • Supports time-range queries for pruning old entries
   • Enables efficient date-based filtering in the UI

5. INDEX(type, should_display_on_index) database/migrations/2025_02_08_000000_create_telescope_entries_table.php42

   • Composite index optimizes the most common query: "show all entries of type X that should be displayed"
   • Filters out hidden entries without table scans

telescope_entries_tags Indexes:

1. PRIMARY(entry_uuid, tag) database/migrations/2025_02_08_000000_create_telescope_entries_table.php49

   • Prevents duplicate tag assignments
   • Supports queries like "all tags for entry Y"

2. INDEX(tag) database/migrations/2025_02_08_000000_create_telescope_entries_table.php50

   • Separate index enables "all entries with tag X" queries
   • Critical for user-based filtering and monitoring features

telescope_monitoring Indexes:

1. PRIMARY(tag) database/migrations/2025_02_08_000000_create_telescope_entries_table.php54
   • Fast lookups to check if a tag is being monitored
   • Prevents duplicate monitoring configurations

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php38-50

---

Data Flow and Storage Schema Relationship

This diagram shows how watchers create entries that flow through Telescope and are ultimately persisted to the database schema:

1. Entry Creation: Watchers create IncomingEntry objects with type-specific content
2. Enrichment: Telescope adds batch_id, tags, user information, and family_hash
3. Storage: The repository inserts into telescope_entries with all fields populated
4. Tag Storage: Each tag creates a row in telescope_entries_tags
5. Monitoring Check: Tags are checked against telescope_monitoring for special handling

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php28-55

---

Migration Configuration

The migration provides flexibility in database connection configuration:

This allows Telescope to:

• Use a separate database connection from the main application
• Connect to a different database entirely
• Use a read replica for queries and a primary for writes (via connection configuration)

The connection is retrieved from config('telescope.storage.database.connection') database/migrations/2025_02_08_000000_create_telescope_entries_table.php17-18 falling back to the default application connection if not specified. See Core Settings for configuration details.

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php14-19

---

Schema Management Operations

Table Creation Order

Tables are created in dependency order database/migrations/2025_02_08_000000_create_telescope_entries_table.php28-55:

1. telescope_entries (no dependencies)
2. telescope_entries_tags (references entries)
3. telescope_monitoring (independent)

Table Deletion Order

Tables are dropped in reverse order to avoid foreign key constraint violations database/migrations/2025_02_08_000000_create_telescope_entries_table.php65-67:

1. telescope_entries_tags (has foreign key reference)
2. telescope_entries (parent table)
3. telescope_monitoring (independent)

Data Types and Compatibility

The migration uses Hyperf's database schema builder, which provides cross-database compatibility:

• uuid(): Compatible with PostgreSQL native UUID, MySQL CHAR(36), SQLite TEXT
• longText(): Suitable for large JSON payloads (4GB in MySQL, unlimited in PostgreSQL)
• dateTime(): Stores timestamps without timezone information

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php24-68