Data Models

This document covers the core data structures used to represent monitored entries throughout their lifecycle in Telescope. These models handle entry creation during recording, storage transformation, and retrieval for display in the web interface.

For information about how entries are persisted to storage, see Database Schema. For details on how watchers create entries, see Watchers System.

Overview

Telescope uses two primary data model classes to represent entries at different stages of their lifecycle:

Model	Purpose	Direction	File
IncomingEntry	Represents entries being recorded by watchers before storage	Watchers → Storage	src/IncomingEntry.php13-287
EntryResult	Represents entries retrieved from storage for API/UI display	Storage → API/UI	src/EntryResult.php11-80

Sources: src/IncomingEntry.php src/EntryResult.php

IncomingEntry Structure

Core Properties

The IncomingEntry class serves as the data container for all monitored events as they flow from watchers to storage. Each instance represents a single recorded event with standardized metadata.

Property	Type	Description	Set At
uuid	string	Unique identifier for the entry	Construction src/IncomingEntry.php18-60
batchId	?string	Groups related entries (e.g., all entries in one request)	Via batchId() method src/IncomingEntry.php23-85
type	?string	Entry type constant from EntryType class	Via type() method src/IncomingEntry.php28-95
familyHash	?string	Hash for grouping similar entries (e.g., same SQL query)	Via withFamilyHash() method src/IncomingEntry.php33-105
user	mixed	Currently authenticated user object	Via user() method src/IncomingEntry.php38-125
content	array|string	Entry-specific data payload	Construction src/IncomingEntry.php43-64
tags	array	Searchable tags for filtering	Via tags() method src/IncomingEntry.php48-135
recordedAt	DateTimeInterface	Timestamp when entry was created	Construction src/IncomingEntry.php53-62

Sources: src/IncomingEntry.php13-67

Builder Pattern Implementation

The IncomingEntry class uses a fluent builder pattern, allowing watchers to construct entries incrementally. All setter methods return $this for method chaining.

Construction Example from CommandWatcher:

Builder Methods:

Method	Parameters	Purpose	Returns
make()	mixed ...$arguments	Static factory constructor	IncomingEntry src/IncomingEntry.php72-75
batchId()	string $batchId	Assigns batch identifier	$this src/IncomingEntry.php80-85
type()	string $type	Sets entry type (e.g., EntryType::REQUEST)	$this src/IncomingEntry.php90-95
withFamilyHash()	?string $familyHash	Sets family grouping hash	$this src/IncomingEntry.php100-105
user()	Authenticatable $user	Attaches authenticated user with auto-tagging	$this src/IncomingEntry.php110-125
tags()	array $tags	Merges additional tags	$this src/IncomingEntry.php130-135

The user() method performs three operations: sets the $user property, merges user data into content, and automatically adds an Auth:{id} tag src/IncomingEntry.php110-125

Sources: src/IncomingEntry.php72-135 src/Watchers/CommandWatcher.php35-40

Type Classification Methods

The class provides type-checking predicates used throughout the system for conditional logic and filtering.

Type Predicate Methods:

Method	Entry Type Checked	Additional Logic	Line Reference
isRequest()	EntryType::REQUEST	None	src/IncomingEntry.php154-157
isFailedRequest()	EntryType::REQUEST	Response status >= 500	src/IncomingEntry.php162-166
isQuery()	EntryType::QUERY	None	src/IncomingEntry.php171-174
isSlowQuery()	EntryType::QUERY	content['slow'] flag set	src/IncomingEntry.php179-182
isEvent()	EntryType::EVENT	None	src/IncomingEntry.php187-190
isCache()	EntryType::CACHE	None	src/IncomingEntry.php195-198
isGate()	EntryType::GATE	None	src/IncomingEntry.php203-206
isFailedJob()	EntryType::JOB	content['status'] === 'failed'	src/IncomingEntry.php211-215
isLog()	EntryType::LOG	None	src/IncomingEntry.php244-247
isScheduledTask()	EntryType::SCHEDULED_TASK	None	src/IncomingEntry.php252-255
isClientRequest()	EntryType::CLIENT_REQUEST	None	src/IncomingEntry.php260-263

Methods isReportableException(), isException(), and isDump() are defined but return false src/IncomingEntry.php220-239 likely placeholders for future implementation.

Sources: src/IncomingEntry.php154-263

Tag Management and Monitoring

The entry tracks tags for filtering and includes monitoring detection capability:

Tag Operations:

• Merge Tags: tags(array $tags) merges new tags with existing ones, maintaining uniqueness via array_unique() src/IncomingEntry.php130-135
• Auto-tagging: The user() method automatically adds Auth:{userId} tags src/IncomingEntry.php122
• Hostname Tag: Originally designed to tag with hostname, currently commented out src/IncomingEntry.php66

Monitoring Check: The hasMonitoredTag() method queries the repository to determine if any of the entry's tags are being actively monitored src/IncomingEntry.php140-149:

Sources: src/IncomingEntry.php122-149

Storage Transformation

The toArray() method serializes the entry for database persistence src/IncomingEntry.php276-286:

Transformation Details:

• Property names are converted to snake_case for database columns
• recordedAt DateTime is formatted as string via toDateTimeString()
• content array includes hostname from construction src/IncomingEntry.php64
• Tags are stored separately in a junction table (not included in this array)

Sources: src/IncomingEntry.php276-286

EntryResult Structure

Core Properties

The EntryResult class represents entries retrieved from storage, formatted for JSON serialization and API responses.

Constructor Parameters src/EntryResult.php30-40:

Parameter	Type	Description
id	mixed	Database primary key
sequence	mixed	Entry sequence number
batchId	string	Batch identifier
type	string	Entry type constant
familyHash	?string	Family grouping hash
content	array	Entry data payload
createdAt	CarbonInterface	Timestamp
tags	array	Associated tags (private)

Sources: src/EntryResult.php11-40

Avatar Generation

The generateAvatar() method creates a Gravatar-style avatar URL for the entry's user src/EntryResult.php45-54:

Implementation Details:

1. Extracts user data from content['user'], defaulting to empty array if not an array src/EntryResult.php47-49
2. Calls Avatar::url() to generate avatar URL
3. Stores result in protected $avatar property src/EntryResult.php51
4. Returns $this for method chaining

Sources: src/EntryResult.php45-54

JSON Serialization

The jsonSerialize() method implements the JsonSerializable interface, providing structured output for API responses src/EntryResult.php59-79:

Serialization Process:

1. Creates a Collection with all base properties src/EntryResult.php61-70
2. Conditionally merges avatar URL into content.user.avatar if set using when() src/EntryResult.php70-78
3. Returns array representation via all() src/EntryResult.php78

Output Structure:

Sources: src/EntryResult.php59-79

Data Lifecycle Flow

Key Transformation Points:

1. Creation: Watchers instantiate IncomingEntry with event-specific content
2. Enrichment: Builder methods add metadata (batch ID, type, user, tags)
3. Classification: Type predicates enable conditional processing
4. Serialization: toArray() converts to database-compatible format
5. Persistence: Repository stores entry and tags
6. Retrieval: Query methods reconstruct entries as EntryResult instances
7. Presentation: JSON serialization prepares data for web interface

Sources: src/IncomingEntry.php src/EntryResult.php src/Watchers/CommandWatcher.php35-40