Actor Monitoring System

A monitoring and reporting Actor for Apify Actors and Tasks. Compare recent runs to detect regressions, or generate multi-sheet Excel reports over configurable time periods.

For a stakeholder overview see README-business.md. For full technical coverage see README-mixed.md. For architecture and process flows see Process.md. For field strategies and custom dimensions see FIELD_COMPARISON_AND_CUSTOM_DIMENSIONS_GUIDE.md. For copy-paste inputs and local smoke testing see examples/README.md.

Features

• Run comparison with multiple strategies (last2, lastVsBaseline, lastVsAverage, or explicit run IDs)
• Monthly Excel reports with executive dashboard, metrics, aggregation, exceptions, and cost breakdown
• Intelligent field comparison with 25 strategies and automatic strategy detection
• Email alerts — consolidated or per-comparison, with significance filtering and health-check fallback
• Status alerts for non-successful latest runs
• Trend and anomaly analysis over historical runs
• Monitoring state to avoid duplicate alerts across scheduled runs
• Flexible output routing — email, dataset-only, or both
• Webhooks, compare Excel export, and HTML dashboard artifacts
• Client billing — optional pricePerItem adds Total Billed and Margin alongside Apify cost in Excel, email, and dataset

Architecture

main.ts validates input, builds config, and delegates to services created by ServiceFactory:

Service	Role
InputValidator	Zod validation and email filtering
DataFetcherService	Run collection orchestration
RunCollectionService	Actor/task discovery and concurrent fetching
ComparisonService	Comparisons, significance filtering, emails
EnrichmentService	Run enrichment and actor name caching
ReportService	Monthly report pipeline
EmailService	HTML email generation
StorageManager	KV store artifacts
AppLogger	Structured logging

Report Types

Compare Mode (actorMode: "compare")

Detects meaningful changes between runs at two levels:

• Run-level: items count, runtime, cost, memory, CPU
• Dataset-level: per-field analysis using fieldsAndCompareStrategy

Compare strategies (compareMode):

Strategy	Description
last2	Latest vs previous run (default)
lastVsBaseline	Latest vs a fixed baselineRunId
lastVsAverage	Latest vs average of baselineRunCount recent runs
Explicit IDs	compareRunId1 + compareRunId2 bypasses discovery

Email delivery:

• combineEmails: true (default) — one email with all comparisons
• combineEmails: false — separate email per comparison
• notifyOnSignificantChange — email only when thresholds are exceeded
• alwaysSendSummary — health-check email when nothing significant changed

Monthly Mode (actorMode: "monthly")

Generates a multi-sheet Excel workbook for a configurable period (1–24 months, default 3) or custom date range.

Excel sheets:

• Executive Dashboard (KPIs, period diff, health rankings, trends)
• Aggregated Metrics, Aggregated Insights
• Failed Runs / Succeeded With 0 Items (when applicable)
• Resource Usage, Threshold Breaches
• All Runs, Category sheets, Cost Breakdown, Contents

Also produces categorized runs JSON, report manifest, optional product aggregation, and monthly email.

Client billing (pricePerItem)

Set a global USD rate per scraped item to show Total Billed (items × price) and Margin (billed minus Apify cost) in monthly Excel, email, dataset summary, and compare reports. Leave unset to disable billing columns (default). Example: examples/16-client-billing.json.

Intelligent Field Comparison

Automatic Strategy Detection

When no strategy is configured, the system analyzes data types, distributions, and field names to select the best comparison approach.

User-Defined Strategies

{
  "actorMode": "compare",
  "fieldsAndCompareStrategy": {
    "product.price": "average",
    "reviews": "array_length",
    "product.description": "coverage",
    "total_sales": "sum"
  }
}

Each field can also use an extended object: { "strategy": "average", "label": "Avg Price", "lowerIsBetter": false, "threshold": { "warning": 10, "critical": 25 } }.

Available Strategies

Category	Strategies
Basic	count, sum, average, array_length, coverage, distinct_count, boolean_rate
Statistical	min, max, median, percentile_95, percentile_99, variance, stddev, range, iqr
Advanced	set_difference, set_overlap, deep_equality, avg_length, null_rate, mode, completeness, uniqueness, ratio

