DOCSEARCHbyAlgolia
Submit Docs

Globalping Documentation

repository·master·Indexed 20 days ago

https://github.com/jsdelivr/globalping

A platform for running networking commands like ping, traceroute, and DNS lookups from a globally distributed network of probes. Includes documentation for the globalping-api (v1.0.0), CLI installation, Slack app integration, REST API usage, and instructions for hosting probes via Docker. Covers probe location targeting using the 'magic' field, system tags for network types, and platform usage limits.

Tokens
18.3K
Snippets
57
Records
84
Agent score
69%

What's inside Globalping

  2. Understand Globalping usage limits and restrictions

    master

    To maintain performance and security, Globalping applies technical and operational limits to the Services, including probe hosting.

    Key details for users:

    • Limit Application: Limits may be applied based on IP address, IP address range, network, location, ASN, probe, or user account.
    • Compliance: You must not attempt to circumvent these limits using additional accounts, IP addresses, or probes.
    • Consequences of Violation: Globalping may disconnect probes that exceed limits, produce unreliable data, or threaten the integrity of the service.
    • Custom Solutions: For legitimate projects that require higher limits, you can contact Globalping to discuss removing limits or providing custom solutions.
    • Current Limits: The most up-to-date limits are published on the official Globalping website and in the official documentation.

  3. Understand the Globalping command structure

    master

    Globalping uses a consistent command structure across its CLI, Slack app, and other integrations. This allows you to switch between tools without relearning syntax.

    Command Syntax: globalping [command] [target] from [location] [flags]

    Components:

    • Available test types: ping, traceroute, mtr, dns (similar to dig), and http (similar to curl GET and HEAD).
    • Target: A domain name or an IP address.
    • Location: Supports continents, regions, countries, cities, US states, and ASNs (prefixed by AS, e.g., from AS80085). You can also use measurement IDs from previous tests to reuse specific probes.
    • Flags: Additional modifiers like --limit to control the number of probes used.
    globalping ping google.com from aws
globalping ping google.com from Berlin, South America --limit 2

  4. Reselect probes from a previous measurement

    master

    You can instruct the API to use the same probes from a previous measurement by providing its measurement ID in the magic field. This is useful for benchmarking, troubleshooting, or emulating continuous pings.

    Example usage: from WZIAtMx4LLhzit02

    IMPORTANT

    This is a best-effort action. If probes are offline or the measurement has expired, they will be missing from the new results. Do not hard-code measurement IDs in production as they expire.

    from WZIAtMx4LLhzit02

  5. Understand the Globalping Infrastructure components

    master

    The Globalping platform relies on several key infrastructure components hosted primarily on Hetzner in Falkenstein:

    • API (api.globalping.io): The central entry point for users and probes.
    • Redis 7.x: Used for caching GeoIP information, storing measurement results, and synchronizing connected probes across API instances. It uses the maxmemory-policy allkeys-lru and has the RedisJSON 2.x module enabled.
    • Measurement Store (TimescaleDB): Used for long-term storage of measurement results.
    • Elastic APM: Used for monitoring API performance, collecting production logs, and monitoring self-hosted servers.
    • DNS: Managed via Hetzner DNS for *.globalping.io.

  6. Liability and usage types

    master

    Liability terms vary depending on whether you are using Globalping as a consumer or a business user:

    Business Users

    • Warranties: All implied conditions, warranties, or representations are excluded.
    • Losses: Globalping is not liable for any loss or damage arising from the use of or reliance on the services, including loss of profits, sales, revenue, business interruption, or loss of reputation.

    Consumer Users

    • Commercial Use Prohibited: Services provided for domestic and private use must not be used for any commercial or business purposes.
    • Liability: Globalping has no liability to consumer users for loss of profit, business interruption, or loss of business opportunity.

  7. Understand Globalping platform limits

    master

    Globalping enforces several limits to prevent abuse and ensure sustainability. Limits are categorized by authentication status and apply to IP addresses or specific API keys.

    Global Limits

    These apply to all users per IP address:

    • 2 GET requests per second per measurement.

    Unauthenticated Users

    Users without an API key are subject to the following limits per IP address:

    • 250 tests per hour
    • 50 probes per measurement

    Note: A 'test' is defined as a successful measurement run from one probe. For example, a limit of 10 tests allows either 10 measurements with 1 probe each, or 1 measurement with 10 probes.

    Registered Users (Free Tier)

  8. How the Geo IP algorithm works

    master

    The Globalping Geo IP algorithm determines the location of a probe by aggregating data from multiple providers and applying approximation and prioritization logic. This ensures a high-confidence location even when individual providers return imprecise data.

    The Process

    1. Data Collection: The system queries five providers: ipinfo, ip2location, maxmind, ipmap, and fastly. Results that are errors or not found are filtered out.
    2. City Approximation: To improve accuracy, the system checks if the provider's city is in the dc-cities.json list. If not, it performs a city approximation:
      • Searches the GeoNames database within a 30 km radius of the provider's latitude/longitude.
      • Filters for cities within the same country.
      • Selects the city with the largest population.
      • If no city is found, the original provider value is kept.
    3. Prioritization and Sorting: Providers are sorted into groups to resolve discrepancies. The sorting hierarchy is:
      • Country: Providers with the same country are grouped together and prioritized.
      • City: Within a country group, providers with the same city are grouped together.
      • Provider Priority: If groups are equal in size, the group containing the highest-priority provider (based on the global priority list) comes first. Groups are sorted internally by provider priority.
      • Global Provider Priority: ["ipinfo", "ip2location", "maxmind", "ipmap", "fastly"] (where ipinfo is highest).
    4. Final Selection: The first item from the sorted list is selected as the definitive location data for the probe.

    Provider Priority Order

    ipinfo > ip2location > maxmind > ipmap > fastly

    // Example of the final output structure after the algorithm runs
{
  "ipinfo": {
    "country": "US",
    "city": "San Jose",
    "lat": 37.323,
    "long": -122.03218,
    "asn": "0001"
  }
}

  9. Target probe locations using the 'magic' field

    master

    Globalping uses a "magic" field to parse location inputs across all integrations (CLI, Slack, Web, API). This allows for a consistent user experience when specifying where tests should originate. The magic parser supports various parameters including:

    • Countries/Continents/Regions: usa, europe, western europe
    • Cities/States: new york, california, frankfurt
    • Cloud Providers/Regions: aws, us-east-2, gcp-us-south1
    • Network/Infrastructure: as396982 (ASN), comcast (ISP), eyeball-network, datacenter-network

    If no location is provided, the system defaults to world, which uses a pseudo-random algorithm to select probes proportionally across continents (e.g., aiming for specific proportions in Africa, Asia, Europe, etc.).

  11. Set up a remote API staging environment

    master

    To run the API staging environment, you will set up two API instances behind an HAProxy load balancer on port 80.

    Key Configuration Details:

    • GeoIP: The GeoIP client is mocked so all probes receive the same location.
    • Performance Mode: Setting TEST_MODE=perf instructs the API to use the fake IP provided by the probe.

    Steps:

    1. Define REDIS_PASSWORD and REDIS_HOST.
    2. Install and configure haproxy with a round-robin backend targeting ports 3001 and 3002.
    3. Install Node.js (version 24).
    4. Clone, install, and build the globalping repository.
    5. Run two separate instances of the app on ports 3001 and 3002 using the environment variables provided in the example.
    # Update that variables before start
