Globalping Probe

Registering on the Globalping Dashboard and adopting your probes allows you to generate additional daily credits for running more tests.

To automate adoption, set the GP_ADOPTION_TOKEN environment variable. You can find your unique token and a personalized command in the Globalping Dashboard.

To join the Globalping network, run the official Docker container. The container supports both x86 and ARM architectures and requires no manual configuration beyond the initial run.

If you have a Globalping account, you should use an adoption token via the GP_ADOPTION_TOKEN environment variable to generate credits and increase your rate limits.

docker run -d --log-driver local --network host --restart=always --name globalping-probe globalping/globalping-probe

# To include your adoption token:
docker run -d --log-driver local --network host --restart=always --name globalping-probe -e GP_ADOPTION_TOKEN=XXX globalping/globalping-probe

The probe's capacity scales with available CPU cores. While it is lightweight and usually runs optimally as is, you can limit the number of CPUs used by the container using the --cpuset-cpus Docker parameter.

docker run -d --log-driver local --network host --restart=always --name globalping-probe --cpuset-cpus="0-2" globalping/globalping-probe

The probe code updates automatically within the container. However, the container image itself is not updated automatically. To update to the latest container version, you must manually pull the new image, stop, and remove the existing container before running a new one.

docker pull globalping/globalping-probe
docker stop globalping-probe
docker rm globalping-probe
docker run -d --log-driver local --network host --restart=always --name globalping-probe globalping/globalping-probe

For users opting for Podman, ensure you add the NET_RAW capability to allow the probe to perform network tests. You may also need to follow specific instructions to ensure the container starts automatically on boot and check logs for permission issues.

sudo podman run --cap-add=NET_RAW -d --network host --restart=always --name globalping-probe globalping/globalping-probe

If Docker Hub is inaccessible, you can pull the probe from the official GitHub Packages mirror. Note that ghcr.io does not currently support IPv6.

docker run -d --log-driver local --network host --restart=always --name globalping-probe ghcr.io/jsdelivr/globalping-probe

When a DNS command fails, the result includes a failureSource to help distinguish between network/resolver issues and internal probe issues.

• resolver: The failure was caused by the DNS resolver (e.g., connection refused, timed out, or the resolver couldn't reach the address).
• target: The query returned a private IP address, which is not allowed for non-ICANN targets.
• internal: An unexpected error occurred within the probe execution logic.

HTTP measurements track the duration of several distinct phases of the request lifecycle. These timings are provided in milliseconds within the timings object of the output.

• dns: Time taken for DNS resolution.
• tcp: Time taken to establish the TCP connection.
• tls: Time taken for the TLS handshake (only for HTTPS).
• firstByte: Time from the end of the handshake/connection until the first byte of the response is received.
• download: Time taken to download the response body.
• total: The total time from the start of the measurement to completion.

The TracerouteCommand classifies failures into two main categories via the FailureSource type:

• internal: The failure originated within the probe's environment (e.g., the traceroute process timed out but the target was reachable, or an internal execution error occurred).
• target: The failure is related to the network path or the target itself (e.g., the target is unreachable, or the traceroute output indicates unanswered probes/unreachable upstream nodes).

This distinction helps determine if a failed test is due to the probe's infrastructure or the network being tested.

The probe application includes built-in mechanisms for self-maintenance:

Node.js Auto-updates

If the current Node.js version does not match the WANTED_VERSION (currently v22.22.3), the probe attempts to update itself using nvm (Node Version Manager).

Requirements for auto-update:

• Memory: At least 250 MB of available memory.
• Disk Space: At least 1000 MB of available disk space.
• Environment: Must not be a hardware probe (detected via GP_HOST_HW or hardware inspection).

If resources are insufficient, the probe will log a warning and skip the update.

Entrypoint Updates

The probe monitors its own entrypoint script. If a change is detected between the current entrypoint and the version in the package, the probe will replace the current script with a command to copy the new version and then restart the process.

A HopType object represents a single hop in a traceroute/MTR path. It contains both network identity and statistical performance data.

Key Fields

• resolvedAddress: The normalized IP address of the hop.
• displayAddress: The address as it appeared in the raw output (may include scope IDs like %eth0).
• resolvedHostname: The resolved DNS hostname.
• asn: An array of Autonomous System Numbers (e.g., ['1234', '5678']).
• stats: A HopStatsType object containing:
  • loss: Percentage of packet loss.
  • drop: Count of dropped packets.
  • rcv: Count of received packets.
  • total: Total packets sent.
  • avg: Average RTT.
  • stDev: Standard deviation of RTT.
  • jAvg: Average jitter.
  • min/max: Minimum and maximum RTT.
• timings: An array of timing objects containing the RTT for specific sequences.