This guide is designed to end that cycle by replacing it with something more useful: a systematic, service-by-service approach to knowing exactly what you're spending, why you're spending it, catching problems before they become invoices, and reducing costs without guesswork.

It's organised as a reference you can return to. Each part is complete on its own: you can go straight to the RDS section if that's your current problem, or follow the guide start to finish if you're building a FinOps practice from scratch. Every command is runnable, and every script is deployable.

Table of Contents

• What You'll Learn

• Prerequisites

• Part 1: Monitoring — Know Where Every Dollar Goes

• Part 2: Alerting — Catch Spikes Before They Become Invoices

• Part 3: Optimisation by Service

• Part 4: The 30-Day Optimisation Sprint

• Best Practices Summary

• Resources

What You'll Learn

• How to set up Cost and Usage Report querying with Athena, the foundation of all serious cost analysis

• The five dashboards every engineering team needs, built with queries you can run today

• A three-tier alerting strategy that catches cost spikes without creating alert fatigue

• Service-specific optimisation playbooks for EC2, S3, Lambda, RDS, DynamoDB, and data transfer

• A concrete 30-day sprint that produces measurable savings in the first month

Let's build this from the ground up.

Prerequisites

Before following this guide, you should have:

Knowledge:

• Working familiarity with AWS services: EC2, S3, RDS, Lambda, and VPC

• Comfort reading Python and SQL

• Basic understanding of how IAM policies and roles work

Access:

• AWS account with billing access. The IAM user or role you work with needs ce:GetCostAndUsage, ec2:Describe*, rds:Describe*, and s3:GetBucketLifecycleConfiguration permissions.

• AWS CLI v2 configured

• Athena access (for the CUR queries in Part 1)

Setup:

• Enable Cost Explorer if it isn't already. It's free and required for most commands in this guide:

aws ce enable-cost-explorer --region us-east-1

• The Cost and Usage Report (CUR) should be configured and exporting to an S3 bucket. If it isn't yet, the AWS CUR setup guide walks through the process. Give the report 24 hours after setup to generate the first data file.

Part 1: Monitoring — Know Where Every Dollar Goes

1.1 The Cost and Usage Report — Your Source of Truth

Cost Explorer shows you service-level totals. It's useful for trends, but it isn't sufficient for root cause analysis. When you need to know which specific resource is responsible for a $12,000/month line item, you need the Cost and Usage Report queried through Athena.

Create the Athena table over your CUR data:

-- Run this once in Athena after your CUR starts generating data
-- Replace 'your-cur-bucket' and 'your-prefix' with your actual values

CREATE EXTERNAL TABLE IF NOT EXISTS cur_database.billing (
    bill_billing_period_start_date  STRING,
    bill_payer_account_id           STRING,
    line_item_usage_start_date      STRING,
    line_item_resource_id           STRING,
    line_item_usage_type            STRING,
    line_item_usage_amount          DOUBLE,
    line_item_unblended_cost        DOUBLE,
    product_servicecode             STRING,
    product_instance_type           STRING,
    product_region                  STRING,
    resource_tags_user_environment  STRING,
    resource_tags_user_team         STRING,
    resource_tags_user_service      STRING,
    resource_tags_user_owner        STRING
)
PARTITIONED BY (year STRING, month STRING)
ROW FORMAT DELIMITED
FIELDS TERMINATED BY ','
LOCATION 's3://your-cur-bucket/your-prefix/'
TBLPROPERTIES ('skip.header.line.count'='1');

MSCK REPAIR TABLE cur_database.billing;

Here are the three queries you should run on day one:

-- Query 1: Top 20 resources by cost this month
-- Run this first. It tells you where to focus.
SELECT
    line_item_resource_id,
    product_servicecode,
    resource_tags_user_team     AS team,
    resource_tags_user_service  AS service,
    SUM(line_item_unblended_cost) AS total_cost_usd
FROM cur_database.billing
WHERE line_item_usage_start_date >= DATE_FORMAT(
    DATE_TRUNC('month', CURRENT_DATE), '%Y-%m-%d'
)
  AND line_item_unblended_cost > 0
GROUP BY 1, 2, 3, 4
ORDER BY total_cost_usd DESC
LIMIT 20;

-- Query 2: Week-over-week cost growth by service
-- Identifies which services are growing fastest — these need investigation
WITH weekly AS (
    SELECT
        DATE_TRUNC('week', CAST(line_item_usage_start_date AS DATE)) AS week,
        product_servicecode,
        SUM(line_item_unblended_cost) AS cost
    FROM cur_database.billing
    WHERE line_item_usage_start_date >=
          DATE_FORMAT(DATE_ADD('day', -42, CURRENT_DATE), '%Y-%m-%d')
    GROUP BY 1, 2
)
SELECT
    curr.product_servicecode AS service,
    ROUND(prev.cost, 2)      AS prev_week_cost,
    ROUND(curr.cost, 2)      AS curr_week_cost,
    ROUND(
        100.0 * (curr.cost - prev.cost) / NULLIF(prev.cost, 0),
        1
    ) AS pct_change
FROM weekly curr
JOIN weekly prev
  ON curr.product_servicecode = prev.product_servicecode
  AND curr.week = DATE_ADD('week', 1, prev.week)
WHERE curr.week = DATE_TRUNC('week', CURRENT_DATE)
  AND ABS((curr.cost - prev.cost) / NULLIF(prev.cost, 0)) > 0.20
ORDER BY pct_change DESC;

-- Query 3: Resources running with no usage (candidates for shutdown)
-- Finds resources that incurred cost but had zero usage quantity
-- in the past 7 days — strong signal for idle or orphaned resources
SELECT
    line_item_resource_id,
    product_servicecode,
    resource_tags_user_owner    AS owner,
    resource_tags_user_team     AS team,
    SUM(line_item_unblended_cost) AS cost_past_7_days
FROM cur_database.billing
WHERE line_item_usage_start_date >=
      DATE_FORMAT(DATE_ADD('day', -7, CURRENT_DATE), '%Y-%m-%d')
  AND line_item_usage_amount = 0
  AND line_item_unblended_cost > 5
GROUP BY 1, 2, 3, 4
ORDER BY cost_past_7_days DESC
LIMIT 30;

1.2 The Five Essential Cost Dashboards

These five views cover the monitoring needs of most engineering teams. Each is built from queries you can run immediately, no third-party tool required.

Dashboard 1: Executive Summary (for weekly leadership updates)

# executive_summary.py
import boto3
from datetime import datetime, timedelta

ce = boto3.client('ce')


def weekly_summary():
    today     = datetime.now()
    start_mtd = today.replace(day=1).strftime('%Y-%m-%d')
    today_str = today.strftime('%Y-%m-%d')

    # Month-to-date spend
    mtd = ce.get_cost_and_usage(
        TimePeriod={'Start': start_mtd, 'End': today_str},
        Granularity='MONTHLY',
        Metrics=['UnblendedCost']
    )
    mtd_spend = float(
        mtd['ResultsByTime'][0]['Total']['UnblendedCost']['Amount']
    )

    # End-of-month forecast
    forecast = ce.get_cost_forecast(
        TimePeriod={
            'Start': today_str,
            'End':   (today.replace(day=28) + timedelta(days=4)).replace(day=1).strftime('%Y-%m-%d'),
        },
        Metric='UNBLENDED_COST',
        Granularity='MONTHLY'
    )
    eom_forecast = float(forecast['Total']['Amount']) + mtd_spend

    # Top 5 services
    by_service = ce.get_cost_and_usage(
        TimePeriod={'Start': start_mtd, 'End': today_str},
        Granularity='MONTHLY',
        Metrics=['UnblendedCost'],
        GroupBy=[{'Type': 'DIMENSION', 'Key': 'SERVICE'}]
    )
    services = sorted(
        [
            (g['Keys'][0], float(g['Metrics']['UnblendedCost']['Amount']))
            for g in by_service['ResultsByTime'][0]['Groups']
        ],
        key=lambda x: x[1],
        reverse=True
    )[:5]

    print(f"\n{'─'*48}")
    print(f"  AWS Cost Summary — {today.strftime('%B %Y')}")
    print(f"{'─'*48}")
    print(f"  Month-to-date:     ${mtd_spend:>12,.2f}")
    print(f"  End-of-month est:  ${eom_forecast:>12,.2f}")
    print(f"\n  Top 5 Services:")
    for name, cost in services:
        short = name.replace('Amazon ', '').replace('AWS ', '')
        print(f"    {short:<32} ${cost:>9,.2f}")
    print(f"{'─'*48}\n")


weekly_summary()

Dashboard 2: Team Cost Breakdown (for engineering leads)

# team_breakdown.py
import boto3
from datetime import datetime

ce = boto3.client('ce')


def team_breakdown():
    start = datetime.now().replace(day=1).strftime('%Y-%m-%d')
    end   = datetime.now().strftime('%Y-%m-%d')

    response = ce.get_cost_and_usage(
        TimePeriod={'Start': start, 'End': end},
        Granularity='MONTHLY',
        Metrics=['UnblendedCost'],
        GroupBy=[
            {'Type': 'TAG',       'Key': 'Team'},
            {'Type': 'DIMENSION', 'Key': 'SERVICE'},
        ]
    )

    by_team = {}
    for group in response['ResultsByTime'][0].get('Groups', []):
        team_raw = group['Keys'][0]
        team     = team_raw.replace('Team$', '') if team_raw else 'untagged'
        service  = group['Keys'][1]
        cost     = float(group['Metrics']['UnblendedCost']['Amount'])

        if team not in by_team:
            by_team[team] = {'total': 0.0, 'by_service': {}}
        by_team[team]['total'] += cost
        by_team[team]['by_service'][service] = (
            by_team[team]['by_service'].get(service, 0.0) + cost
        )

    total_bill = sum(d['total'] for d in by_team.values())

    print(f"\n{'─'*58}")
    print(f"  Team Cost Breakdown — MTD {datetime.now().strftime('%Y-%m-%d')}")
    print(f"  Total: ${total_bill:,.2f}")
    print(f"{'─'*58}")

    for team, data in sorted(by_team.items(), key=lambda x: x[1]['total'], reverse=True):
        pct = (data['total'] / total_bill * 100) if total_bill else 0
        print(f"\n  {team:<20}  ${data['total']:>10,.2f}  ({pct:.1f}%)")
        top3 = sorted(data['by_service'].items(), key=lambda x: x[1], reverse=True)[:3]
        for svc, cost in top3:
            short = svc.replace('Amazon ', '').replace('AWS ', '')
            print(f"    └─ {short:<30} ${cost:>8,.2f}")

    print()


team_breakdown()

Dashboard 3: Waste Detection (for weekly cleanup reviews):

# waste_detector.py
import boto3
from datetime import datetime, timezone, timedelta

ec2  = boto3.client('ec2')
elbv2 = boto3.client('elbv2')
cw   = boto3.client('cloudwatch')


def detect_waste():
    report = {'items': [], 'total_monthly_waste': 0.0}

    # Unattached EBS volumes
    for vol in ec2.describe_volumes(
        Filters=[{'Name': 'status', 'Values': ['available']}]
    )['Volumes']:
        age  = (datetime.now(timezone.utc) - vol['CreateTime']).days
        cost = round(vol['Size'] * 0.08, 2)
        tags = {t['Key']: t['Value'] for t in vol.get('Tags', [])}
        report['items'].append({
            'type':         'Unattached EBS Volume',
            'id':           vol['VolumeId'],
            'detail':       f"{vol['Size']}GB — {age} days old",
            'owner':        tags.get('Owner', '—'),
            'monthly_cost': cost,
        })
        report['total_monthly_waste'] += cost

    # Unassociated Elastic IPs
    for addr in ec2.describe_addresses()['Addresses']:
        if 'AssociationId' not in addr:
            report['items'].append({
                'type':         'Unassociated Elastic IP',
                'id':           addr.get('AllocationId', ''),
                'detail':       addr['PublicIp'],
                'owner':        '—',
                'monthly_cost': 3.60,
            })
            report['total_monthly_waste'] += 3.60

    # Idle load balancers (fewer than 100 requests in 7 days)
    for lb in elbv2.describe_load_balancers()['LoadBalancers']:
        metrics = cw.get_metric_statistics(
            Namespace='AWS/ApplicationELB',
            MetricName='RequestCount',
            Dimensions=[{'Name': 'LoadBalancer',
                         'Value': lb['LoadBalancerArn'].split(':loadbalancer/')[-1]}],
            StartTime=datetime.now() - timedelta(days=7),
            EndTime=datetime.now(),
            Period=604800,
            Statistics=['Sum']
        )['Datapoints']
        total_requests = metrics[0]['Sum'] if metrics else 0

        if total_requests < 100:
            report['items'].append({
                'type':         'Idle Load Balancer',
                'id':           lb['LoadBalancerName'],
                'detail':       f"{int(total_requests)} requests in 7 days",
                'owner':        '—',
                'monthly_cost': 22.0,
            })
            report['total_monthly_waste'] += 22.0

    print(f"\n  Waste Detection Report — {datetime.now().strftime('%Y-%m-%d')}")
    print(f"  Estimated monthly waste: ${report['total_monthly_waste']:.2f}\n")

    for item in sorted(report['items'], key=lambda x: x['monthly_cost'], reverse=True)[:20]:
        print(f"  [{item['type']}]")
        print(f"    ID:     {item['id']}")
        print(f"    Detail: {item['detail']}")
        print(f"    Owner:  {item['owner']}")
        print(f"    Cost:   ${item['monthly_cost']:.2f}/month\n")

    return report


detect_waste()

1.3 Tagging Strategy — The Foundation of All Attribution

Every cost attribution model depends on tags. Teams that skip tagging build dashboards that show totals without explanations. The discipline is in making tagging structural rather than procedural: enforced by infrastructure code, not by reminders in Confluence.

Required tag set:

