Private Locations Configuration

Overview

Synthetic private locations come with a set of options you can configure to match your environment requirements. All options for the private location worker can be found by running the help command:

    docker run --rm datadog/synthetics-private-location-worker --help

    synthetics-pl-worker.exe --help

    Refer to the example in the Datadog Helm repository.

    Customize your private location

    Available parameters are listed below. These configuration options for private locations can be passed as parameters to your JSON configuration file or as arguments in the launch command, for example:

      docker run -d --restart always -v $PWD/<MY_WORKER_CONFIG_FILE_NAME>.json:/etc/datadog/synthetics-check-runner.json datadog/synthetics-private-location-worker:latest --logFormat=json

      synthetics-pl-worker.exe --config=<PathToYourConfiguration> --logFormat=json

      Arguments set in the launch command have precedence over the configuration file. However, these options are not stored and are consequently only relevant for a given launch.

      Top configuration options

      Datadog site configuration

      site
      Type: String
      Default: datadoghq.com
      Datadog site from which the private location pulls the test configuration and pushes the test results. Your site is .

      DNS configuration

      The following parameters can be used to customize DNS resolution on your API tests:

      dnsUseHost
      Type: Boolean
      Default: true
      Use host local DNS configuration first (for example, the configuration from your etc/resolv.conf file), then DNS servers specified in the dnsServer parameter.
      dnsServer
      Type: Array of Strings
      Default: ["8.8.8.8","1.1.1.1"]
      DNS servers IPs to use in given order (for example, --dnsServer="8.8.4.4" --dnsServer="8.8.8.8").

      On browser tests, the DNS resolution is done directly by the browser, which usually reads DNS servers from the host. Alternatively, you can configure it at the container level (for example, using the --dns flag on Docker, or dnsConfig.nameservers on Kubernetes).

      Proxy configuration

      The following parameters can be used to configure a proxy to connect to Datadog:

      proxyDatadog
      Type: String
      Default: none
      Proxy URL used by the private location to send requests to Datadog (for example, --proxyDatadog=http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT>).
      proxyIgnoreSSLErrors
      Type: Boolean
      Default: false
      Discard SSL errors when private location is using a proxy to send requests to Datadog.
      proxyEnableConnectTunnel
      Type: Boolean
      Default: none
      Enable HTTP CONNECT tunneling for HTTP proxies. When this option is not set, HTTP CONNECT tunneling is only used for HTTPS proxies.

      Note: HTTP forward proxies like Squid may require the HTTP CONNECT request to establish the initial TCP connection between the private location and Datadog. As such, the proxyEnableConnectTunnel parameter should be set to true. However, reverse proxies like HAProxy that direct an HTTP CONNECT request to Datadog may not work with this option enabled.

      Note: The proxy parameter is deprecated and should be replaced by proxyDatadog.

      The following parameters can be used to configure a default proxy to use for Synthetic Monitoring tests:

      proxyTestRequests
      Type: String
      Default: none
      Proxy URL used by the private location to send test requests to the endpoint. PAC files are supported with the following syntax: pac+https://... or pac+http://....

      Advanced configuration

      concurrency
      Type: Number
      Default: 10
      Maximum number of tests executed in parallel.
      maxNumberMessagesToFetch
      Type: Number
      Default: 10
      Maximum number of tests fetched from Datadog.

      Note: Private Location containers output logs to stdout and stderr without saving them within the container.

      All configuration options

      --accessKey
      Type: String
      Default: none
      Access key for Datadog API authentication.
      --secretAccessKey
      Type: String
      Default: none
      Secret access key for Datadog API authentication.
      --datadogApiKey
      Type: String
      Default: none
      Datadog API key to send browser tests artifacts (such as screenshots).
      --privateKey
      Type: Array
      Default: none
      Private key used to decrypt test configurations.
      --publicKey
      Type: Array
      Default: none
      Public key used by Datadog to encrypt test results. Composed of --publicKey.pem.
      --site
      Type: String
      Default: datadoghq.com
      Datadog site from which the private location pulls the test configuration and pushes the test results. Your site is .
      --concurrency
      Type: Number
      Default: 10
      Maximum number of tests executed in parallel.
      --maxNumberMessagesToFetch
      Type: Number
      Default: 10
      Maximum number of tests fetched from Datadog.
      --proxyDatadog
      Type: String
      Default: none
      Proxy URL used by the private location to send requests to Datadog (for example, --proxyDatadog=http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT>).
      --disableFipsCompliance
      Type: Boolean
      Default: false
      Disables the FIPS compliance for a private location using ddog-gov.com. By default, Private Locations reporting to ddog-gov.com communicate to Datadog using FIPS-compliant encryption. The communication complies on the use of FIPS 140-2 validated Cryptographic Module - Certificate #4282. This option is required if you are using a Windows private location that reports to ddog-gov.com.
      --dumpConfig
      Type: Boolean
      Default: none
      Display worker configuration parameters without secrets.
      --enableStatusProbes
      Type: Boolean
      Enables the readiness and liveness of private location probes. This enables two endpoints: http://127.0.0.1:8080/liveness and http://127.0.0.1:8080/readiness.
      --statusProbesPort
      Type: Number
      Default: 8080
      Overrides the port for the private location status probes.
      --config
      Type: String
      Default: /etc/datadog/synthetics-check-runner.json
      Windows: C:\ProgramData\Datadog-Synthetics\worker-config.json
      Path to the JSON configuration file.
      --proxyTestRequests
      Type: String
      Default: none
      Proxy URL used by the private location to send test requests to the endpoint. PAC files are supported with the following syntax: pac+https://... or pac+http://....
      --proxyIgnoreSSLErrors
      Type: Boolean
      Default: false
      Discard SSL errors when private location is using a proxy to send requests to Datadog.
      --dnsUseHost
      Type: Boolean
      Default: true
      Use host local DNS configuration first (for example, the configuration from your etc/resolv.conf file), then DNS servers specified in the dnsServer parameter.
      --dnsServer
      Type: Array of Strings
      Default: ["8.8.8.8","1.1.1.1"]
      DNS servers IPs to use in given order (for example, --dnsServer="8.8.4.4" --dnsServer="8.8.8.8").
      --variableOverride
      Type: String
      Overrides the variables used in tests running on the Private Location. Format: VARIABLE=value. All variables imported this way are obfuscated.
      --environmentVariableOverride
      Type: String
      Overrides variables used in tests running on the Private Location with environment variables. It requires the environment variables to be imported in the containerized environment. With Docker, for example, docker run --env VARIABLE gcr.io/datadoghq/synthetics-private-location-worker --environmentVariableOverride VARIABLE. All variables imported this way are obfuscated.
      --allowedIPRanges
      Type: Array of Strings
      Default: none
      Grant access to specific IPs and/or CIDR among IP ranges blocked through --enableDefaultBlockedIpRanges or blockedIPRanges (for example, "allowedIPRanges.4": "10.0.0.0/8"). Note: allowedIPRanges has precedence over blockedIPRanges.
      --blockedIPRanges
      Type: Array of Strings
      Default: none
      Block access to specific IPs and/or CIDR in addition, or not, to the IP ranges blocked when setting the --enableDefaultBlockedIpRanges parameter to true (for example, --blockedIPRanges.4="127.0.0.0/8" --blockedIPRanges.6="::1/128".)
      --enableDefaultBlockedIpRanges
      Type: Boolean
      Default: false
      Prevent users from creating Synthetic tests on endpoints that are using reserved IP ranges (IANA IPv4 and IPv6 Special-Purpose Address Registry), except for those explicitly set with the --allowedIPRanges parameter.
      --allowedDomainNames
      Type: Array
      Default: none
      Grant access to domain names in test. Has precedence over –blockedDomainNames, for example: --allowedDomainNames="*.example.com".
      --blockedDomainNames
      Type: Array
      Default: none
      Deny access to domain names in tests, for example: --blockedDomainNames="example.org" --blockedDomainNames="*.com".
      --enableIPv6
      Type: Boolean
      Default: false
      Use IPv6 to perform tests. Note: IPv6 in Docker is only supported with a Linux host.
      --version
      Type: Boolean
      Default: none
      Show version number of the worker.
      --logFormat
      Type: String
      Default: pretty
      Format log output between "compact", "pretty", "pretty-compact", and "json". Setting your log format to json allows you to have these logs automatically parsed when collected by Datadog.
      --verbosity
      Type: Number
      Default: 3
      Verbosity level from 1 (errors only) to 4 (debug logs and above). Setting the verbosity from the command line is done with -v, -vv, -vvv, and -vvvv arguments.

      Verbosity levelCLI argumentJSON config option
      DEBUG-vvvv"verbosity": 4
      INFO (default)-vvv"verbosity": 3
      WARNING-vv"verbosity": 2
      ERROR-v"verbosity": 1
      --help
      Type: Boolean
      Default: none
      Show the output for the help command.

      Environment variables

      Command options can also be set using environment variables such as DATADOG_API_KEY="...", DATADOG_WORKER_CONCURRENCY="15", DATADOG_DNS_USE_HOST="true". For options that accept multiple arguments, use JSON string array notation (DATADOG_TESTS_DNS_SERVER='["8.8.8.8", "1.1.1.1"]')

      Supported environment variables:

      DATADOG_ACCESS_KEY, DATADOG_API_KEY, DATADOG_PRIVATE_KEY, DATADOG_PUBLIC_KEY_PEM, DATADOG_SECRET_ACCESS_KEY, DATADOG_SITE, DATADOG_WORKER_CONCURRENCY, DATADOG_WORKER_LOG_FORMAT, DATADOG_WORKER_LOG_VERBOSITY, DATADOG_WORKER_MAX_NUMBER_MESSAGES_TO_FETCH, DATADOG_WORKER_PROXY, DATADOG_TESTS_DNS_SERVER, DATADOG_TESTS_DNS_USE_HOST, DATADOG_TESTS_PROXY, DATADOG_TESTS_PROXY_ENABLE_CONNECT_TUNNEL, DATADOG_TESTS_PROXY_IGNORE_SSL_ERRORS, DATADOG_ALLOWED_IP_RANGES_4, DATADOG_ALLOWED_IP_RANGES_6, DATADOG_BLOCKED_IP_RANGES_4, DATADOG_BLOCKED_IP_RANGES_6, DATADOG_ENABLE_DEFAULT_WINDOWS_FIREWALL_RULES, DATADOG_ALLOWED_DOMAIN_NAMES, DATADOG_BLOCKED_DOMAIN_NAMES, DATADOG_WORKER_ENABLE_STATUS_PROBES, DATADOG_WORKER_STATUS_PROBES_PORT

      Further Reading

      Additional helpful documentation, links, and articles:

      Getting Started with Private LocationsDOCUMENTATION more more Dimension your private locationsDOCUMENTATION more more