REDIS_PASSWORD=<your_value>
REDIS_HOST=<your_value>

# Install haproxy
sudo apt-get update
sudo apt -y install haproxy

# Configure and start haproxy
sudo chmod a+w /etc/haproxy/haproxy.cfg
cat <<EOF | sudo tee -a /etc/haproxy/haproxy.cfg > /dev/null
frontend gp_fe
    bind *:80
    default_backend gp_be

backend gp_be
    balance roundrobin
    option httpchk GET /health
    server server1 127.0.0.1:3001 check
    server server2 127.0.0.1:3002 check
EOF
sudo systemctl stop haproxy
sudo systemctl start haproxy

# Install node
sudo apt-get install -y ca-certificates curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_MAJOR=24
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install nodejs -y

# Copy and build the repository
git clone https://github.com/jsdelivr/globalping.git
cd globalping/
npm i
npm run build

# Run the app
echo 'Run 2 app instances using: 
PORT=3001 HOSTNAME=3001 REDIS_URL=redis://default:$REDIS_PASSWORD@$REDIS_HOST:6379 NODE_ENV=production ADMIN_KEY=admin TEST_MODE=perf NEW_RELIC_ENABLED=false NEW_RELIC_LOG_ENABLED=false node dist/index.js
and
PORT=3002 HOSTNAME=3002 REDIS_URL=redis://default:$REDIS_PASSWORD@$REDIS_HOST:6379 NODE_ENV=production ADMIN_KEY=admin TEST_MODE=perf NEW_RELIC_ENABLED=false NEW_RELIC_LOG_ENABLED=false node dist/index.js
'

  12. Use API keys to increase Globalping limits

    master

    By registering on the Globalping Dashboard, you receive an API key that grants higher usage limits than unauthenticated access:

    • 500 tests per hour
    • 500 probes per measurement

    Credits System

    Registered users who host probes receive 150 credits per day for each probe.

    • Purpose: Credits allow you to run measurements beyond your hourly limits.
    • Cost: Each test performed above the hourly limit costs one credit.
    • Persistence: Credits do not expire and accumulate in your account if unused.

    GitHub Sponsors

    As a GitHub Sponsor of jsDelivr, you receive an additional 2000 credits for every dollar donated.