Real-Time Data Freshness Evaluation Prompt

This prompt is designed for real-time data pipeline and streaming system builders who need to programmatically monitor the timeliness of incoming data. The core job-to-be-done is generating a structured health report that flags stale sources, calculates latency percentiles, and scores the reliability of each data feed. The ideal user is an engineering lead or platform engineer responsible for data quality in event-driven architectures, where a silent stall in a Kafka topic or a delayed API response can corrupt downstream models and dashboards. You should use this prompt when you have a stream of timestamped events and need an automated, repeatable way to answer the question: 'Is our data fresh enough to trust right now?'

The prompt requires a well-defined input context: a list of data sources with their expected update frequencies, a window of recent timestamps, and a set of freshness thresholds (e.g., maximum acceptable latency in seconds). It is not a general-purpose data quality tool. Do not use this prompt for static document corpora, historical analysis, or batch ETL validation where recency is not the primary concern. It is also unsuitable for systems where event time and processing time cannot be reliably distinguished, or where clock skew across distributed sources exceeds the latency thresholds you are trying to measure. In those cases, you need infrastructure-level time synchronization before a prompt-based evaluation can be meaningful.

Before wiring this into a production harness, you must define clear Service Level Objectives (SLOs) for each data source. The prompt template uses placeholders like [SOURCES] and [FRESHNESS_THRESHOLDS] that should be populated from a configuration store, not hardcoded. The output is a structured JSON health report with staleness alerts and reliability scores, which your application can route to alerting systems like PagerDuty or log to an observability platform. The next step after reading this section is to copy the prompt template, map your source metadata into the placeholders, and run it against a known-good and known-stale dataset to calibrate your thresholds before deploying to production.

This prompt template evaluates whether live data feeds, API responses, and streaming sources are delivering data within acceptable latency windows. It produces structured freshness health reports with staleness alerts and source reliability scores. The template is designed to be wired into a monitoring harness that periodically samples data sources and passes their metadata to the model for assessment.

textCopy
You are a real-time data freshness evaluator. Your job is to assess whether streaming data sources are delivering data within acceptable latency windows and to produce a structured freshness health report.

## INPUT DATA

[SOURCE_METADATA]

## EVALUATION PARAMETERS

- Acceptable latency threshold: [MAX_LATENCY_SECONDS] seconds
- Evaluation window: [EVALUATION_WINDOW_MINUTES] minutes
- Domain: [DOMAIN]
- Risk level: [RISK_LEVEL]

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "evaluation_timestamp": "ISO 8601 timestamp of evaluation",
  "overall_health": "healthy|degraded|stale|critical",
  "sources": [
    {
      "source_id": "string",
      "source_name": "string",
      "last_event_timestamp": "ISO 8601 or null",
      "latency_seconds": "number or null if no recent event",
      "freshness_status": "fresh|delayed|stale|offline|unknown",
      "reliability_score": "0.0 to 1.0",
      "staleness_reason": "string or null",
      "recommended_action": "string or null"
    }
  ],
  "alerts": [
    {
      "severity": "warning|critical",
      "source_id": "string",
      "message": "string",
      "detected_at": "ISO 8601"
    }
  ],
  "summary": "One-paragraph human-readable assessment of overall freshness health"
}

## CONSTRAINTS

- If a source has no events in the evaluation window, mark it as offline or unknown with a null latency.
- Reliability scores must reflect both recent latency performance and historical consistency.
- Generate alerts only for sources exceeding the latency threshold or showing degraded patterns.
- If risk level is high, flag any source with latency above 50% of the threshold as a warning.
- Do not fabricate timestamps. Use only the data provided in [SOURCE_METADATA].
- If source metadata is insufficient to determine freshness, set status to unknown and explain why in staleness_reason.

## EXAMPLES

[EXAMPLES]

## TOOLS AVAILABLE

[TOOLS]

Adaptation guidance: Replace [SOURCE_METADATA] with a structured array of source records containing at minimum source_id, source_name, last_event_timestamp, and any historical latency data. Set [MAX_LATENCY_SECONDS] based on your domain's freshness requirements—sub-second for financial trading, seconds for operational dashboards, minutes for batch analytics. The [EXAMPLES] placeholder should contain 2-3 few-shot examples showing correct output for common scenarios like healthy sources, delayed sources, and offline sources. If your pipeline has access to historical uptime data or source health metrics, pass those through [TOOLS] as available function signatures. For high-risk domains such as financial data or safety-critical monitoring, always route alerts through human review before automated actions.

This prompt is designed to run inside a scheduled or event-driven monitoring harness, not as a one-off chat interaction. The typical deployment pattern is a background worker that polls live data sources, assembles a freshness evaluation request, calls the model, parses the structured output, and writes the result to a monitoring dashboard or alerting system. The prompt expects a batch of source metadata—timestamps, source identifiers, expected update cadences—and returns a freshness health report with per-source staleness alerts and reliability scores.

Wire the prompt into your application by building a thin orchestration layer that handles three responsibilities: input assembly, output validation, and alert routing. For input assembly, collect the latest last_updated timestamps, expected_freshness_seconds thresholds, and source_id labels from your streaming sources or API health endpoints. Pack these into the [SOURCE_METADATA] placeholder as a JSON array. For output validation, parse the model's JSON response and run schema checks: every source in the input must appear in the output, staleness_seconds must be a non-negative number, and freshness_status must be one of fresh, degraded, or stale. Reject and retry any response that fails schema validation. For alert routing, publish stale and degraded entries to your incident channel with the recommended_action field included. Use a model that supports structured JSON output (such as gpt-4o with response_format or Claude with tool-use extraction) to reduce parsing failures. Log every evaluation run—input, output, model, latency, and validation result—so you can track source reliability trends and model drift over time.

Do not use this prompt for sources where freshness cannot be measured objectively (e.g., human-reported status without timestamps). Do not skip output validation: a hallucinated fresh status on a stale source will suppress alerts and create a false sense of system health. If a source consistently triggers staleness alerts, investigate whether the expected_freshness_seconds threshold is misconfigured before adjusting the prompt. For high-criticality pipelines, add a human review step for any evaluation where more than 20% of sources are flagged as stale, since this may indicate a systemic ingestion failure rather than individual source lag.