Probe Result Data Files and Structure

Probe data files contain the detailed results of executed health checks. Each file represents a single execution cycle and includes results for all probes configured in the project.

File Location

storage/app/private/uplinkr/<project-name>/probes/<url-name>@<timestamp>.json

File Naming Convention

Probe files follow this naming pattern:

<sanitized-url>@<timestamp>.json

Examples:

uplinkr_dev@2026-01-30-12.json
api_test_uplinkr_dev@2026-01-30-21.json
health_check_example_com@2026-02-01-08.json

URL Sanitization

URLs are sanitized for filesystem compatibility:

• Protocol removed (https:// → “)
• Dots replaced with underscores (example.com → example_com)
• Slashes replaced with underscores (/api/health → _api_health)
• Special characters removed or replaced

Timestamp Format

Format: YYYY-MM-DD-HH (hourly granularity)

Example: 2026-01-30-12 = January 30, 2026 at 12:00

File Structure

Each probe file contains an array of probe results:

[
    {
        "status_header": 200,
        "headers": {...},
        "probe_id": "uuid",
        "probe_message": {...},
        "probe_status": "healthy",
        "time_to_load": 0.123,
        "executed": "2026-01-30T12:00:00.971032Z",
        "probe_tls_expiration_date": "2027-01-01T00:00:00+00:00",
        "settings": {...}
    },
    ...
]

Field Reference

Top-Level Fields

Field	Type	Description
status_header	integer	HTTP status code (200, 404, 500, etc.)
headers	object	Response headers from the probe request
probe_id	string	Unique identifier (UUID) for this probe execution
probe_message	object	Localized message and timing information
probe_status	string	Health status: healthy, unreachable, slow, failed
time_to_load	float	Response time in seconds
executed	string	ISO 8601 timestamp of execution
probe_tls_expiration_date	string|null	TLS certificate expiration date for HTTPS probes (if available)
settings	object	Probe configuration used for this check

Headers Object

Response headers are stored as key-value pairs with arrays for values:

{
    "Content-Type": ["application/json"],
    "Content-Length": ["1234"],
    "X-Custom-Header": ["value1", "value2"]
}

Probe Message Object

{
    "lang_key": "messages.probe_healthy",
    "duration_ms": 123.45,
    "duration_s": 0.12
}

Field	Type	Description
lang_key	string	Translation key for status message
duration_ms	float	Response time in milliseconds
duration_s	float	Response time in seconds

Settings Object

Contains the probe configuration that was used:

{
    "url": "https://example.com/health",
    "project": "my-project",
    "method": "GET",
    "headers": [],
    "body": null
}

Legacy note: Older entries may still contain header; Uplinkr normalizes this to headers for compatibility.

Probe Status Values

Status	Description
healthy	Response received with expected status code
unreachable	Target could not be reached (DNS, network, timeout)
slow	Response received but exceeded latency threshold
failed	Received response but with error status code

Example: Complete Probe Result

{
    "status_header": 404,
    "headers": {
        "Content-Type": ["text/html"],
        "Content-Length": ["1271"],
        "Connection": ["keep-alive"],
        "Date": ["Fri, 30 Jan 2026 12:00:00 GMT"],
        "Server": ["Apache"]
    },
    "probe_id": "0e910eb9-73ca-4981-af44-df6d99050908",
    "probe_message": {
        "lang_key": "messages.probe_unreachable",
        "duration_ms": 178.73,
        "duration_s": 0.18
    },
    "probe_status": "unreachable",
    "time_to_load": 0.1787271499633789,
    "executed": "2026-01-30T12:00:00.971032Z",
    "settings": {
        "url": "https://uplinkr.dev/health",
        "project": "uplinkr-dev-api-test",
        "method": "GET",
        "headers": [],
        "body": null
    }
}

File Size Considerations

Growth Patterns

Probe files can grow large depending on:

• Number of probes per project
• Response header sizes
• Execution frequency

Typical sizes:

• Small project (5 probes): ~50-100 KB per file
• Medium project (20 probes): ~200-500 KB per file
• Large project (50+ probes): 1+ MB per file

Performance Impact

Large probe files may:

• Slow down file reads when analyzing historical data
• Consume significant disk space over time
• Impact backup durations

Recommendations:

• Archive old probe data periodically
• Monitor disk usage in high-frequency scenarios
• Consider retention policies for probe data

Data Retention

Manual Cleanup

Remove old probe files:

# Remove probe files older than 30 days
find storage/app/private/uplinkr/*/probes/ -name "*.json" -mtime +30 -delete

Archiving

Use Uplinkr’s archiving feature:

php artisan uplinkr:project:archive my-project

This copies the project directory (including probe data) to the archived/ folder.

Use Cases

Historical Analysis

Probe data enables:

• Trend analysis over time
• Incident investigation
• Performance baseline establishment
• SLA compliance verification

Debugging

When investigating issues:

1. Locate the timestamp of the incident
2. Find corresponding probe file: <url>@<timestamp>.json
3. Examine headers, status_header, and time_to_load
4. Check probe_message for detailed error information

Custom Reporting

Parse probe files for custom reports:

# Count failed probes in the last day
find storage/app/private/uplinkr/my-project/probes/ -name "*.json" -mtime -1 \
    -exec jq '[.[] | select(.probe_status == "failed")] | length' {} \;

Related Topics

• Storage Structure - Overall storage architecture
• Project Files - Project configuration
• Alerts & State - How probe data triggers alerts
• Archiving - Long-term data management