Strategy Priority

1. User-defined strategy in fieldsAndCompareStrategy
2. Automatic detection from data characteristics
3. Field discovery report saved to KV as field-discovery-report.v2.{entity} when no config is provided

Configuration

Core Input Parameters

Parameter	Type	Default	Description
actorMode	string	monthly	compare or monthly
useDirectActorRuns	boolean	false	Fetch runs from actors directly (ignores task filters)
outputMode	string	email	email, dataset, or both
compareMode	string	last2	last2, lastVsBaseline, lastVsAverage
compareRunId1 / compareRunId2	string	—	Explicit run pair (overrides discovery)
baselineRunId	string	—	Required for lastVsBaseline
baselineRunCount	integer	5	Runs to average for lastVsAverage (2–20)
monthsToAnalyze	integer	3	Calendar months for monthly reports (1–24)
includeCurrentMonth	boolean	true	Include in-progress month
dateRangeStart / dateRangeEnd	string	—	ISO dates; override month window
maxRuns	integer	100	Max runs per actor/task (1–50000)
maxDatasetItems	integer	1000	Dataset items per run for field comparison
combineEmails	boolean	true	Consolidate comparison emails
notifyOnSignificantChange	boolean	true	Email only on significant changes
alwaysSendSummary	boolean	false	Health-check when no significant changes
significanceThreshold	number	5	Min % change to flag significance
enableTrendAnalysis	boolean	false	Multi-run trend analysis
enableAnomalyDetection	boolean	false	Z-score anomaly detection
enableCompareExcel	boolean	false	Export compare Excel to KV
enableAggregation	boolean	true	Product volume aggregation in monthly
saveHtmlDashboard	boolean	false	Save monthly HTML to KV
webhookUrl	string	—	POST JSON on report completion
dryRun	boolean	false	Save email HTML to KV instead of sending
emailRecipients	array	[]	Report recipients
fieldsAndCompareStrategy	object	—	Per-field comparison strategies; omit to enable field auto-discovery (do not pass {}; runtime normalizes empty object to unset)
excludeFields	array	[]	Fields to skip in comparison
alertThresholds	object	—	Warning/critical tiers per metric
customDimensions	array	—	Monthly grouping dimensions (max 5)
topNActors	integer	5	Top actors in monthly rankings
healthScoreWeights	object	—	Monthly health score weights (must sum to 1.0)
actorNameInclude / Exclude	array	—	Actor name substring filters
actorNamePattern	string	—	Actor name regex (overrides substrings)
taskNameInclude / Exclude	array	—	Task name filters (ignored when direct actor runs)
taskNamePattern	string	—	Task name regex
actorIds	array	—	Explicit actor IDs (8–64 alphanumeric; skip discovery)
monthlyFilterStatus	array	all statuses	Status filter for monthly mode
compareFilterStatus	array	SUCCEEDED	Status filter for compare mode
emailSubject	string	—	Template: {mode}, {date}, {actorCount}, {status}
emailSections	object	all true	Toggle email sections
emailFooterText	string	—	Custom footer
concurrencyLimit	integer	5	Parallel actor/task processing (1–20)
circuitBreakerThreshold	integer	3	Abort after consecutive collection failures (1–50)
token	string	—	Optional Apify API token
debug	boolean	false	Verbose logging

Configuration Examples

Copy-paste inputs for fifteen real-world scenarios live in examples/ (task-based pg- portfolio, explicit run IDs, monthly date ranges). Refresh run fixtures with npm run discover:examples.

Scenario	Example file
Daily production compare	examples/01-daily-production-monitoring.json
Incident / explicit runs	examples/04-incident-investigation.json
Field auto-discovery	examples/12-field-discovery-auto-config.json
Average baseline compare	examples/13-compare-average-baseline.json
Monthly date-range export	examples/15-monthly-date-range-export.json

Minimal starting points:

{ "actorMode": "monthly" }

{
  "actorMode": "compare",
  "useDirectActorRuns": false,
  "actorNamePattern": "pg-",
  "taskNameInclude": ["amazon-de"],
  "maxRuns": 2,
  "dryRun": true
}

Direct Actor Runs vs Task-Based