# terraform/variables.tf
variable "mandatory_tags" {
  description = "Tags applied to every resource in this account"
  type        = map(string)

  validation {
    condition = alltrue([
      contains(keys(var.mandatory_tags), "Environment"),
      contains(keys(var.mandatory_tags), "Team"),
      contains(keys(var.mandatory_tags), "Owner"),
      contains(keys(var.mandatory_tags), "Service"),
    ])
    error_message = "mandatory_tags must include Environment, Team, Owner, and Service."
  }
}

locals {
  common_tags = merge(var.mandatory_tags, {
    ManagedBy    = "terraform"
    LastModified = timestamp()
  })
}

resource "aws_instance" "api_server" {
  ami           = data.aws_ami.amazon_linux_2023.id
  instance_type = "t3.medium"
  tags          = merge(local.common_tags, {Name = "api-server-${var.environment}"})
}

Find and report untagged resources weekly:

#!/usr/bin/env bash
# find_untagged.sh

echo "Untagged EC2 instances (missing Team tag):"
aws ec2 describe-instances \
  --filters "Name=instance-state-name,Values=running" \
  --query "Reservations[].Instances[?!not_null(Tags[?Key=='Team'].Value|[0])].[InstanceId,InstanceType,LaunchTime]" \
  --output table

echo "Untagged RDS instances:"
aws rds describe-db-instances \
  --query "DBInstances[?!not_null(TagList[?Key=='Team'].Value|[0])].DBInstanceIdentifier" \
  --output table

Part 2: Alerting — Catch Spikes Before They Become Invoices

The typical discovery timeline without proactive alerting: a cost spike happens on the 5th, the monthly invoice arrives on the 20th, someone notices on the 22nd, investigation begins on the 23rd, and two weeks of billed waste can't be recovered. With proactive alerting, discovery happens within hours.

2.1 The Three-Tier Alert Structure

Alert fatigue is as damaging as no alerting. The three-tier model keeps signal high by routing different severity levels to different channels with different response expectations.

# alert_router.py
import boto3
import json
import urllib.request
from enum import Enum

SLACK_INFO_WEBHOOK  = 'https://hooks.slack.com/services/INFO/WEBHOOK'
SLACK_ALERT_WEBHOOK = 'https://hooks.slack.com/services/ALERT/WEBHOOK'
SNS_CRITICAL_TOPIC  = 'arn:aws:sns:us-east-1:YOUR_ACCOUNT:cost-critical'


class AlertTier(Enum):
    INFO     = 1
    WARNING  = 2
    CRITICAL = 3


def route_alert(tier: AlertTier, subject: str, message: str):
    """Send an alert to the appropriate channel for its severity tier."""
    icons   = {AlertTier.INFO: ':information_source:',
               AlertTier.WARNING: ':warning:', AlertTier.CRITICAL: ':rotating_light:'}
    payload = {'text': f"{icons[tier]} *{subject}*\n{message}"}

    if tier == AlertTier.INFO:
        _post_slack(SLACK_INFO_WEBHOOK, payload)
    elif tier == AlertTier.WARNING:
        _post_slack(SLACK_ALERT_WEBHOOK, payload)
        _send_sns(SNS_CRITICAL_TOPIC, subject, f"WARNING: {message}")
    elif tier == AlertTier.CRITICAL:
        _post_slack(SLACK_ALERT_WEBHOOK, payload)
        _send_sns(SNS_CRITICAL_TOPIC, subject, f"CRITICAL: {message}")


def _post_slack(webhook: str, payload: dict):
    req = urllib.request.Request(
        webhook,
        data=json.dumps(payload).encode(),
        headers={'Content-Type': 'application/json'}
    )
    urllib.request.urlopen(req)


def _send_sns(topic_arn: str, subject: str, message: str):
    sns = boto3.client('sns')
    sns.publish(TopicArn=topic_arn, Subject=subject[:100], Message=message)

The three tiers and what they respond to: Tier 1 INFO goes to a Slack informational channel for daily cost summaries, weekly trend reports, and tag compliance updates. No action required.

Tier 2 WARNING goes to a Slack alert channel plus email for budget above 75% utilisation, 25% week-over-week increases, and expiring Savings Plans. Acknowledge within 24 hours.

Tier 3 CRITICAL goes to PagerDuty plus SMS for budget above 90% utilisation, 100% increase in 24 hours, crypto mining detected, and projected overspend above 120% of plan. Investigate within 1 hour.

2.2 Real-Time Budget Monitor

AWS Budgets sends alerts once daily by default. A daily window means a cost spike that begins at 08:00 isn't caught until the next day's alert fires. The Lambda below runs hourly and checks both absolute budget utilisation and hour-over-hour rate of change.

# budget_monitor.py
# Lambda triggered by EventBridge every hour

import boto3
from datetime import datetime, timedelta
from alert_router import route_alert, AlertTier

ce      = boto3.client('ce')
budgets = boto3.client('budgets', region_name='us-east-1')
ACCOUNT_ID  = boto3.client('sts').get_caller_identity()['Account']
BUDGET_NAME = 'monthly-infrastructure'


def get_mtd_spend() -> float:
    start = datetime.now().replace(day=1).strftime('%Y-%m-%d')
    end   = datetime.now().strftime('%Y-%m-%d')
    r = ce.get_cost_and_usage(
        TimePeriod={'Start': start, 'End': end},
        Granularity='MONTHLY',
        Metrics=['UnblendedCost']
    )
    return float(r['ResultsByTime'][0]['Total']['UnblendedCost']['Amount'])


def get_budget_limit() -> float:
    r = budgets.describe_budget(AccountId=ACCOUNT_ID, BudgetName=BUDGET_NAME)
    return float(r['Budget']['BudgetLimit']['Amount'])


def get_hourly_costs(hours: int = 4) -> list:
    """Return hourly cost totals for the last N hours."""
    end   = datetime.now()
    start = end - timedelta(hours=hours)
    r = ce.get_cost_and_usage(
        TimePeriod={'Start': start.strftime('%Y-%m-%d'), 'End': end.strftime('%Y-%m-%d')},
        Granularity='HOURLY',
        Metrics=['UnblendedCost']
    )
    return [
        float(period['Total']['UnblendedCost']['Amount'])
        for period in r['ResultsByTime']
    ]


def lambda_handler(event, context):
    mtd_spend    = get_mtd_spend()
    budget_limit = get_budget_limit()
    utilisation  = mtd_spend / budget_limit * 100

    days_elapsed  = datetime.now().day
    projected_eom = (mtd_spend / days_elapsed) * 30
    projected_pct = projected_eom / budget_limit * 100

    if utilisation >= 90:
        route_alert(
            AlertTier.CRITICAL,
            f'Budget at {utilisation:.0f}%',
            f'MTD spend ${mtd_spend:,.2f} is {utilisation:.0f}% of ${budget_limit:,.0f} budget. '
            f'Projected EOM: ${projected_eom:,.2f}.'
        )
    elif utilisation >= 75:
        route_alert(
            AlertTier.WARNING,
            f'Budget at {utilisation:.0f}%',
            f'MTD spend ${mtd_spend:,.2f} is {utilisation:.0f}% of ${budget_limit:,.0f} budget. '
            f'Projected EOM: ${projected_eom:,.2f}.'
        )

    # Check hourly spike
    hourly = get_hourly_costs(hours=4)
    if len(hourly) >= 2:
        last_hour = hourly[-1]
        prev_avg  = sum(hourly[:-1]) / len(hourly[:-1])
        if prev_avg > 0.10 and last_hour > prev_avg * 1.5:
            route_alert(
                AlertTier.WARNING,
                'Hourly cost spike detected',
                f'Last hour: ${last_hour:.2f} vs prior 3-hour avg ${prev_avg:.2f} '
                f'(+{(last_hour/prev_avg - 1)*100:.0f}%)'
            )

    return {
        'mtd_spend':       round(mtd_spend, 2),
        'utilisation_pct': round(utilisation, 1),
        'projected_eom':   round(projected_eom, 2),
    }

Part 3: Optimisation by Service

3.1 EC2 — Seven Levers in Priority Order

EC2 is the largest line item in most AWS accounts and the one with the most optimisation options. Work through these levers in order, as each one lowers the baseline that the next lever acts on.

Lever 1: Find truly idle instances (CPU below 1% for 14 days).

# ec2_idle_finder.py
import boto3
from datetime import datetime, timedelta

ec2 = boto3.client('ec2')
cw  = boto3.client('cloudwatch')


def find_idle_instances(avg_cpu_threshold: float = 1.0, days: int = 14):
    instances = [
        inst
        for r in ec2.describe_instances(
            Filters=[{'Name': 'instance-state-name', 'Values': ['running']}]
        )['Reservations']
        for inst in r['Instances']
    ]

    idle = []
    for inst in instances:
        iid   = inst['InstanceId']
        stats = cw.get_metric_statistics(
            Namespace='AWS/EC2',
            MetricName='CPUUtilization',
            Dimensions=[{'Name': 'InstanceId', 'Value': iid}],
            StartTime=datetime.utcnow() - timedelta(days=days),
            EndTime=datetime.utcnow(),
            Period=days * 86400,
            Statistics=['Average']
        )['Datapoints']

        avg_cpu = stats[0]['Average'] if stats else 0.0
        if avg_cpu < avg_cpu_threshold:
            tags = {t['Key']: t['Value'] for t in inst.get('Tags', [])}
            idle.append({
                'instance_id':   iid,
                'instance_type': inst['InstanceType'],
                'avg_cpu':       round(avg_cpu, 2),
                'environment':   tags.get('Environment', '—'),
                'owner':         tags.get('Owner', '—'),
            })

    return sorted(idle, key=lambda x: x['avg_cpu'])


for inst in find_idle_instances():
    print(f"  {inst['instance_id']}  {inst['instance_type']}  "
          f"{inst['avg_cpu']}% CPU  env:{inst['environment']}  owner:{inst['owner']}")

Lever 2: Right-size over-provisioned instances (CPU below 20%, sustained).

Use the same script with avg_cpu_threshold=20.0. These are right-sizing candidates, not shutdown candidates.

Lever 3: Schedule dev and staging shutdowns using EventBridge rules on AutoShutdown=true tagged instances.

Lever 4: Purchase Savings Plans only after completing levers 1–3.

Lever 5: Migrate to Graviton (20% cheaper, same performance for most workloads).

Lever 6: Use Spot for fault-tolerant batch and development workloads.

Lever 7: Migrate containerised workloads to EKS with Karpenter for automatic bin-packing.

Spot savings estimate:

# spot_price_analyser.py
import boto3

ec2 = boto3.client('ec2')


def spot_savings_estimate(instance_type: str) -> dict:
    spot_history = ec2.describe_spot_price_history(
        InstanceTypes=[instance_type],
        ProductDescriptions=['Linux/UNIX'],
        MaxResults=1
    )['SpotPriceHistory']
    spot_price = float(spot_history[0]['SpotPrice']) if spot_history else 0

    on_demand_approx = {
        't3.medium': 0.0416, 'm5.large': 0.096,
        'c5.xlarge': 0.17,   'r5.2xlarge': 0.504,
    }
    od_price    = on_demand_approx.get(instance_type, 0)
    savings_pct = ((od_price - spot_price) / od_price * 100) if od_price else 0

    return {
        'instance_type': instance_type,
        'spot_price':    round(spot_price, 4),
        'on_demand':     od_price,
        'savings_pct':   round(savings_pct, 1),
        'monthly_spot':  round(spot_price * 730, 2),
        'monthly_od':    round(od_price * 730, 2),
    }


for itype in ['t3.medium', 'm5.large', 'c5.xlarge']:
    r = spot_savings_estimate(itype)
    print(f"  {r['instance_type']:<15} Spot: ${r['spot_price']}/hr  "
          f"OD: ${r['on_demand']}/hr  Savings: {r['savings_pct']}%")

3.2 S3 — Lifecycle Policies and Storage Class Selection

S3 optimisation has two components: moving infrequently accessed data to cheaper storage classes via lifecycle policies, and eliminating waste patterns like incomplete multipart uploads.

# s3_lifecycle_applier.py
import boto3

s3 = boto3.client('s3')

LOG_POLICY = {
    'Rules': [{
        'ID': 'standard-tiering',
        'Status': 'Enabled',
        'Filter': {'Prefix': ''},
        'Transitions': [
            {'Days': 30,  'StorageClass': 'STANDARD_IA'},
            {'Days': 90,  'StorageClass': 'GLACIER_IR'},
            {'Days': 365, 'StorageClass': 'DEEP_ARCHIVE'},
        ],
        'Expiration': {'Days': 2555},
        'AbortIncompleteMultipartUpload': {'DaysAfterInitiation': 7},
    }]
}

TEMP_POLICY = {
    'Rules': [{
        'ID': 'temp-data-retention',
        'Status': 'Enabled',
        'Filter': {'Prefix': ''},
        'Expiration': {'Days': 30},
        'AbortIncompleteMultipartUpload': {'DaysAfterInitiation': 1},
    }]
}

for bucket in s3.list_buckets()['Buckets']:
    name = bucket['Name']
    try:
        s3.get_bucket_lifecycle_configuration(Bucket=name)
        print(f"  {name} — policy already exists, skipping")
    except s3.exceptions.ClientError:
        policy = TEMP_POLICY if any(k in name for k in ['temp', 'build', 'cache']) else LOG_POLICY
        s3.put_bucket_lifecycle_configuration(
            Bucket=name, LifecycleConfiguration=policy
        )
        print(f"  {name} — applied {'TEMP' if policy is TEMP_POLICY else 'LOG'} policy")

3.3 RDS — Five Optimisation Levels

Find over-provisioned RDS instances:

# rds_rightsizer.py
import boto3
from datetime import datetime, timedelta

rds = boto3.client('rds')
cw  = boto3.client('cloudwatch')


