Run Synthetics tests from Private Locations
Datadog の調査レポート: サーバーレスの状態 レポート: サーバーレスの状態

Run Synthetics tests from Private Locations

This feature is in public beta and available for API Tests only.


Private locations allow you to monitor internal-facing applications or any private URLs that aren’t accessible from the public internet. They can also be used to create a new custom Synthetics location.


The private location worker is shipped as a Docker container, so it can run on a Linux based OS or Windows OS if the Docker engine is available on your host and can run in Linux containers mode.

By default, every second, your private location worker pulls your test configurations from Datadog’s servers using HTTPS, executes the test depending on the frequency defined in the configuration of the test, and returns the test results to Datadog’s servers.

Once you created a private location, configuring a Synthetics API test from a private location is completely identical to the one of Datadog managed locations.

Create a new private location

  1. Go in Synthetics -> Settings -> Private Locations and create a new private location:

  2. Fill out the Location Details and click Save and Generate to generate the configuration file associated with your private location on your worker.

    Note: The configuration file contains secrets for private location authentication, test configuration decryption, and test result encryption. Datadog does not store the secrets, so store them locally before leaving the Private Locations screen. You need to be able to reference these secrets again if you decide to add more workers, or to install workers on another host.

  3. Launch your worker on:

    Launch your worker as a standalone container using the Docker run command provided and the previously created configuration file:

    docker run --rm -v $PWD/worker-config-<LOCATION_ID>.json:/etc/datadog/synthetics-check-runner.json datadog/synthetics-private-location-worker

    Create a Kubernetes ConfigMap with the previously created JSON file by executing the following:

    kubectl create configmap private-worker-config --from-file=<MY_WORKER_CONFIG_FILE_NAME>.json

    Create a private-worker-pod.yaml file containing the below and modify <MY_WORKER_CONFIG_FILE_NAME>.json with the name of your Private Location JSON config file in the subPath section.

    apiVersion: v1
    kind: Pod
      name: private-location-worker
      annotations: '[{"source":"private-location-worker","service":"synthetics"}]'
      - name: datadog-private-location-worker
        image: datadog/synthetics-private-location-worker
        args: ["-f=json"]
        - mountPath: /etc/datadog/synthetics-check-runner.json
          name: worker-config
          subPath: <MY_WORKER_CONFIG_FILE_NAME>.json
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 2
              - /bin/sh
              - -c
              - "[ $(expr $(cat /tmp/ + 120000) -gt $(date +%s%3N) ]"
      - name: worker-config
          name: private-worker-config

    Execute the below to apply the configuration to your pod:

    kubectl apply -f private-worker-pod.yaml
  4. To pull test configurations and push test results, the private location worker needs access to one of the Datadog API endpoints:

    Datadog siteEndpoint
    Datadog US for version 0.1.6+ ( for versions <0.1.5)
    Datadog EU

    Check if the endpoint corresponding to your Datadog site is available from the host running the worker:

    • For the Datadog US site: for version 0.1.6+ use curl (curl for versions <0.1.5).
    • For the Datadog EU site: curl

    Note: You must allow outbound traffic on port 443 because test configurations are pulled and test results are pushed via HTTPS.

  5. If your private location reports correctly to Datadog you should see the corresponding health status displayed if the private location polled your endpoint less than 5 seconds before loading the settings or create test pages:

    • In your private locations list, in the Settings section:
    • In the form when creating a test, below the Private locations section:
  6. You should now be able to use your new private location as any other Datadog managed locations for your Synthetics API tests.


The synthetics-private-location-worker comes with a number of options that can be set to configure your private locations through the launch command or the configuration file. Arguments set in the launch command have precedence over the configuration file. However, these options aren’t stored and are consequently only prevalent for a given launch:

dnsServerArray of Strings["",""]DNS server IPs used in given order (--dnsServer="" --dnsServer="")
dnsUseHostBooleanfalseUse local DNS config in addition to –dnsServer (currently ["<DEFAULT_DNS_IN_HOST_CONFIG"])
whitelistedRange.4Array of StringsnoneGrant access to IPv4 IP ranges (e.g. --whitelistedRange.4="" or --whitelistedRange.4={"",""}, has precedence over --blacklistedRange)
whitelistedRange.6Array of StringsnoneGrant access to IPv6 IP ranges (e.g. --whitelistedRange.6="::/128" or --whitelistedRange.6={"::/128","64:ff9b::/96"}, has precedence over --blacklistedRange)
blacklistedRange.4Array of StringsIANA IPv4/IPv6 Special-Purpose Address RegistryDeny access to IPv4 IP ranges (e.g. --blacklistedRange.4="" --blacklisted.4="")
blacklistedRange.6Array of StringsIANA IPv4/IPv6 Special-Purpose Address RegistryDeny access to IPv6 IP ranges (e.g. --blacklistedRange.6="::1/128")
siteStringdatadoghq.comDatadog site ( or
proxyStringnoneProxy URL
proxyIgnoreSSLErrorsBooleannoneDisregard SSL errors when using a proxy.
logFormatStringprettyFormat log output [choices: "pretty", "json"]. Setting your log format to json allows you to have these logs automatically parsed when collected by Datadog.
concurrencyInteger10Maximum number of tests executed in parallel.
maxTimeoutInteger60000Maximum test execution duration, in milliseconds.
maxBodySizeInteger5e+6Maximum HTTP body size for download, in bytes.
maxBodySizeIfProcessedInteger5e+6Maximum HTTP body size for the assertions, in bytes.
regexTimeoutInteger500Maximum duration for regex execution, in milliseconds.

Note: These options and more can be found by running the help command for the Datadog worker docker run --rm datadog/synthetics-private-location-worker --help.

Proxy configuration

If the traffic has to go through a proxy, you need to set the proxy option to your proxy URL in a curl-like way (--proxy=http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT> URL for instance). If you use this, no additional configuration on your proxy should be needed.

DNS configuration

By default, the Datadog workers use to perform DNS resolution. If it fails, it makes a second attempt to communicate with

If you are testing an internal URL and need to use an internal DNS server you can set the dnsServer option to a specific DNS IP address. Alternatively leverage the dnsUseHost parameter to have your worker use your local DNS config from the etc/resolv.conf file.

Special-purpose IPv4 whitelisting

If you are using private locations to monitor internal endpoints, some of your servers might be using special-purpose IPv4. These IPs are blacklisted by default, so if your private location needs to run a test on one of them, you first need to whitelist it using the whitelistedRange parameter.

Scale your Private Location

To scale a private location:

  • Change the concurrency parameter value to allow more parallel tests from one worker.
  • Add or remove workers on your host. It is possible to add several workers for one private location with one single configuration file. Each worker would then request N tests to run depending on its number of free slots and when worker 1 is processing tests, worker 2 requests the following tests, etc.


The private location workers only pull data from Datadog servers. Datadog does not push data to the workers. The secret access key, used to authenticate your private location worker to the Datadog servers, uses an in-house protocol based on AWS Signature Version 4 protocol.

The test configurations are encrypted asymmetrically. The private key is used to decrypt the test configurations pulled by the workers from Datadog servers. The public key is used to encrypt the test results that are sent from the workers to Datadog’s servers.

Further Reading