Direct Actor Runs (useDirectActorRuns: true)

• Monitors all runs from matching actors regardless of task.
• Task filters are ignored.
• Best for actor-level performance monitoring.

Task-Based (useDirectActorRuns: false — default)

• Organizes monitoring by tasks.
• Supports task name include/exclude/pattern filters.
• Best for task-category analysis.

Custom Dimensions (Monthly)

Group runs by any field path with optional transforms and buckets:

{
  "customDimensions": [
    { "field": "actorName", "label": "Actor", "fallback": "Unknown" },
    { "field": "status", "label": "Status", "transform": "successFailure" },
    {
      "field": "stats.runTimeSecs",
      "label": "Runtime Bucket",
      "buckets": [
        { "max": 60, "label": "< 1 min" },
        { "max": 300, "label": "1–5 min" },
        { "label": "> 5 min" }
      ],
      "sort": "count"
    }
  ]
}

Data Flow

graph TD
    A[Input] --> B[Validate + buildConfig]
    B --> C[ServiceFactory]
    C --> D{actorMode}

    D -->|compare| E[RunCollectionService]
    E --> F[ComparisonService buffer]
    F --> G[flushCompareOutputs dataset rows]
    G --> H[Compare Excel + manifest KV]
    H --> I[finalizeCompareNotifications emails]
    I --> J[Optional Webhook]

    D -->|monthly| K[RunCollectionService]
    K --> L[categorizeRuns]
    L --> M[ExcelReportBuilder]
    M --> N[KV Artifacts + Manifest]
    N --> O[Monthly Email / Webhook]
    N --> P[Dataset Metadata]

Email Reports

Compare Email Sections

• Executive summary cards
• Comparison table with unified delta styling and run links
• Report artifact links (dataset, manifest, compare Excel when generated)
• Top regressions, build changes, schema changes
• Cost breakdown; trend analysis and anomaly detection in collapsible Technical details
• Field discovery suggestions (when no strategy configured)
• Status alerts for failed latest runs

Monthly Email Sections

• KPI grid, executive summary, watchlist
• Period-over-period diff (when prior report exists)
• Monthly trends and product volume aggregation
• Artifact download links

Health-Check Email

Sent when alwaysSendSummary is true and no significant changes were detected. Confirms monitoring scope and all-clear status.

Outputs

Output	Compare	Monthly
Dataset comparison/monthly records	✓	✓
Performance metrics	✓	✓
last-report-summary (KV)	✓	✓
compare-manifest.v1 (KV)	✓	—
field-discovery-report.v2.* (KV)	✓	—
Excel workbook	optional	✓
Email	optional	optional
Webhook (with retry)	optional	optional
monitoring-state (KV)	✓	—
HTML dashboard (KV)	—	optional

Performance

• Parallel processing with configurable concurrency (concurrencyLimit, default 5)
• Circuit breaker after consecutive collection failures (circuitBreakerThreshold, default 3)
• Paginated API fetching with retry for transient errors
• Bounded dataset item fetching (maxDatasetItems)

Examples and Local Smoke Testing

Fifteen task-based examples using real pg- portfolio filters live in examples/. Refresh Apify run fixtures and batch-test locally:

npm run discover:examples      # writes examples/_fixtures.json (gitignored)
npm run test:examples:smoke    # runs all 15 examples (~5 min)

See examples/README.md for per-example bindings and pass criteria.

Deployment

Build and push to Apify, then run with token in Actor secrets (not committed input):

npm run build
apify push
apify actor run actors-monitoring --input-file examples/12-field-discovery-auto-config.json

Verify KV artifacts: field-discovery-report.v2.*, compare-manifest.v1, last-report-summary.

Troubleshooting

Issue	Likely cause	Action
No email received	No recipients, significance filter, or outputMode: dataset	Check emailRecipients, notifyOnSignificantChange, outputMode
Partial report	Circuit breaker tripped	Check logs for failed actors/tasks; increase threshold or fix API access
Duplicate alerts	Monitoring state not persisting	Verify KV store access; avoid explicit run ID mode for scheduled monitoring
Slow runs	High maxRuns / maxDatasetItems	Reduce volume limits or narrow filters