def find_oversized_rds():
    instances  = rds.describe_db_instances()['DBInstances']
    candidates = []

    for inst in instances:
        iid    = inst['DBInstanceIdentifier']
        iclass = inst['DBInstanceClass']

        stats = cw.get_metric_statistics(
            Namespace='AWS/RDS',
            MetricName='CPUUtilization',
            Dimensions=[{'Name': 'DBInstanceIdentifier', 'Value': iid}],
            StartTime=datetime.utcnow() - timedelta(days=14),
            EndTime=datetime.utcnow(),
            Period=1209600,
            Statistics=['Average', 'Maximum']
        )['Datapoints']

        if not stats:
            continue

        avg_cpu = stats[0]['Average']
        max_cpu = stats[0]['Maximum']

        if avg_cpu < 20 and max_cpu < 50:
            candidates.append({
                'id':       iid,
                'class':    iclass,
                'avg_cpu':  round(avg_cpu, 1),
                'max_cpu':  round(max_cpu, 1),
                'engine':   inst['Engine'],
            })

    return candidates


for c in find_oversized_rds():
    print(f"  {c['id']}  {c['class']}  avg:{c['avg_cpu']}%  max:{c['max_cpu']}%  engine:{c['engine']}")

3.4 DynamoDB — On-Demand vs Provisioned Decision

On-demand is convenient but can be 3–5× more expensive than provisioned for predictable workloads. Provisioned with auto-scaling covers most cases at significantly lower cost.

# dynamodb_mode_advisor.py
import boto3
from datetime import datetime, timedelta

dynamodb = boto3.client('dynamodb')
cw       = boto3.client('cloudwatch')


def analyse_table_billing(table_name: str) -> dict:
    table = dynamodb.describe_table(TableName=table_name)['Table']
    mode  = table.get('BillingModeSummary', {}).get('BillingMode', 'PROVISIONED')

    stats = {}
    for metric in ['ConsumedReadCapacityUnits', 'ConsumedWriteCapacityUnits']:
        data = cw.get_metric_statistics(
            Namespace='AWS/DynamoDB',
            MetricName=metric,
            Dimensions=[{'Name': 'TableName', 'Value': table_name}],
            StartTime=datetime.utcnow() - timedelta(days=30),
            EndTime=datetime.utcnow(),
            Period=86400,
            Statistics=['Average', 'Maximum']
        )['Datapoints']
        if data:
            avg  = sum(d['Average'] for d in data) / len(data)
            peak = max(d['Maximum'] for d in data)
            stats[metric] = {'avg': round(avg, 1), 'peak': round(peak, 1)}

    if mode == 'PAY_PER_REQUEST':
        avg_rcu = stats.get('ConsumedReadCapacityUnits', {}).get('avg', 0)
        avg_wcu = stats.get('ConsumedWriteCapacityUnits', {}).get('avg', 0)

        if avg_rcu > 2000 or avg_wcu > 500:
            return {
                'table':          table_name,
                'current_mode':   'PAY_PER_REQUEST',
                'recommendation': 'Switch to PROVISIONED with auto-scaling',
                'reason': f'Avg {avg_rcu:.0f} RCU/s and {avg_wcu:.0f} WCU/s — predictable pattern',
            }

    return {'table': table_name, 'current_mode': mode, 'recommendation': 'No change needed'}


for table in dynamodb.list_tables()['TableNames']:
    r = analyse_table_billing(table)
    if r['recommendation'] != 'No change needed':
        print(f"  {r['table']}: {r['recommendation']}")

3.5 Data Transfer — The Three Main Waste Patterns

Data transfer charges are often the most confusing line item on an AWS bill. Here are the the three main patterns and their fixes:

Cross-AZ traffic (most common, most fixable): services in different AZs incur $0.01/GB in each direction. The fix is to use topology-aware routing on Kubernetes Services or ensure your application tier and database tier use the same AZ placement.

NAT Gateway charges for internal AWS traffic: S3, ECR, DynamoDB, and SQS traffic that routes through NAT Gateway incurs $0.045/GB. The fix: VPC endpoints eliminate this entirely.

Inter-region replication that compliance doesn't require: audit your S3 replication rules quarterly against actual compliance requirements.

# Find S3 buckets with active replication
for bucket in $(aws s3api list-buckets --query 'Buckets[*].Name' --output text); do
    result=$(aws s3api get-bucket-replication --bucket "$bucket" 2>&1)
    if ! echo "$result" | grep -q "ReplicationConfigurationNotFoundError"; then
        echo "  $bucket — replication active, verify compliance requirement"
    fi
done

Part 4: The 30-Day Optimisation Sprint

This sprint produces measurable savings in the first month. It's designed for a single engineer with two to four hours per week of dedicated FinOps time.

Week 1 – Visibility: enable CUR, set up the Athena table, run the three day-one queries, screenshot the results as your baseline, tag 100% of running EC2 and RDS instances, and identify your top three cost drivers with a documented hypothesis for each.

Week 2 – Quick wins: deploy the orphaned resource reporter Lambda, apply S3 lifecycle policies to your three largest buckets, run the idle instance finder and stop anything below 1% average CPU with no owner objection, and add VPC endpoints for S3, ECR, and DynamoDB.

Week 3 – Right-sizing: run the EC2 rightsizing analyser, downsize the three highest-confidence candidates (non-production first), run the RDS rightsizing script, and find read replicas serving minimal traffic and decommission them.

Week 4 – Alerting and automation: deploy the hourly budget monitor Lambda, configure the three-tier alert routing, set up the weekly waste reporter, add the Infracost GitHub Action to your infrastructure repository, and schedule a monthly 30-minute FinOps review meeting.

Expected outcome after 30 days: 15–25% reduction in monthly AWS spend, documented evidence of every change, and a recurring process that prevents the same waste from accumulating again.

Best Practices Summary

✅ Do: Set up CUR + Athena before any other monitoring. Cost Explorer is a starting point, while CUR is the source of truth.

✅ Do: Enforce tagging in Terraform or CloudFormation. Process-based tagging decays, but infrastructure-enforced tagging is permanent.

✅ Do: Run the idle instance finder and waste reporter weekly. Waste accumulates continuously. A weekly report keeps the pile small.

✅ Do: Use the three-tier alert model. One alert channel with everything in it creates fatigue and gets muted.

✅ Do: Work through the EC2 optimisation levers in order. Right-sizing before Savings Plans prevents locking in waste at a discount.

✅ Do: Check DynamoDB billing mode against actual usage patterns quarterly.

❌ Don't: Delete untagged resources without investigation. Untagged doesn't mean unused, it means unclaimed.

❌ Don't: Apply aggressive S3 lifecycle policies without auditing access patterns first. Glacier retrieval fees can exceed Standard storage costs if data is accessed more frequently than expected.

❌ Don't: Run the waste reporter Lambda with auto-deletion enabled on its first deployment. Run in report-only mode for two weeks to validate the output before adding deletion logic.

Resources

• AWS Cost and Usage Report Data Dictionary: Column reference for all CUR Athena queries in this guide

• AWS Cost Explorer API Reference: Full reference for the Python boto3 cost queries

• AWS Compute Optimizer: ML-powered right-sizing recommendations, useful as a cross-check against the manual analyser scripts

• Amazon DynamoDB Pricing: The definitive reference for the provisioned vs on-demand cost calculation in Section 3.4

• AWS Instance Scheduler: The official AWS solution for tag-based EC2 and RDS scheduling

• FinOps Foundation Framework: The practitioner framework that defines the Inform, Optimise, Operate cycle this guide implements

• Companion Repository: All scripts, Lambda functions, and Terraform modules from this guide

You might even know the basic definition, but knowing what OpenTelemetry is vs how it actually works are two different things.

By the end of this guide, you'll understand how OpenTelemetry works end-to-end, from the moment a request enters your application to the moment you can see it in your observability backend. You'll learn how traces, spans, context propagation, and exporters all fit together into one pipeline.

If you're completely new to OpenTelemetry, don't worry: the next section will get you up to speed before we go any further.

Table of Contents

• What is OpenTelemetry?

• How OpenTelemetry Works

  • Step 1: Instrument Your Application

  • Step 2: OpenTelemetry Creates Telemetry Signals

  • Step 3: Traces Follow Requests Through Your Application

  • Step 4: Context Propagation Connects Work Across Services

  • Step 5: The OpenTelemetry SDK Processes the Telemetry

  • Step 6: Exporters Send the Telemetry

  • Step 7: The OpenTelemetry Collector Receives and Processes the Data

  • Step 8: An Observability Backend Stores and Analyzes the Telemetry

• Putting the OpenTelemetry Flow Together

• Do You Need Every OpenTelemetry Component?

• Why Use OpenTelemetry?

• Conclusion

What is OpenTelemetry?

OpenTelemetry is an open-source, vendor-neutral observability framework. It gives you a standard way to instrument your application, generate telemetry data, and export that data to any observability backend of your choice.

Before OpenTelemetry, every monitoring tool had its own way of collecting data. If you used Datadog, you’ll have to instrument your app the Datadog way. If you switched to Jaeger, you started over. OpenTelemetry changed that by giving you one standard way to instrument your application, regardless of which backend you use

[!NOTE] OpenTelemetry is not a monitoring platform, dashboard, or data store. It provides the tools and standards for collecting and exporting telemetry from your application to an observability backend, where the data can be stored, queried, and analyzed.

The data OpenTelemetry collects is called telemetry. It's the information your application produces about itself as it runs, and it comes in three forms:

• Traces tell you how a request traveled through your system.

• Metrics give you numbers, like how many requests per second your app is handling, or how much memory it's using.

• Logs are timestamped records of specific events that happened inside your application.

How OpenTelemetry Works

When a request hits your application, a lot happens behind the scenes. OpenTelemetry's job is to capture all of that activity (the traces, metrics, and logs) and send them to the right place.

Here’s what it looks like:

Each stage has a specific job. Let's walk through them one by one.

Step 1: Instrument Your Application

Before OpenTelemetry can capture anything, your application needs to be instrumented. Instrumentation is simply the process of adding code that tells OpenTelemetry what to watch and what to record.

There are two ways to instrument your application: automatically or manually.

1. Automatic instrumentation

This is the easiest one to start with. You add a library to your project, and it instruments your application for you with no changes to your existing code.

For example, if you're running a Node.js Express app, you can add the OpenTelemetry auto-instrumentation package, and it will automatically start capturing incoming HTTP requests, outgoing calls, database queries, and more.

Here's what that setup looks like:

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const sdk = new NodeSDK({
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Once this runs before your app starts, OpenTelemetry begins capturing telemetry automatically. For a complete setup guide, see Getting started with OpenTelemetry in Node.js.

2. Manual instrumentation

Automatic instrumentation covers a lot, but it can't capture everything that happens inside your own code. If you want to track what happens inside a specific function, like how long it takes to process a payment or validate a user, you need to add that yourself.

Here's a simple example. Let’s say you have a function that processes an order:

function processOrder(orderId) {
  // processing logic
}

With manual instrumentation, you wrap it like this:

const { trace } = require('@opentelemetry/api');

const tracer = trace.getTracer('order-service');

function processOrder(orderId) {
  return tracer.startActiveSpan('processOrder', (span) => {
    // processing logic

    span.end();
  });
}

What happens is that you created a span. That span now records when processOrder started, when it ended, and how long it took. You'll learn more about spans in Step 3.

For the full manual instrumentation reference, see OpenTelemetry JavaScript instrumentation.

Step 2: OpenTelemetry Creates Telemetry Signals

Once your application is instrumented, OpenTelemetry starts producing telemetry data about what your application is doing. That data comes in three forms, called signals, which we've already briefly talked about: traces, metrics, and logs. Each signal answers a different kind of observability question.

Traces show you how a request moved through your system, which services it touched, and how long each step took. Metrics give you numbers over time, things like request rate, error rate, and memory usage. Logs are timestamped records of specific events that happened inside your application.

Here's a quick comparison:

You don't have to choose between them. In practice, you'll use all three together. A metric tells you something is wrong, a trace shows you where, and a log tells you exactly what happened.

Step 3: Traces Follow Requests Through Your Application

When a user sends a request to your application, that request usually touches multiple services before a response comes back. A trace is the complete record of that journey, from the moment the request enters your system to the moment it finishes.

A trace is actually made up of smaller units called spans. Each span represents one operation, like an API call, a database query, or a function execution, and together they give you the full picture of what happened.

Every trace gets a unique trace ID, and every span gets its own span ID. The trace ID is what links all the spans together. No matter how many services a request passes through, they all share the same trace ID, so you can follow the request from start to finish in your observability backend.

Here's a simple example. A user places an order, and the request flows through four services:

Each span has a start time and an end time, so you can see how long each operation took. If something slowed down or failed, you can pinpoint exactly where it happened just by looking at the spans.

Step 4: Context Propagation Connects Work Across Services

In Step 3, you saw how a single trace is made up of spans from multiple services. But here's a question you need to ask: how does OpenTelemetry know that a span in your payment service belongs to the same trace as a span in your order service?

Without something connecting them, each service would record its own spans independently. Your API gateway would see one operation, your order service would see another, and your payment service would see a third. They'd look like completely separate requests with no relationship to each other, which makes debugging across services nearly impossible.

That's where context propagation comes in. As a request moves from one service to another, OpenTelemetry attaches the trace context to it, typically as HTTP headers. That context carries the trace ID and the parent span ID, so every service that handles the request knows which trace it belongs to and where it sits in the chain.

Here's what that looks like in practice:

All three services share the same trace ID. That's what lets your observability backend connect the spans together into one complete trace.

OpenTelemetry doesn't invent its own rules for this. It follows the W3C Trace Context standard, a widely adopted specification that defines how trace context should be formatted and passed between services, so it works consistently across different languages, frameworks, and vendors.

The good news is that if you're using automatic instrumentation, context propagation happens automatically. OpenTelemetry handles the headers for you, so you don't have to think about it unless you're working with a custom transport or a non-standard setup.

Step 5: The OpenTelemetry SDK Processes the Telemetry

At this point, OpenTelemetry is capturing telemetry and keeping traces connected across services. But between the moment a span is created and the moment it leaves your application, something has to process it. That's the SDK's job.

When your instrumented code creates a span, it does that through the OpenTelemetry API. The API is what you interact with as a developer, things like trace.getTracer() and tracer.startActiveSpan(). But the API alone doesn't process or send anything. It needs the SDK behind it to actually do the work.

Once the SDK receives the telemetry, it runs it through a processor. The processor is responsible for things like batching spans together before sending them, adding extra attributes, or filtering out data you don't need. The most common one you'll see is the BatchSpanProcessor, which groups spans and exports them in batches rather than one at a time, making it more efficient in production.

Before the processor even runs, the SDK also handles sampling. Sampling lets you control how much telemetry you actually collect. In high-traffic applications, recording every single span would generate an enormous amount of data. With sampling, you can tell the SDK to only capture a percentage of traces, which keeps your costs and data volume manageable without losing visibility.

Once the processor is done, it hands the data to the exporter, which is what actually sends it to its destination. You'll see how that works in the next step.

Step 6: Exporters Send the Telemetry

The exporter's job is simple: take the telemetry the SDK prepared and send it to whatever destination you've configured.

OpenTelemetry uses OTLP, the OpenTelemetry Protocol, to transport telemetry data. It's a standard wire protocol designed specifically for transmitting traces, metrics, and logs, and it runs over either HTTP or gRPC.

[!NOTE] OTLP and OpenTelemetry are not the same thing. OpenTelemetry is the full framework, covering instrumentation, the SDK, the Collector, and more. OTLP is just the protocol it uses to transport data.

Although OTLP is the default, not every exporter uses it. Some exporters send data directly to specific backends in their own format, like Jaeger or Prometheus. So depending on your setup, you might use an OTLP exporter to send data to a Collector or backend, or a vendor-specific exporter to send it directly."

Step 7: The OpenTelemetry Collector Receives and Processes the Data

The OpenTelemetry Collector is a standalone service that sits between your application and your observability backend. It receives telemetry data, processes it, and forwards it to one or more destinations.

Using the Collector is common but not mandatory. You can configure your exporter to send data directly to your backend and skip the Collector entirely. But in most production setups, teams add a Collector because it gives them a central place to manage telemetry, without touching application code.

The Collector has three stages:

• Receivers accept incoming telemetry from your applications, typically over OTLP.

• Processors transform the data at the Collector level, things like batching spans, filtering out noise, or adding attributes before forwarding.

• Exporters send the processed data to your backend, or multiple backends if needed.

Here's a minimal Collector configuration:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:

exporters:
  otlphttp:
    endpoint: https://your-backend.com

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

This config accepts traces over gRPC, batches them for efficiency, and forwards them to an observability backend over HTTP.

The Collector can also receive data from multiple applications simultaneously and route it to one or more destinations. So instead of each application shipping telemetry directly to your backend, they all send it to the Collector, and the Collector handles the rest.

For the full configuration, see the OpenTelemetry Collector configuration docs.

Step 8: An Observability Backend Stores and Analyzes the Telemetry

This is where OpenTelemetry's job ends. Once your telemetry leaves the Collector, it arrives at your observability backend.

The backend is what stores your data, lets you query it, and gives you the dashboards and alerts you actually interact with day to day. OpenTelemetry doesn't provide any of that. It gets the data there, and the backend does the rest.

A few popular backends that support OpenTelemetry natively:

• Open-source: Jaeger, Prometheus, Grafana Tempo

• Commercial: Datadog, New Relic, Honeycomb, Dynatrace, Elastic, Lightstep, Grafana Cloud, Middleware.

Once your data is in the backend, you can search through traces to debug a slow request, build dashboards to monitor your application's health, and set up alerts when something goes wrong.

Putting the OpenTelemetry Flow Together

Let’s assume a user initiates a bank transfer on a mobile banking app. The request hits your API gateway, and because your application is instrumented, OpenTelemetry immediately starts capturing what’s happening. It creates a span for the incoming request and assigns it a trace ID.

As the request moves to the authentication service, context propagation carries that trace ID along in the request headers. The authentication service creates its own span and attaches it to the same trace. The same thing happens when the authentication service calls the transaction service, and when the transaction service hits the database to process the transfer. Four services and four spans, with one trace ID connecting them all.

Meanwhile, the SDK processes the telemetry in the background, runs the spans through the batch processor, and hands them to the exporter. The exporter packages everything into OTLP and sends it to the Collector, which applies your processing rules and forwards it to your observability backend.

Here’s a summary of every component involved in that flow:

From that single transfer request, you now have a complete trace in your backend. When you open your dashboard and search the trace ID, you'll see every service, every span, and every millisecond of that transaction laid out in front of you.

Do You Need Every OpenTelemetry Component?

To be honest, you don’t need every component to get started with OpenTelemetry. The pipeline you’ve seen throughout this article is the full setup, but not every team uses all of that.

1. Without the Collector: Your exporter sends telemetry directly to your backend with nothing in between. Works well for smaller projects or when you're just getting started.

2. With the Collector: The more common production setup. Teams add the Collector when they need more control, like routing telemetry to multiple backends, filtering sensitive data, or managing telemetry from dozens of services in one place.

The Collector is powerful, but it’s not mandatory. Start without it if your setup is simple, and add it when you actually need it.

Why Use OpenTelemetry?

You've now seen how every piece of OpenTelemetry fits together. Here's why it's worth using:

• Vendor-neutral instrumentation: Before OpenTelemetry, switching observability tools meant you had to re-instrument your entire application from scratch. With OpenTelemetry, you instrument once and switch backends freely.

• Consistent telemetry across services and languages: Your backend might be in Go, your microservices in Python, and your data pipeline in Java. OpenTelemetry has SDKs for all of them, and they all produce telemetry in the same format, so your whole stack speaks the same language.

• Correlated observability signals: Traces, metrics, and logs all flow through the same pipeline. So when something goes wrong, a spike in your metrics leads you to a trace, and that trace points you to the exact log entry where things broke down.

• It's becoming the industry standard: Most observability backends already support OpenTelemetry natively. Instead of learning a vendor-specific instrumentation approach every time you adopt a new tool, you learn OpenTelemetry once and it works everywhere.

Conclusion

OpenTelemetry gives you a standard way to instrument your application, collect telemetry, and ship it to any backend you choose, without locking you into a specific vendor or tool.

If you remember nothing else from this article, remember this: you instrument your application, generate telemetry, process it, export it, and analyze it. Every step has a component behind it, and now you know what each one does.

If you're just getting started, you don't need to set everything up at once. Start with instrumentation, get your telemetry flowing to a backend, and add the Collector when you need it. You can always add more as your needs grow.

If you found this helpful, I'd love to connect. You can find me on LinkedIn or X. Feel free to reach out if you have questions or just want to talk about observability and developer tooling.

And while many SaaS tools can monitor your site, they often charge high monthly fees for simple alerts.

My goal with this article is to help you stop paying those expensive fees by showing you a powerful, free, open-source alternative called Uptime Kuma.

In this guide, you'll learn how to use Docker to deploy Uptime Kuma safely on a local Ubuntu machine.

By the end of this tutorial, you'll have set up your own private server monitoring dashboard in less than 10 minutes and created an automated Discord alert to ping your phone if your website goes offline.

Table of Contents

• Prerequisites

• Step 1: Update Packages and Prepare the Firewall

• Step 2: Create the Docker Compose File

• Step 3: Start the Application

• Step 4: Access the Dashboard

• Step 5: Use Case – Monitor a Website and Send Discord Alerts

• Conclusion

Prerequisites

Before you start, make sure you have:

• An Ubuntu machine (like a local server, VM, or desktop).

• Docker and Docker Compose installed.

• Basic knowledge of the Linux terminal.

Step 1: Update Packages and Prepare the Firewall

First, you'll want to make sure your system has the newest updates. Then, you'll install the Uncomplicated Firewall (UFW) and open the network "door" (port) that Uptime Kuma uses for the dashboard. You'll also need to allow SSH so you don't lock yourself out.

Run these commands in your terminal:

1. Update your packages:

sudo apt update && sudo apt upgrade -y

1. Install the firewall:

sudo apt install ufw -y

1. Allow SSH and open port 3001:

sudo ufw allow ssh
sudo ufw allow 3001/tcp

1. Enable the firewall:

sudo ufw enable
sudo ufw reload

Step 2: Create the Docker Compose File

Using a docker-compose.yml file is the professional way to manage Docker containers. It keeps your setup organised in one single place.

To start, create a new folder for your project and enter it:

mkdir uptime-kuma && cd uptime-kuma

Then create the configuration file:

nano docker-compose.yml

Paste the following code into the editor:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"

Note: The ./data:/app/data line is very important. It saves your database in a normal folder on your machine, making it easy to back up later.

Finally, save and exit: Press CTRL + X, then Y, then Enter.

Step 3: Start the Application

Now, tell Docker to read your file and start the monitoring service in the background.

docker compose up -d

How to verify: Docker will download the files. When it finishes, your terminal should print Started uptime-kuma.

Step 4: Access the Dashboard

To access the dashboard, first open your web browser and go to http://localhost:3001 (or your machine's local IP address).

When asked to choose the database, select SQLite. It's simple, fast, and requires no extra setup.

Then create an account and choose a secure admin username and password.

Step 5: Use Case – Monitor a Website and Send Discord Alerts

Now you'll put Uptime Kuma to work by monitoring a live website and setting up an alert. Just follow these steps:

1. Click Add New Monitor.

2. Set the Monitor Type to HTTP(s).

3. Give it a Friendly Name (e.g., "My Blog") and enter your website's URL.

Pro-Tip: How to Fix "Down" Errors (Bot Protection)

If your site uses strict security, it might block Uptime Kuma and say your site is "Down" with a 403 Forbidden error.

The Fix: Scroll down to Advanced, find the User Agent box, and paste this text to make Uptime Kuma look like a normal Chrome browser:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36

Add a Discord Alert

To get a message on your phone when your site goes down:

1. On the right side of the monitor screen, click Setup Notification.

2. Select Discord from the dropdown list.

3. Paste a Discord Webhook URL (you can create one in your Discord server settings under Integrations).

4. Click Test to receive a test ping, then click Save.

Conclusion

Congratulations! You just took control of your server health. By deploying Uptime Kuma, you replaced an expensive SaaS subscription with a powerful, free monitoring tool that alerts you the second a project goes offline.

Let’s connect! I am a developer and technical writer specialising in writing step-by-step guides and workflows. You can find my latest projects on my Technical Writing Portfolio or reach out to me directly on LinkedIn.

That’s where application monitoring tools (APM) come in. They show you what’s working, what’s slow, and what’s failing, all in one place.

Here are five of the best tools developers use today. I’ll walk you through what they do, why they’re good, and how you might use them in your projects.

New Relic

New Relic is one of the oldest players in this space. It’s great for full-stack observability, meaning you can see everything from your frontend JavaScript errors to database query times.

Imagine your Node.js backend is running slow. You deploy a new endpoint, and your API response times go up.

With New Relic, you can trace that slowdown to a specific function call or database query. It shows you performance metrics, transaction traces, error rates, and alerts in real time.

For beginners, New Relic’s dashboard can feel overwhelming. But once you get used to it, you’ll see why large teams rely on it for 24/7 monitoring.

If you want one tool that does application performance monitoring (APM), infrastructure monitoring, browser monitoring, and even mobile monitoring in one place, New Relic is your tool.

New Relic is a paid tool, but it comes with a generous free tier for you to start exploring its features. Here is the full pricing plan.

Datadog

Datadog started as an infrastructure monitoring tool but has become a powerhouse for developers, too.

It integrates easily with AWS, Azure, GCP, Kubernetes, Docker, and almost any service you use.

Assume you deploy a Flask app on Kubernetes. Suddenly, users report timeouts.

In Datadog, you can view your pod metrics, CPU and memory usage, container logs, and APM traces all in one timeline. You’ll quickly see if your pod was OOMKilled, if your database had connection spikes, or if your app code itself was slow.

Datadog also shines in alerting. You can set up alerts like:

If average response time > 2000ms for 5 minutes, send Slack alert to #devops

This keeps your team proactive instead of reactive.

It also integrates behavioural targeting data from user sessions and performance metrics, helping product teams understand how performance issues affect user behaviour and conversion.

If you want seamless cloud-native monitoring with powerful dashboards, alerts, and security integrations, Datadog is your solution.

Datadog is free for up to five hosts, so the free plan would be sufficient for solo developers / small teams to get started. Here is the full pricing plan.

Prometheus + Grafana

Prometheus is an open-source monitoring system that scrapes metrics from your app, stores them in a time-series database, and lets you query them with PromQL.

Grafana is the dashboard layer on top. Together, they’re like peanut butter and jelly for monitoring.

Here’s how you can use them. Suppose you have a Go API exposing metrics on /metrics using the Prometheus client library. Prometheus scrapes that endpoint every 15 seconds. You can query:

rate(http_requests_total[5m])

This shows you the average requests per second over the last 5 minutes.

Then, in Grafana, you build dashboards to visualise that data with graphs, gauges, and alerts. Many teams use Grafana for system health dashboards displayed on TVs in the office.

Prometheus is free, flexible, and used heavily with Kubernetes because of its service discovery features. But it requires setup and maintenance compared to SaaS tools.

If you want a powerful open-source solution with custom dashboards and PromQL querying, Prometheus + Graphana is your solution.

Sentry

Unlike New Relic and Datadog, Sentry focuses on error and performance monitoring.

It’s a favourite for frontend and backend developers because it gives detailed stack traces, breadcrumbs, and release tracking.

For example, say your React app throws an error when users click “Submit”. Sentry captures:

• The exact error and message

• The function and file that caused it

• The user’s browser and OS

• The recent events (breadcrumbs) before the error

This helps you reproduce and fix the issue fast.

On backend apps, it works similarly to the frontend. You can integrate Sentry with Django, Express, Flask, or almost any framework to capture exceptions and performance bottlenecks.

If you want to track bugs and performance issues in real time, with deep context to debug them quickly, Sentry is your solution.

Sentry is free for a single user with minimal features. Here is the full pricing plan.

PostHog

PostHog is a modern open-source tool for product analytics, session recording, feature flags, and application monitoring.

Unlike traditional APM tools, PostHog focuses on understanding how users interact with your app.

For example, suppose users aren’t completing your signup flow. With PostHog, you can:

• Record user sessions to see exactly where they drop off

• Track funnel conversion rates step by step

• Analyse feature usage to prioritise improvements

• Use behavioural targeting to trigger in-app prompts for specific user segments

You can self-host PostHog on your infrastructure or use their cloud offering. Developers like it because it combines product analytics and user insights without sending data to third parties if self-hosted.

If you want to combine product analytics, session replays, feature flags, and event-based monitoring in one tool to understand and improve user behaviour in your app, Posthog is your solution.

PostHog has a generous free tier for up to 1 million events per month. Paid plans start from $0.00045 per event after the free tier, with enterprise features and advanced plugins. So there is no fixed pricing and you pay as your application scales.

So which APM tool should you pick?

If you’re a solo developer or a small team, start with Sentry for errors and Prometheus + Grafana for open-source metrics.

As you grow and need unified monitoring with alerts and APM, tools like Datadog or New Relic become valuable.

If you want full control of your data with modern APM features and pricing that scales with your app, Posthog is your solution.

Conclusion

Remember, monitoring isn’t just about fixing failures. It’s about learning how your app behaves under real usage. This helps you optimise performance, spot bottlenecks, and build resilient software that users trust.

Take some time to integrate at least basic monitoring into your apps. Even simple HTTP request metrics and error alerts can save you hours of blind debugging later.

Hope you found this article useful. Get in touch with me on LinkedIn.

This article focuses specifically on the first component – data collection and reporting – and shows you how to build a monitoring SDK from scratch. By the end of this article, you'll understand how to gather critical metrics about your application's performance, capture errors, track user behavior, and implement efficient reporting mechanisms.

Below is an outline of the topics we'll cover:

                       ┌────────────────────┐
                       │  Data Collection   │
                       └──────────┬─────────┘
                                  │
         ┌─────────────────┬──────┴──────────────┐
         │                 │                     │
┌────────┴────────┐ ┌──────┴──────┐     ┌────────┴────────┐
│ Error Monitoring │ │ Performance  │     │ Behavior       │
│                  │ │ Monitoring   │     │ Monitoring     │
└────────┬─────────┘ └──────┬──────┘     └────────┬────────┘
         │                  │                     │
┌────────┴────────┐ ┌──────┴──────────┐  ┌────────┴────────┐
│                 │ │                 │  │                 │
│ Resource Loading│ │ Resource Loading│  │     UV, PV      │
│     Errors      │ │      Time       │  │                 │
│                 │ │                 │  │  Page Access    │
│   JS Errors     │ │  API Request    │  │     Depth       │
│                 │ │     Time        │  │                 │
│ Promise Errors  │ │                 │  │   Page Stay     │
│                 │ │   DNS, TCP,     │  │    Duration     │
│ Custom Errors   │ │ First-byte Time │  │                 │
│                 │ │                 │  │  Custom Event   │
│                 │ │   FPS Rate      │  │    Tracking     │
│                 │ │                 │  │                 │
│                 │ │ Cache Hit Rate  │  │   User Clicks   │
│                 │ │                 │  │                 │
│                 │ │  First Screen   │  │ Page Navigation │
│                 │ │  Render Time    │  │                 │
│                 │ │                 │  └─────────────────┘
│                 │ │  FP, FCP, LCP,  │
│                 │ │   FID, LCS,     │
│                 │ │ DOMContentLoaded│
│                 │ │    onload       │
└─────────────────┘ └─────────────────┘

Once data is collected, it needs to be reported to your backend systems for processing and analysis:

                  ┌─────────────────┐
                  │ Data Reporting  │
                  └────────┬────────┘
                           │
          ┌────────────────┴────────────────┐
          │                                 │
┌─────────────────────┐           ┌─────────────────────┐
│  Reporting Methods  │           │  Reporting Timing   │
└──────────┬──────────┘           └──────────┬──────────┘
           │                                 │
     ┌─────┼─────┐               ┌───────────┼───────────┐
     │     │     │               │           │           │
┌────┴───┐ │ ┌───┴────┐ ┌────────┴────────┐ │ ┌─────────┴─────────┐
│  xhr   │ │ │ image  │ │ requestIdle     │ │ │ Upload when cache │
└────────┘ │ └────────┘ │ Callback/       │ │ │ limit is reached  │
           │            │ setTimeout      │ │ └───────────────────┘
     ┌─────┴─────┐      └─────────────────┘ │
     │ sendBeacon│                          │
     └───────────┘                ┌─────────┴──────────┐
                                  │    beforeunload    │
                                  └────────────────────┘

Prerequisites

Before diving into this tutorial, you should have:

• Basic knowledge of JavaScript and web development

• Familiarity with browser APIs and event handling

• Understanding of asynchronous programming concepts

• Some experience with performance optimization concepts

Since theoretical knowledge alone can be difficult to grasp, I've created a simple monitoring SDK that implements these technical concepts. You can use it to create simple demos and gain a better understanding. Reading this article while experimenting with the SDK will provide the best learning experience.

Table of Contents

1. Collect Performance Data

   • FP (First Paint)

   • FCP (First Contentful Paint)

   • LCP (Largest Contentful Paint)

   • CLS (Cumulative Layout Shift)

   • DOMContentLoaded and Load Events

   • First Screen Rendering Time

   • API Request Timing

   • Resource Loading Time and Cache Hit Rate

   • Browser Back/Forward Cache

   • FPS

   • Vue Router Change Rendering Time

2. Error Data Collection

   • Resource Loading Errors

   • JavaScript Errors

   • Promise Errors

   • Sourcemap

   • Vue Errors

3. Behavior Data Collection

   • PV and UV

   • Page Stay Duration

   • Page Access Depth

   • User Clicks

   • Page Navigation

   • Vue Router Changes

4. Data Reporting

   • Reporting Methods

   • Reporting Timing

5. Summary

6. References

   • Performance Monitoring

   • Error Monitoring

   • Behavior Monitoring

Collect Performance Data

Monitoring performance is crucial for providing users with a smooth, responsive experience. Slow websites lead to higher bounce rates and reduced conversions. By collecting performance metrics, you can identify bottlenecks, optimize critical rendering paths, and improve overall user satisfaction.

The Chrome developer team has proposed a series of metrics to monitor page performance, each measuring a different aspect of the user experience:

• FP (First Paint) – Time from when the page starts loading until the first pixel is painted on the screen (essentially the white screen time)

• FCP (First Contentful Paint) – Time from page load start until any part of page content is rendered

• LCP (Largest Contentful Paint) – Time from page load start until the largest text block or image element completes rendering

• CLS (Cumulative Layout Shift) – Cumulative score of all unexpected layout shifts occurring between page load start and when the page's lifecycle state becomes hidden

We can obtain these four performance metrics through PerformanceObserver (they can also be retrieved via performance.getEntriesByName(), but this method doesn't provide real-time notifications when events occur). PerformanceObserver is a performance monitoring interface used to observe performance measurement events.

Let's examine each of these metrics in detail and see how to implement them in our SDK.

FP (First Paint)

First Paint (FP) marks the point when the browser renders anything visually different from what was on the screen before navigation. This could be a background color change or any visual element that indicates to the user that the page is loading.

Implementation code:

const entryHandler = (list) => {        
    for (const entry of list.getEntries()) {
        if (entry.name === 'first-paint') {
            observer.disconnect()
        }
        console.log(entry)
    }
}

const observer = new PerformanceObserver(entryHandler)
// The buffered property indicates whether to observe cached data, 
// allowing observation even if the monitoring code is added after the event occurs
observer.observe({ type: 'paint', buffered: true })

This code creates a new PerformanceObserver that watches for 'paint' type events. When the first-paint event occurs, it logs the entry information and disconnects the observer since we only need to capture this event once per page load. The observer's observe() method is configured with buffered: true to ensure we can catch paint events that occurred before our code runs.

The FP measurement output:

{
    duration: 0,
    entryType: "paint",
    name: "first-paint",
    startTime: 359, // FP time
}

The startTime value represents the paint timing we need. This value (359ms in this example) tells us how long it took from the start of navigation until the first visual change appeared on screen. You can use this metric to optimize your critical rendering path and reduce the time users spend looking at a blank screen.

FCP (First Contentful Paint)

FCP (First Contentful Paint) refers to the time from page load start until any part of page content is rendered. The "content" in this metric refers to text, images (including background images), <svg> elements, and non-white <canvas> elements.

To provide a good user experience, the FCP score should be kept under 1.8 seconds.

The measurement code:

const entryHandler = (list) => {        
    for (const entry of list.getEntries()) {
        if (entry.name === 'first-contentful-paint') {
            observer.disconnect()
        }

        console.log(entry)
    }
}

const observer = new PerformanceObserver(entryHandler)
observer.observe({ type: 'paint', buffered: true })

We can get the value of FCP via the above code:

{
    duration: 0,
    entryType: "paint",
    name: "first-contentful-paint",
    startTime: 459, // fcp 时间
}

The startTime value is the painting time we need.

LCP (Largest Contentful Paint)

LCP (Largest Contentful Paint) refers to the time from page load start until the largest text block or image element completes rendering. The LCP metric reports the relative render time of the largest visible image or text block in the viewport, measured from when the page first begins loading.

A good LCP score should be kept under 2.5 seconds.

The measurement code:

const entryHandler = (list) => {
    if (observer) {
        observer.disconnect()
    }

    for (const entry of list.getEntries()) {
        console.log(entry)
    }
}

const observer = new PerformanceObserver(entryHandler)
observer.observe({ type: 'largest-contentful-paint', buffered: true })

We can get the value of LCP via the above code:

{
    duration: 0,
    element: p,
    entryType: "largest-contentful-paint",
    id: "",
    loadTime: 0,
    name: "",
    renderTime: 1021.299,
    size: 37932,
    startTime: 1021.299,
    url: "",
}

The startTime value is the painting time we need. And element refers to the element being painted during LCP.

The difference between FCP and LCP is: FCP event occurs when any content is painted, while LCP event occurs when the largest content finishes rendering.

LCP considers these elements:

• <img> elements

• <image> elements inside <svg>

• <video> elements (using poster images)

• Elements with background images loaded via the url() function (not using CSS gradients)

• Block-level elements containing text nodes or other inline-level text elements

CLS (Cumulative Layout Shift)

CLS (Cumulative Layout Shift) refers to the cumulative score of all unexpected layout shifts occurring between page load start and when the page's lifecycle state becomes hidden.

An "unexpected layout shift" occurs when elements on a page move around without user interaction. Common examples include:

• A banner or ad suddenly appearing at the top of the page, pushing content down

• A font loading and changing the size of text

• An image loading without predefined dimensions, expanding and pushing other content out of the way

• A button appearing below where a user is about to click, causing them to click the wrong element

These shifts are frustrating for users and lead to accidental clicks, lost reading position, and overall poor user experience. CLS helps quantify this problem so you can identify and fix problematic elements.

The layout shift score is calculated as follows:

layout shift score = impact score × distance score

The impact score measures how unstable elements affect the visible area between two frames. The distance score is calculated by taking the greatest distance any unstable element has moved (either horizontally or vertically) and dividing it by the viewport's largest dimension (width or height, whichever is greater).

CLS is the sum of all layout shift scores.

A layout shift occurs when a DOM element changes position between two rendered frames, as shown below:

In the above diagram, the rectangle moves from the top-left to the right side, counting as one layout shift. In CLS terminology, there's a concept called "session window": one or more individual layout shifts occurring in rapid succession, with less than 1 second between each shift and a maximum window duration of 5 seconds.

For example, in the second session window shown above, there are four layout shifts. Each shift must occur less than 1 second after the previous one, and the time between the first and last shifts must not exceed 5 seconds to qualify as a session window. If these conditions aren't met, it's considered a new session window. This specification comes from extensive experimentation and research by the Chrome team, as detailed in Evolving the CLS metric.

CLS has three calculation methods:

1. Cumulative

2. Average of all session windows

3. Maximum of all session windows

Cumulative

This method adds up all layout shift scores from page load start. However, this approach disadvantages long-lived pages - the longer a page is open, the higher the CLS score becomes.

Average of All Session Windows

This method calculates based on session windows rather than individual layout shifts, taking the average of all session window scores. However, this approach has limitations.

As shown above, if the first session window has a high CLS score and the second has a low score, averaging them masks the actual page behavior. The average doesn't reflect that the page had more shifts early on and fewer later.

Maximum of All Session Windows

This is currently the optimal calculation method, using the highest session window score to reflect the worst-case scenario for layout shifts. For more details, see Evolving the CLS metric.

Below is the implementation code for the third calculation method:

let sessionValue = 0
let sessionEntries = []
const cls = {
    subType: 'layout-shift',
    name: 'layout-shift',
    type: 'performance',
    pageURL: getPageURL(),
    value: 0,
}

const entryHandler = (list) => {
    for (const entry of list.getEntries()) {
        // Only count layout shifts without recent user input.
        if (!entry.hadRecentInput) {
            const firstSessionEntry = sessionEntries[0]
            const lastSessionEntry = sessionEntries[sessionEntries.length - 1]

            // If the entry occurred less than 1 second after the previous entry and
            // less than 5 seconds after the first entry in the session, include the
            // entry in the current session. Otherwise, start a new session.
            if (
                sessionValue
                && entry.startTime - lastSessionEntry.startTime < 1000
                && entry.startTime - firstSessionEntry.startTime < 5000
            ) {
                sessionValue += entry.value
                sessionEntries.push(formatCLSEntry(entry))
            } else {
                sessionValue = entry.value
                sessionEntries = [formatCLSEntry(entry)]
            }

            // If the current session value is larger than the current CLS value,
            // update CLS and the entries contributing to it.
            if (sessionValue > cls.value) {
                cls.value = sessionValue
                cls.entries = sessionEntries
                cls.startTime = performance.now()
                lazyReportCache(deepCopy(cls))
            }
        }
    }
}

const observer = new PerformanceObserver(entryHandler)
observer.observe({ type: 'layout-shift', buffered: true })

A single layout shift measurement contains the following data:

{
  duration: 0,
  entryType: "layout-shift",
  hadRecentInput: false,
  lastInputTime: 0,
  name: "",
  sources: (2) [LayoutShiftAttribution, LayoutShiftAttribution],
  startTime: 1176.199999999255,
  value: 0.000005752046026677329,
}

The value field represents the layout shift score.

DOMContentLoaded and Load Events

The DOMContentLoaded event is triggered when the HTML is fully loaded and parsed, without waiting for CSS, images, and iframes to load.

The load event is triggered when the entire page and all dependent resources such as stylesheets and images have finished loading.

Although these performance metrics are older, they still provide valuable insights into page behavior. Monitoring them remains necessary.

import { lazyReportCache } from '../utils/report'

['load', 'DOMContentLoaded'].forEach(type => onEvent(type))

function onEvent(type) {
    function callback() {
        lazyReportCache({
            type: 'performance',
            subType: type.toLocaleLowerCase(),
            startTime: performance.now(),
        })

        window.removeEventListener(type, callback, true)
    }

    window.addEventListener(type, callback, true)
}

First Screen Rendering Time

In most cases, the first screen rendering time can be obtained through the load event. However, there are exceptions, such as asynchronously loaded images and DOM elements.

<script>
    setTimeout(() => {
        document.body.innerHTML = `
            <div>
                <!-- lots of code... -->
            </div>
        `
    }, 3000)
</script>

In such cases, we cannot obtain the first screen rendering time through the load event. Instead, we need to use MutationObserver to get the first screen rendering time. MutationObserver triggers events when the properties of the DOM elements it's monitoring change.

The process of calculating first screen rendering time:

1. Use MutationObserver to monitor the document object, triggering events whenever DOM element properties change.

2. Check if the DOM element is in the first screen. If it is, call performance.now() in the requestAnimationFrame() callback function to get the current time as its rendering time.

3. Compare the rendering time of the last DOM element with the loading time of all images in the first screen, and use the maximum value as the first screen rendering time.

Monitoring DOM

const next = window.requestAnimationFrame ? requestAnimationFrame : setTimeout
const ignoreDOMList = ['STYLE', 'SCRIPT', 'LINK']

observer = new MutationObserver(mutationList => {
    const entry = {
        children: [],
    }

    for (const mutation of mutationList) {
        if (mutation.addedNodes.length && isInScreen(mutation.target)) {
             // ...
        }
    }

    if (entry.children.length) {
        entries.push(entry)
        next(() => {
            entry.startTime = performance.now()
        })
    }
})

observer.observe(document, {
    childList: true,
    subtree: true,
})

The code above monitors DOM changes while filtering out style, script, and link tags.

Checking if Element is in First Screen

A page may have a lot of content, but users can only see one screen at a time. Therefore, when calculating first screen rendering time, we need to limit the scope to content visible in the current screen.

const viewportWidth = window.innerWidth
const viewportHeight = window.innerHeight

// Check if DOM element is in screen
function isInScreen(dom) {
    const rectInfo = dom.getBoundingClientRect()
    if (
        rectInfo.left >= 0 
        && rectInfo.left < viewportWidth
        && rectInfo.top >= 0
        && rectInfo.top < viewportHeight
    ) {
        return true
    }
}

Using requestAnimationFrame() to Get DOM Rendering Time

When DOM changes trigger the MutationObserver event, it only means the DOM content can be read, not that it has been painted to the screen.

As shown in the image above, when the MutationObserver event is triggered, we can read that document.body already has content, but the left side of the screen hasn't painted anything yet. Therefore, we need to call requestAnimationFrame() to get the current time as the DOM rendering time after the browser has successfully painted.

Comparing with All Image Loading Times in First Screen

function getRenderTime() {
    let startTime = 0
    entries.forEach(entry => {
        if (entry.startTime > startTime) {
            startTime = entry.startTime
        }
    })

    // Need to compare with all image loading times in current page, take the maximum
    // Image request time must be less than startTime, response end time must be greater than startTime
    performance.getEntriesByType('resource').forEach(item => {
        if (
            item.initiatorType === 'img'
            && item.fetchStart < startTime 
            && item.responseEnd > startTime
        ) {
            startTime = item.responseEnd
        }
    })

    return startTime
}

Optimization

The current code still needs optimization, with two main points to consider:

1. When should we report the rendering time?

2. How to handle asynchronously added DOM elements?

For the first point, we must report the rendering time after DOM changes stop, which typically happens after the load event triggers. Therefore, we can report at this point.

For the second point, we can report after the LCP event triggers. Whether DOM elements are loaded synchronously or asynchronously, they need to be painted, so we can monitor the LCP event and only allow reporting after it triggers.

Combining these two approaches, we get the following code:

let isOnLoaded = false
executeAfterLoad(() => {
    isOnLoaded = true
})

let timer
let observer
function checkDOMChange() {
    clearTimeout(timer)
    timer = setTimeout(() => {
        // Calculate first screen rendering time after load and LCP events trigger and DOM tree stops changing
        if (isOnLoaded && isLCPDone()) {
            observer && observer.disconnect()
            lazyReportCache({
                type: 'performance',
                subType: 'first-screen-paint',
                startTime: getRenderTime(),
                pageURL: getPageURL(),
            })

            entries = null
        } else {
            checkDOMChange()
        }
    }, 500)
}

The checkDOMChange() function is called each time the MutationObserver event triggers and needs to be debounced.

API Request Timing

To monitor API request timing, we need to intercept both XMLHttpRequest and fetch requests.

Monitoring XMLHttpRequest

originalProto.open = function newOpen(...args) {
    this.url = args[1]
    this.method = args[0]
    originalOpen.apply(this, args)
}

originalProto.send = function newSend(...args) {
    this.startTime = Date.now()

    const onLoadend = () => {
        this.endTime = Date.now()
        this.duration = this.endTime - this.startTime

        const { status, duration, startTime, endTime, url, method } = this
        const reportData = {
            status,
            duration,
            startTime,
            endTime,
            url,
            method: (method || 'GET').toUpperCase(),
            success: status >= 200 && status < 300,
            subType: 'xhr',
            type: 'performance',
        }

        lazyReportCache(reportData)

        this.removeEventListener('loadend', onLoadend, true)
    }

    this.addEventListener('loadend', onLoadend, true)
    originalSend.apply(this, args)
}

To determine if an XML request is successful, we can check if its status code is between 200 and 299. If it is, the request was successful; otherwise, it failed.

Monitoring fetch

const originalFetch = window.fetch

function overwriteFetch() {
    window.fetch = function newFetch(url, config) {
        const startTime = Date.now()
        const reportData = {
            startTime,
            url,
            method: (config?.method || 'GET').toUpperCase(),
            subType: 'fetch',
            type: 'performance',
        }

        return originalFetch(url, config)
        .then(res => {
            reportData.endTime = Date.now()
            reportData.duration = reportData.endTime - reportData.startTime

            const data = res.clone()
            reportData.status = data.status
            reportData.success = data.ok

            lazyReportCache(reportData)

            return res
        })
        .catch(err => {
            reportData.endTime = Date.now()
            reportData.duration = reportData.endTime - reportData.startTime
            reportData.status = 0
            reportData.success = false

            lazyReportCache(reportData)

            throw err
        })
    }
}

For fetch requests, we can determine success by checking the ok field in the response data. If it's true, the request was successful; otherwise, it failed.

Note: The API request timing we monitor may differ from what's shown in Chrome DevTools. This is because Chrome DevTools shows the time for the entire HTTP request and interface process. But XHR and fetch are asynchronous requests – after the interface request succeeds, the callback function needs to be called. When the event triggers, the callback function is placed in the message queue, and then the browser processes it. There's also a waiting period in between.

Resource Loading Time and Cache Hit Rate

We can monitor resource and navigation events through PerformanceObserver. If the browser doesn't support PerformanceObserver, we can fall back to using performance.getEntriesByType(entryType).

When the resource event triggers, we can get the corresponding resource list. Each resource object contains the following fields:

From these fields, we can extract useful information:

{
    name: entry.name, // Resource name
    subType: entryType,
    type: 'performance',
    sourceType: entry.initiatorType, // Resource type
    duration: entry.duration, // Resource loading duration
    dns: entry.domainLookupEnd - entry.domainLookupStart, // DNS duration
    tcp: entry.connectEnd - entry.connectStart, // TCP connection duration
    redirect: entry.redirectEnd - entry.redirectStart, // Redirect duration
    ttfb: entry.responseStart, // Time to first byte
    protocol: entry.nextHopProtocol, // Request protocol
    responseBodySize: entry.encodedBodySize, // Response body size
    responseHeaderSize: entry.transferSize - entry.encodedBodySize, // Response header size
    resourceSize: entry.decodedBodySize, // Resource size after decompression
    isCache: isCache(entry), // Whether cache was hit
    startTime: performance.now(),
}

Determining if Resource Hit Cache

Among these resource objects, there's a transferSize field that represents the size of the resource being fetched, including response header fields and response data size. If this value is 0, it means the resource was read directly from cache (forced cache). If this value is not 0 but the encodedBodySize field is 0, it means it used negotiated cache (encodedBodySize represents the size of the response data body).

function isCache(entry) {
    // Read directly from cache or 304
    return entry.transferSize === 0 || (entry.transferSize !== 0 && entry.encodedBodySize === 0)
}

If it doesn't meet the above conditions, it means the cache was not hit. Then we can calculate the cache hit rate by dividing all cached data/total data.

Browser Back/Forward Cache (BFC)

BFC is a memory cache that saves the entire page in memory. When users navigate back, they can see the entire page immediately without refreshing. According to the article bfcache, Firefox and Safari have always supported BFC, while Chrome only supports it in high-version mobile browsers. But when I tested it, only Safari supported it – my Firefox version might have been different.

Still, BFC also has drawbacks. When users navigate back and restore the page from BFC, the original page's code won't execute again. For this reason, browsers provide a pageshow event where we can put code that needs to be executed again.

window.addEventListener('pageshow', function(event) {
  // If this property is true, it means the page was restored from BFC
  if (event.persisted) {
    console.log('This page was restored from the bfcache.');
  } else {
    console.log('This page was loaded normally.');
  }
});

For pages restored from BFC, we also need to collect their FP, FCP, LCP, and other timing metrics.

onBFCacheRestore(event => {
    requestAnimationFrame(() => {
        ['first-paint', 'first-contentful-paint'].forEach(type => {
            lazyReportCache({
                startTime: performance.now() - event.timeStamp,
                name: type,
                subType: type,
                type: 'performance',
                pageURL: getPageURL(),
                bfc: true,
            })
        })
    })
})

The code above is easy to understand. After the pageshow event triggers, we subtract the event timestamp from the current time – this time difference is the rendering time of the performance metrics.

Note: For pages restored from BFC, these performance metrics usually have very small values, around 10 ms. This means that we need to add an identifier field bfc: true so we can ignore them when doing performance statistics.

FPS

We can calculate the current page's FPS using requestAnimationFrame().

const next = window.requestAnimationFrame 
    ? requestAnimationFrame : (callback) => { setTimeout(callback, 1000 / 60) }

const frames = []

export default function fps() {
    let frame = 0
    let lastSecond = Date.now()

    function calculateFPS() {
        frame++
        const now = Date.now()
        if (lastSecond + 1000 <= now) {
            // Since now - lastSecond is in milliseconds, frame needs to be multiplied by 1000
            const fps = Math.round((frame * 1000) / (now - lastSecond))
            frames.push(fps)

            frame = 0
            lastSecond = now
        }

        // Avoid reporting too frequently, cache a certain amount before reporting
        if (frames.length >= 60) {
            report(deepCopy({
                frames,
                type: 'performace',
                subType: 'fps',
            }))

            frames.length = 0
        }

        next(calculateFPS)
    }

    calculateFPS()
}

The code logic is as follows:

First record an initial time, then each time requestAnimationFrame() triggers, increment the frame count by 1. After one second passes, we can get the current frame rate by dividing frame count/elapsed time.

When three consecutive FPS values below 20 appear, we can determine that the page has become unresponsive. This technique is based on the observation that smooth animations require at least 20 FPS to appear fluid to users.

export function isBlocking(fpsList, below = 20, last = 3) {
    let count = 0
    for (let i = 0; i < fpsList.length; i++) {
        if (fpsList[i] && fpsList[i] < below) {
            count++
        } else {
            count = 0
        }

        if (count >= last) {
            return true
        }
    }

    return false
}

Vue Router Change Rendering Time

We already know how to calculate first screen rendering time, but how do we calculate the page rendering time caused by route changes in SPA applications? This article uses Vue as an example to explain my approach.

export default function onVueRouter(Vue, router) {
    let isFirst = true
    let startTime
    router.beforeEach((to, from, next) => {
        // First page load already has other rendering time metrics available
        if (isFirst) {
            isFirst = false
            return next()
        }

        // Add a new field to router to indicate whether to calculate rendering time
        // Only needed for route changes
        router.needCalculateRenderTime = true
        startTime = performance.now()

        next()
    })

    let timer
    Vue.mixin({
        mounted() {
            if (!router.needCalculateRenderTime) return

            this.$nextTick(() => {
                // Code that only runs after the entire view has been rendered
                const now = performance.now()
                clearTimeout(timer)

                timer = setTimeout(() => {
                    router.needCalculateRenderTime = false
                    lazyReportCache({
                        type: 'performance',
                        subType: 'vue-router-change-paint',
                        duration: now - startTime,
                        startTime: now,
                        pageURL: getPageURL(),
                    })
                }, 1000)
            })
        },
    })
}

The code logic is as follows:

1. Monitor route hooks – when route changes occur, the router.beforeEach() hook triggers. In this hook's callback function, record the current time as the rendering start time.

2. Use Vue.mixin() to inject a function into all components' mounted() hooks. Each function executes a debounced function.

3. When the last component's mounted() triggers, it means all components under this route have been mounted. We can get the rendering time in the this.$nextTick() callback function.

Also, we need to consider another case. When not changing routes, there may also be component changes, in which case we shouldn't calculate rendering time in these components' mounted() hooks. Therefore, we need to add a needCalculateRenderTime field - set it to true when changing routes to indicate that rendering time can be calculated.

Error Data Collection

Error monitoring is a critical aspect of frontend monitoring that helps identify issues users encounter while interacting with your application. By tracking and analyzing these errors, you can proactively fix bugs before they affect more users, improving both user experience and application reliability.

In this section, we'll explore how to capture various types of errors including resource loading failures, JavaScript runtime errors, unhandled promises, and framework-specific errors.

Resource Loading Errors

Resource loading errors occur when the browser fails to load external resources like images, stylesheets, scripts, and fonts. These errors can significantly impact user experience by causing missing content, broken layouts, or even preventing core functionality from working.

Using addEventListener() to monitor the error event can capture resource loading failure errors.

// Capture resource loading failure errors js css img...
window.addEventListener('error', e => {
    const target = e.target
    if (!target) return

    if (target.src || target.href) {
        const url = target.src || target.href
        lazyReportCache({
            url,
            type: 'error',
            subType: 'resource',
            startTime: e.timeStamp,
            html: target.outerHTML,
            resourceType: target.tagName,
            paths: e.path.map(item => item.tagName).filter(Boolean),
            pageURL: getPageURL(),
        })
    }
}, true)

This code listens for the global error event with the capture option set to true, which allows it to catch errors from resource elements like <img>, <link>, and <script>. When a resource fails to load, it collects important information including:

• The URL of the failed resource

• The element type (img, link, script)

• The HTML of the element that failed

• The DOM path to the element

• The page URL where the error occurred

With this data, you can identify which resources are failing most frequently, prioritize fixes, and implement fallback strategies for critical resources.

JavaScript Errors

JavaScript errors occur during script execution and can prevent features from working properly. These include syntax errors, reference errors, type errors, and other runtime exceptions.

Using window.onerror can monitor JavaScript errors.

// Monitor JavaScript errors
window.onerror = (msg, url, line, column, error) => {
    lazyReportCache({
        msg,
        line,
        column,
        error: error.stack,
        subType: 'js',
        pageURL: url,
        type: 'error',
        startTime: performance.now(),
    })
}

This handler captures detailed information about JavaScript errors:

• The error message

• The file URL where the error occurred

• The line and column number of the error

• The full error stack trace

This information is invaluable for debugging and fixing issues, especially in production environments where direct debugging isn't possible. By analyzing these errors, you can identify patterns and prioritize fixes for the most common or impactful issues.

Promise Errors

Modern JavaScript applications heavily use Promises for asynchronous operations. When a Promise rejection isn't handled with .catch() or a second argument to .then(), it results in an unhandled rejection which can cause silent failures.

Using addEventListener() to monitor the unhandledrejection event can capture unhandled promise errors.

// Monitor promise errors - drawback is can't get column data
window.addEventListener('unhandledrejection', e => {
    lazyReportCache({
        reason: e.reason?.stack,
        subType: 'promise',
        type: 'error',
        startTime: e.timeStamp,
        pageURL: getPageURL(),
    })
})

This code captures unhandled Promise rejections and reports:

• The rejection reason (usually an error object with a stack trace)

• The timestamp when the rejection occurred

• The page URL where the rejection happened

Tracking unhandled Promise rejections is particularly important for asynchronous operations like API calls, where errors might otherwise go unnoticed. By monitoring these rejections, you can ensure that all asynchronous errors are properly handled and resolved.

Sourcemap

Generally, production environment code is minified, and sourcemap files are not uploaded to production. Therefore, error messages in production environment code are difficult to read. For this reason, we can use source-map to restore these minified code error messages.

When code errors occur, we can get the corresponding filename, line number, and column number:

{
    line: 1,
    column: 17,
    file: 'https:/www.xxx.com/bundlejs',
}

Then call the following code to restore:

async function parse(error) {
    const mapObj = JSON.parse(getMapFileContent(error.url))
    const consumer = await new sourceMap.SourceMapConsumer(mapObj)
    // Remove ./ from webpack://source-map-demo/./src/index.js file
    const sources = mapObj.sources.map(item => format(item))
    // Get original line and column numbers and source file based on minified error information
    const originalInfo = consumer.originalPositionFor({ line: error.line, column: error.column })
    // sourcesContent contains the original source code of each file before minification, find corresponding source code by filename
    const originalFileContent = mapObj.sourcesContent[sources.indexOf(originalInfo.source)]
    return {
        file: originalInfo.source,
        content: originalFileContent,
        line: originalInfo.line,
        column: originalInfo.column,
        msg: error.msg,
        error: error.error
    }
}

function format(item) {
    return item.replace(/(\.\/)*/g, '')
}

function getMapFileContent(url) {
    return fs.readFileSync(path.resolve(__dirname, `./maps/${url.split('/').pop()}.map`), 'utf-8')
}

Each time the project is built, if sourcemap is enabled, each JS file will have a corresponding map file.

bundle.js
bundle.js.map

At this point, the JS file is placed on the static server for user access, while the map file is stored on the server for error message restoration. The source-map library can restore error messages from minified code to their original state. For example, if the minified code error location is line 1, column 47, the restored location might be line 4, column 10. Besides location information, we can also get the original source code.

The image above shows an example of code error restoration. Since this part doesn't belong to the SDK's scope, I created another repository to handle this. Feel free to check it out if you're interested.

Vue Errors

Using window.onerror cannot capture Vue errors – we need to use Vue's provided API for monitoring.

Vue.config.errorHandler = (err, vm, info) => {
    // Print error information to console
    console.error(err)

    lazyReportCache({
        info,
        error: err.stack,
        subType: 'vue',
        type: 'error',
        startTime: performance.now(),
        pageURL: getPageURL(),
    })
}

Behavior Data Collection

Understanding how users interact with your application is crucial for optimizing user experience, improving engagement, and driving business goals. Behavior monitoring tracks user actions, navigation patterns, and engagement metrics to provide insights into how your application is actually being used.

In this section, we'll explore how to collect key behavioral metrics that can help you make data-driven decisions to improve your application.

PV and UV

PV (Page View) is the number of page views, while UV (Unique Visitor) is the number of unique users visiting. PV counts each page visit, while UV only counts once per user per day.

Why this matters: PV and UV metrics help you understand your application's traffic patterns. A high PV-to-UV ratio indicates users are viewing multiple pages, suggesting good engagement. Tracking these metrics over time helps you identify growth trends, seasonal patterns, and the impact of marketing campaigns or feature releases.

For the front end, we just need to report PV each time a page is entered. UV statistics are handled on the server side, mainly analyzing reported data to calculate UV.

export default function pv() {
    lazyReportCache({
        type: 'behavior',
        subType: 'pv',
        startTime: performance.now(),
        pageURL: getPageURL(),
        referrer: document.referrer,
        uuid: getUUID(),
    })
}

You can use this data to:

• Track which pages are most popular

• Identify underperforming pages that need improvement

• Analyze user flow through your application

• Measure the effectiveness of new features or content

Page Stay Duration

To get the stay duration, you just need to record an initial time when users enter the page, then subtract the initial time from the current time when users leave the page. This calculation logic can be placed in the beforeunload event.

Why this matters: Page stay duration indicates how engaging your content is. Longer durations typically suggest users find the content valuable, while very short durations might indicate confusion, irrelevant content, or usability issues. This metric helps you identify which pages effectively capture user attention and which ones need improvement.

export default function pageAccessDuration() {
    onBeforeunload(() => {
        report({
            type: 'behavior',
            subType: 'page-access-duration',
            startTime: performance.now(),
            pageURL: getPageURL(),
            uuid: getUUID(),
        }, true)
    })
}

With page stay duration data, you can:

• Identify engaging vs. problematic content

• Set benchmarks for content performance

• Detect potential usability issues (extremely short durations)

• Measure the effectiveness of content updates or redesigns

Page Access Depth

Recording page access depth is very useful. For example, for different activity pages a and b, if page a has an average access depth of 50% and page b has 80%, it indicates that page b is more popular with users. Based on this, we can make targeted improvements to page a.

Why this matters: Access depth measures how far users scroll down a page, revealing whether they're viewing all your content or abandoning it partway through. This metric helps identify content engagement patterns and potential issues with content structure or page length.

Also, we can use access depth and stay duration to identify e-commerce order fraud. For example, if someone enters the page and immediately scrolls to the bottom, then waits a while before purchasing, while another person slowly scrolls down the page before purchasing. Even though they have the same stay duration, the first person is more likely to be committing fraud.

The page access depth calculation process is slightly more complex:

1. When users enter the page, record the current time, scrollTop value, viewport height, and total page height.

2. When users scroll the page, the scroll event triggers. In the callback function, use the data from point 1 to calculate page access depth and stay duration.

3. When users stop scrolling at a certain point to continue viewing the page, record the current time, scrollTop value, viewport height, and total page height.

4. Repeat point 2...

Here's the specific code:

let timer
let startTime = 0
let hasReport = false
let pageHeight = 0
let scrollTop = 0
let viewportHeight = 0

export default function pageAccessHeight() {
    window.addEventListener('scroll', onScroll)

    onBeforeunload(() => {
        const now = performance.now()
        report({
            startTime: now,
            duration: now - startTime,
            type: 'behavior',
            subType: 'page-access-height',
            pageURL: getPageURL(),
            value: toPercent((scrollTop + viewportHeight) / pageHeight),
            uuid: getUUID(),
        }, true)
    })

    // Initialize and record current access height and time after page loads
    executeAfterLoad(() => {
        startTime = performance.now()
        pageHeight = document.documentElement.scrollHeight || document.body.scrollHeight
        scrollTop = document.documentElement.scrollTop || document.body.scrollTop
        viewportHeight = window.innerHeight
    })
}

function onScroll() {
    clearTimeout(timer)
    const now = performance.now()

    if (!hasReport) {
        hasReport = true
        lazyReportCache({
            startTime: now,
            duration: now - startTime,
            type: 'behavior',
            subType: 'page-access-height',
            pageURL: getPageURL(),
            value: toPercent((scrollTop + viewportHeight) / pageHeight),
            uuid: getUUID(),
        })
    }

    timer = setTimeout(() => {
        hasReport = false
        startTime = now
        pageHeight = document.documentElement.scrollHeight || document.body.scrollHeight
        scrollTop = document.documentElement.scrollTop || document.body.scrollTop
        viewportHeight = window.innerHeight        
    }, 500)
}

function toPercent(val) {
    if (val >= 1) return '100%'
    return (val * 100).toFixed(2) + '%'
}

With page access depth data, you can:

• Identify where users lose interest in your content

• Optimize content placement (put important elements where users actually look)

• Improve long-form content structure with better hierarchy

• Detect unusual user behavior patterns that might indicate fraud or bots

User Clicks

Using addEventListener() to monitor mousedown and touchstart events, we can collect information about each click area's size, click coordinates' specific position in the page, clicked element's content, and other information.

Why this matters: Click tracking reveals what elements users interact with most frequently, helping you understand user interests and optimize UI element placement. It also helps identify usability issues where users might be clicking on non-interactive elements expecting a response.

export default function onClick() {
    ['mousedown', 'touchstart'].forEach(eventType => {
        let timer
        window.addEventListener(eventType, event => {
            clearTimeout(timer)
            timer = setTimeout(() => {
                const target = event.target
                const { top, left } = target.getBoundingClientRect()

                lazyReportCache({
                    top,
                    left,
                    eventType,
                    pageHeight: document.documentElement.scrollHeight || document.body.scrollHeight,
                    scrollTop: document.documentElement.scrollTop || document.body.scrollTop,
                    type: 'behavior',
                    subType: 'click',
                    target: target.tagName,
                    paths: event.path?.map(item => item.tagName).filter(Boolean),
                    startTime: event.timeStamp,
                    pageURL: getPageURL(),
                    outerHTML: target.outerHTML,
                    innerHTML: target.innerHTML,
                    width: target.offsetWidth,
                    height: target.offsetHeight,
                    viewport: {
                        width: window.innerWidth,
                        height: window.innerHeight,
                    },
                    uuid: getUUID(),
                })
            }, 500)
        })
    })
}

With this click data, you can:

• Create heatmaps showing where users click most frequently

• Identify non-functional elements users try to interact with

• Optimize button placement and size for better conversion

• Detect rage clicks (multiple rapid clicks in the same area) indicating user frustration

Page Navigation

Using addEventListener() to monitor popstate and hashchange page navigation events allows you to track how users navigate through your application.

Why this matters: Navigation tracking helps you understand user flow patterns - how users move between pages, which navigation paths are most common, and where users might be getting lost or trapped in navigation loops. This data is crucial for optimizing site structure and improving user journey flows.

export default function pageChange() {
    let from = ''
    window.addEventListener('popstate', () => {
        const to = getPageURL()

        lazyReportCache({
            from,
            to,
            type: 'behavior',
            subType: 'popstate',
            startTime: performance.now(),
            uuid: getUUID(),
        })

        from = to
    }, true)

    let oldURL = ''
    window.addEventListener('hashchange', event => {
        const newURL = event.newURL

        lazyReportCache({
            from: oldURL,
            to: newURL,
            type: 'behavior',
            subType: 'hashchange',
            startTime: performance.now(),
            uuid: getUUID(),
        })

        oldURL = newURL
    }, true)
}

With navigation data, you can:

• Identify common user paths through your application

• Detect navigation dead-ends or loops where users get stuck

• Optimize navigation menus based on actual usage patterns

• Improve information architecture to better match user behavior

Vue Router Changes

For applications built with Vue, you can use the router's hooks to monitor navigation between routes, providing similar insights to general page navigation tracking but specific to Vue's routing system.

Why this matters: In single-page applications, traditional page navigation events don't capture all route changes. Framework-specific router monitoring ensures you don't miss important navigation data in modern web applications.

export default function onVueRouter(router) {
    router.beforeEach((to, from, next) => {
        // Don't count first page load
        if (!from.name) {
            return next()
        }

        const data = {
            params: to.params,
            query: to.query,
        }

        lazyReportCache({
            data,
            name: to.name || to.path,
            type: 'behavior',
            subType: ['vue-router-change', 'pv'],
            startTime: performance.now(),
            from: from.fullPath,
            to: to.fullPath,
            uuid: getUUID(),
        })

        next()
    })
}

This data helps you:

• Track the most frequently accessed routes in your Vue application

• Understand navigation patterns specific to your application's structure

• Identify potential optimization opportunities in your routing setup

• Measure the impact of UX improvements on navigation behavior

Data Reporting

Once you've collected performance, error, and behavior data, you need a reliable system to transmit this information to your backend for processing and analysis. Data reporting is the critical bridge between client-side data collection and server-side analytics.

Effective data reporting must balance several concerns:

1. Reliability – Ensuring data is successfully transmitted, especially critical errors

2. Performance – Minimizing impact on the user experience and application performance

3. Timing – Deciding when to send data to avoid interference with user interactions

4. Bandwidth – Managing the amount of data transmitted to reduce network usage

Let's explore the various methods and strategies for implementing efficient data reporting.

Reporting Methods

Data can be reported using the following methods:

• sendBeacon

• XMLHttpRequest

• image

My simple SDK uses a combination of the first and second methods for reporting. Using sendBeacon for reporting has very obvious advantages.

Note: Using the sendBeacon() method will send data to the server asynchronously when the user agent has an opportunity, without delaying page unload or affecting the performance of the next navigation. This solves all the problems with submitting analytics data: data is reliable, transmission is asynchronous, and it won't affect the loading of the next page.

For browsers that don't support sendBeacon, we can use XMLHttpRequest for reporting. An HTTP request consists of sending and receiving two steps.

Actually, for reporting, we just need to ensure the data can be sent – we don't need to receive the response. For this reason, I did an experiment where I sent 30kb of data (generally reported data rarely exceeds this size) using XMLHttpRequest in beforeunload, tested with different browsers, and all were able to send successfully. Of course, this also depends on hardware performance and network conditions.

Here's a sample implementation of a reporting function that uses both methods:

function report(data, isImmediate = false) {
    if (!config.reportUrl) {
        console.error('Report URL is not set')
        return
    }

    // Add timestamp and other common properties
    const reportData = {
        ...data,
        timestamp: Date.now(),
        userAgent: navigator.userAgent,
        userId: getUserId(),
        // Add other common properties as needed
    }

    // Choose reporting method based on browser support and timing
    if (isImmediate) {
        sendData(reportData)
    } else {
        // Queue data for batch sending
        reportQueue.push(reportData)

        // Send when queue reaches threshold
        if (reportQueue.length >= config.batchSize) {
            sendBatchData()
        }
    }
}

function sendData(data) {
    // Try sendBeacon first
    if (navigator.sendBeacon) {
        const blob = new Blob([JSON.stringify(data)], { type: 'application/json' })
        const success = navigator.sendBeacon(config.reportUrl, blob)

        if (success) return
    }

    // Fall back to XMLHttpRequest
    const xhr = new XMLHttpRequest()
    xhr.open('POST', config.reportUrl, true)
    xhr.setRequestHeader('Content-Type', 'application/json')
    xhr.send(JSON.stringify(data))
}

function sendBatchData() {
    if (reportQueue.length === 0) return

    const data = [...reportQueue]
    reportQueue.length = 0

    sendData({ type: 'batch', data })
}

Reporting Timing

There are three reporting timings:

1. Use requestIdleCallback/setTimeout for delayed reporting

2. Report in the beforeunload callback function

3. Cache reported data and report when reaching a certain amount

It's recommended to combine all three methods:

1. First cache the reported data, and when reaching a certain amount, use requestIdleCallback/setTimeout for delayed reporting

2. Report all unreported data when leaving the page

Here's how you might implement this combined approach:

// Cache for storing reports until they're sent
let reportCache = []
const MAX_CACHE_SIZE = 10
let timer = null

// Report data with requestIdleCallback when browser is idle
function lazyReportCache(data) {
    reportCache.push(data)

    // If cache reaches threshold, schedule sending
    if (reportCache.length >= MAX_CACHE_SIZE) {
        // Use requestIdleCallback if available, otherwise setTimeout
        const scheduleFn = window.requestIdleCallback || setTimeout

        if (timer) {
            cancelScheduledReport()
        }

        timer = scheduleFn(() => {
            // Send cached data in bulk
            const dataToSend = [...reportCache]
            reportCache = []
            report({
                type: 'batch',
                data: dataToSend,
            })
            timer = null
        }, { timeout: 2000 }) // For requestIdleCallback, timeout after 2s
    }
}

function cancelScheduledReport() {
    if (window.requestIdleCallback && timer) {
        window.cancelIdleCallback(timer)
    } else if (timer) {
        clearTimeout(timer)
    }
    timer = null
}

// Report any remaining data when user leaves the page
function setupUnloadReporting() {
    window.addEventListener('beforeunload', () => {
        if (reportCache.length > 0) {
            // Cancel any scheduled reporting
            cancelScheduledReport()

            // Send remaining cached data immediately
            report({
                type: 'batch',
                data: reportCache,
            }, true) // true for immediate sending

            reportCache = []
        }
    })
}

This implementation:

1. Collects data in a cache until it reaches a threshold

2. Uses requestIdleCallback (or setTimeout as fallback) to send data when the browser is idle

3. Ensures any remaining data is sent when the user leaves the page

4. Batches multiple reports together to reduce network requests

By combining these methods, you create a robust reporting system that minimizes performance impact while ensuring data reliability.

Summary

In this comprehensive guide, we've explored how to build a complete frontend monitoring SDK for collecting and reporting critical application data. Let's recap what we've covered:

1. Performance Monitoring

   • We implemented methods to capture key web vitals like FP, FCP, LCP, and CLS

   • We tracked page load events, API request timing, and resource loading metrics

   • We measured first screen rendering time and frame rates to ensure smooth user experiences

   • We added support for SPA-specific metrics like Vue router change rendering time

2. Error Monitoring

   • We built systems to capture resource loading errors, JavaScript exceptions, and Promise rejections

   • We explored how to use sourcemaps to make minified production errors readable

   • We integrated with framework-specific error handling for Vue applications

3. User Behavior Tracking

   • We implemented tracking for page views, stay duration, and scroll depth

   • We created methods to monitor user clicks and navigation patterns

   • We built custom tracking for SPA navigation with Vue Router

4. Data Reporting

   • We developed robust reporting mechanisms using sendBeacon and XMLHttpRequest

   • We implemented intelligent reporting timing strategies to minimize performance impact

   • We created batching mechanisms to reduce network requests

Building your own monitoring SDK gives you complete control over what data you collect and how you process it. This approach offers several advantages over third-party solutions:

• Privacy: You own all the data and can ensure compliance with regulations like GDPR

• Performance: You can optimize the SDK specifically for your application's needs

• Customization: You can add custom metrics unique to your business requirements

• Integration: Your SDK can easily integrate with your existing systems

As you implement your own monitoring solution, remember these best practices:

1. Respect User Privacy: Only collect what you need and be transparent about it

2. Minimize Performance Impact: Ensure your monitoring doesn't degrade the user experience

3. Balance Detail and Volume: More data isn't always better if it overwhelms your analysis

4. Act on Insights: The ultimate goal is to improve your application based on the data

By following the approaches outlined in this article, you'll be well-equipped to build a comprehensive monitoring system that helps you deliver better user experiences through data-driven decision making.

References

Performance Monitoring

• Performance API

• PerformanceResourceTiming

• Using_the_Resource_Timing_API

• PerformanceTiming

• Metrics

• evolving-cls

• custom-metrics

• web-vitals

• PerformanceObserver

• Element_timing_API

• PerformanceEventTiming

• Timing-Allow-Origin

• bfcache

• MutationObserver

• XMLHttpRequest

• sendBeacon

Error Monitoring

• noerror

• source-map

Behavior Monitoring

• popstate

• hashchange

Grafana is an open-source analytics and monitoring platform. It has gained widespread recognition among developers and enterprises looking to extract more insights from the data produced by their systems.

Grafana has many powerful visualization features, and when combined with Amazon EC2's scalability and flexibility, it creates a stable environment for efficient monitoring.

This article will walk you through setting up Grafana on Amazon EC2 and creating informative dashboards out of raw data.

For Whom is this Intended?

This tutorial is intended for both novices to the cloud and experts in DevOps. The goal of this post is to make the installation process easier so you can use Grafana on AWS to its fullest. Now let's get going.

How to Configure Your EC2 Instance

You need to configure the inbound rule for your EC2 instance to access port 3000, as Grafana operates on this port. But first, you need to establish an EC2 instance. You can follow this guide on how to set up your AWS EC2 instance. It takes less than 5 minutes.

Once you have created your EC2 instance, you'll need to configure the network inbound rules. So head to your instance page and click on it. On the button widget, click on the security tab and click on the security group link (it should look like this: “sg-547**”).

Once you open the page in the inbound rules section, click on ‘Edit inbound rules’. Click on Add a new rule and add 3000 to the port range field, and on the source field, select 0.0.0.0/0. Then save.

Inbound rules

How to Create an IAM Role

Now you need to construct an IAM (Identity Access Management) role. You're developing an identity role so that you can generate credentials that you'll subsequently use to log in to your Grafana service.

IAM Dashboard

So, in the search field, type "IAM service" and click it. Click 'Create role', and select the AWS service as the trusted entity type.

IAM Trusted Entity

On the use case section, select EC2, then click next.

IAM role use case

On the Add Permissions page, click on the AdministratorAccess policy, then click next. Enter a role name – in this case, I used Grafana-Server-Role.

Role creation

How to Download Grafana

Now that you've configured your EC2 inbound rule and also configured the IAM role, let's set up Grafana on your EC2 instance.

So head over to Grafana's download page. Since we'll be downloading the version for Amazon Linux in this tutorial, you need to type in the following command on your Linux command line. Note: You need to connect to your VM instance through SSH (Secure Shell). In this case, I am using the EC2 Instance Connect.

sudo yum install -y https://dl.grafana.com/enterprise/release/grafana-enterprise-11.1.0-1.x86_64.rpm

Now you'll enable the Grafana service on your terminal by typing the following command:

systemctl enable grafana-server.service

Then start the service:

systemctl start grafana-server.service

Check the status of the Grafana service on the EC2 instance by running this command:

systemctl status grafana-server.service

Grafana Service Status

Now that you've confirmed that the service is currently active, you'll also need to check if the Grafana service is active on port 3000, as you've already created an inbound rule to cater for this.

You can do this by typing the following command:

netstat -tunpl | grep grafana

Port 3000 confirmation

Now that you've confirmed that the service runs on port 3000, you can go ahead and set up your Grafana dashboard.

You can access the Grafana dashboard by typing the Public IP of your EC2 instance and adding port 3000 on your web browser, something like this: 34.239.101.172:3000.

Grafana Login

The default username and password for Grafana are admin, but you'll be given the option to change your password after you sign in with the default credentials. You can also skip the password change process if you like.

Change password on Grafana

After this step, go to the home page. The next thing to do is to start connecting your Grafana dashboard to a data source. In this case, you're going to connect it to the AWS cloud watch service.

Grafana

How to Connect Data Sources to the Grafana Dashboard

Click on the connections tab on the side menu and click on data sources. Search for the CloudWatch service.

Cloudwatch configuration

Now you'll be prompted to input your access key ID and secret access key. You will need to create this on your AWS IAM service.

So go back to your IAM management dashboard and go to the user's tab. If you haven’t created an IAM user, you can do so by checking out this IAM user creation tutorial.

In the user IAM dashboard, scroll down to the access keys section and click on Create access key.

Access key

Select the Command Line Interface use case.

Access key use case

Set the description tag. This step is optional. Then click on the Create access key.

Access keys

Now copy the Access Key ID and Secret access key and paste them into the CloudWatch Datasource configuration page on Grafana. Set your default cloud region – in this case, mine is us-east-1

Additional settings

When you’re done, click on the save and test buttons. Grafana will query the Cloudwatch logs, and if it works fine it will save the configuration.

How to Create a Dashboard on Grafana

Now that you have successfully configured your grafana service, let’s start creating dashboards.

Click on the dashboard tab on the side menu click on New and select new dashboard. You should see the screen below:

Create a new dashboard

Then select Import dashboard.

Import a dashboard

For this case, you'll be importing an already-made dashboard from Grafana. Grafana has a lot of dashboards for a lot of use cases and services. But in this case, you'll be importing an EC2 dashboard (Grafana EC2 dashboard).

If you want to import it, you can easily copy the ID of the dashboard that you want to import. It is always accompanied by the dashboard.

So now copy the ID – in this case, it's 11265. Then paste it into the import field on the import dashboard, and click on the load button.

Grafana Dashboard

Now you have successfully created a dashboard in Grafana. This dashboard lets you monitor the performance of your EC2 instance. You can monitor metrics such as CPU Utilization, CPU Credit, Disk Ops, Disk Bytes, Network, Network Packets, Status check, and so on.

Wrapping Up

Thank you for reading! I hope this step by step guide has helped you learn how to create and set up efficient dashboards using Grafana.