Documentation forSolarWinds Observability SaaS

Add a private probe through Docker

Install the Private Probe as a single Docker container on a host or in a simple container environment.

Before getting started, make sure you have the prerequisites to install the Private Probe. See Private Probe requirements.

Prerequisites

Before you are able to run a private probe on Docker, you have to complete the following prerequisites.

  1. Install Docker and download the Docker image

  2. Test your Docker installation.

  3. Create the API token

  4. Identify the correct Synthetics Collector endpoint

  5. Configure the private probe

Install Docker and download the Docker image

Before installing your private probe, you must have Docker installed, and you need to download the Docker image.

  1. Install Docker. For information about installing Docker, see the Docker instructions.

  2. Download the Docker image https://hub.docker.com/r/solarwinds/synthetics-private-probe.

Test your Docker installation

  1. Run a simple container to confirm Docker is installed and can run containers. 

    docker run --rm hello-world
Docker is installed and can run containers!

Create the API token

The API ingestion token is required to set up your private probe. The API ingestion token authenticates the private probe with the Synthetics collector.

To create a new ingestion token:

  1. In SolarWinds Observability, click Settings > API Tokens.

  2. Click Create API token.

  3. Enter a name and select the Ingestion as the token type

  4. Click Create API Token.

See API tokens for complete instructions.

To reuse an existing ingestion token:

  1. In SolarWinds Observability, click Settings > API Tokens.

  2. Click the three dots (⋯) next to an existing Ingestion token and select Copy Token to copy it to the clipboard.

Create an in SolarWinds Observability that will be used to configure your private probe.

Identify the correct Synthetics Collector endpoint

The following URLs are used by the private probe to retrieve check schedules and submit check results to the Synthetics-Collector service through gRPC protocol.

  • synthetics.collector.na-01.cloud.solarwinds.com

  • synthetics.collector.na-02.cloud.solarwinds.com

  • synthetics.collector.eu-01.cloud.solarwinds.com

  • synthetics.collector.ap-01.cloud.solarwinds.com

The xx-yy part of the hostname must match the data center in the URL you use to access SolarWinds Observability. For example:

  • If you log in at https://my.na-01.cloud.solarwinds.com, you would use synthetics.collector.na-01.cloud.solarwinds.com.

  • If you log in at https://my.eu-01.cloud.solarwinds.com, you would use synthetics.collector.eu-01.cloud.solarwinds.com.

See the endpoint system requirements to determine which endpoint is correct for your organization.

This process uses port 443 and is only an outbound communication.

Configure the private probe

The Private Probe can be configured in two ways:

  • From a yaml configuration file inside of the Docker Container

  • From environment variables in the configuration file

By default, the Private Probe looks for the configuration file at /app/config/private-probe.yaml. You can mount this file from your host into the container. You can also override any configuration value using an environment variable.

Required Configuration variables

The following environment variables are required in the Private Probe yaml configuration file.

Friendly name Environment Variable Name Required Description
Synthetics Collector URL SYNTHETICS_COLLECTOR_URL Yes Specifies the URL of the Synthetics Collector service where the probe will connect. For example, synthetics.collector.na-01.cloud.solarwinds.com:443.
Ingestion API token API_TOKEN Yes Specifies the ingestion token you created in SolarWinds Observabilitythat's used to authenticate the probe with Synthetics Collector.
Local ID LOCAL_ID Yes

User defined unique identifier for the private probe which allows the probe to bind a running container instance in SolarWinds Observability.

  • A new LOCAL_ID registers a new probe in SolarWinds Observability.

  • Reusing the same LOCAL_ID after adding the container keeps the same probe identity, so existing checks continue to run on the new container.

  • If you run multiple containers with the same LOCAL_ID, SolarWinds Observabilitytreats them as a single probe instance and the same checks will run on all of them.
Probe name NAME Yes

User defined name for the probe visible in SolarWinds Observability.

You can change this later. If LOCAL_ID stays the same, updating NAME renames the existing probe.

Optional advanced configuration variables

The following environment configuration variables are optional in the Private Probe yaml configuration file.

Environment Variable Name Required Default Value Description
LOG_LEVEL No INFO

Specifies the verbosity level of log messages generated by the probe DEBUG,INFO,WARN,ERROR.

  • Keep INFO for normal operation.

  • Use DEBUG temporarily when troubleshooting (for example, to get trace IDs for support).
FETCH_PERIODIC_SCHEDULE_INTERVAL No 60 seconds (s) Specifies the interval at which the probe fetches the periodic schedule from the Synthetics Collector.
FETCH_ONE_TIME_SCHEDULE_INTERVAL No 30 seconds (s) Specifies the interval at which the probe fetches the one-time schedule from the Synthetics Collector.
RESEND_RESULTS_INTERVAL No 60 seconds (s) Specifies the interval at which the probe will try to resend results that failed to be sent by the Synthetics Collector.
RESULTS_BUFFER_LIMIT No 10000 Specifies the maximum number of results that are stored for send attempts.
API_CLIENT_TIMEOUT No 30 seconds (s) Specifies timeout for communication with Synthetics Collector.
EXTERNAL_EXECUTOR_HARD_TIMEOUT No 61 seconds (s) Specifies the hard timeout for the check executor.
TRANSACTION_EXECUTOR_HARD_TIMEOUT No 65 seconds (s) Specifies the hard timeout for the transaction executor.
EXECUTOR_SOFT_TIMEOUT_EXTENSION No 5 seconds (s) Specifies the soft timeout for the check executor. (This value is added to the executor hard timeout and to the transaction executor hard timeout).
BINARY_SIZE_LIMIT_MB No 1 Specifies the binary output limit for the transaction executor in megabytes (mb).

Example YAML Configuration 

private-probe:
  information:
    local_id: "local-private-probe"
    name: "My local private probe"
  options:
    synthetics_collector_url: "synthetics.collector.xx.cloud.solarwinds.com:443"
    api_token: "INGESTION_TOKEN"
    log_level: "INFO"
    fetch_periodic_schedule_interval: 60s
    fetch_one_time_schedule_interval: 60s
    resend_results_interval: 60s
    results_buffer_limit: 10000
    api_client_timeout: 30s
    executor_soft_timeout_extension: 5s
    external_executor_hard_timeout: 60s
    transaction_executor_hard_timeout: 65s
    binary_size_limit_mb: 1

Add your Private Probe through Docker

The Digital Experience private probe is a single docker image that can be added in a container environment with environment variables, or by mounting a configuration file.

Option 1: Run the Private Probe with environment variables

Use the latest probe image to run your Private Probe.

docker run -d \
	-e SYNTHETICS_COLLECTOR_URL='synthetics.collector.xx-xx.cloud.solarwinds.com:443' \
	-e API_TOKEN='INGESTION_TOKEN' \
	-e LOG_LEVEL='INFO' \
	-e LOCAL_ID='local-private-probe' \
	-e NAME='My local private probe' \
	solarwinds/synthetics-private-probe:latest

  1. Replace synthetics.collector.xx-xx.cloud.solarwinds.com:443 with your organization’s collector endpoint.

  2. Replace INGESTION_TOKEN with your ingestion API token created in SolarWinds Observability.

  3. Enter a unique LOCAL_ID for your probe instance.

  4. Enter a descriptive NAME that you can easily identify.

After your container starts and contacts the Synthetics Collector, your Private Probe is automatically registered in SolarWinds Observability and will appear as a new Private Probe where checks can be assigned.

Option 2: Run the Private Probe with a configuration file

  1. Save your configuration file as private-probe.yaml in a Directory on the Docker host.

  2. Run the container and mount the file.

Update the local path (./config/private-probe.yaml) to the location where you stored the configuration file.
docker run -d \
	-e PRIVATE_PROBE_CONFIG_FILE=/app/private-probe.yaml \
	-v ./config/private-probe.yaml:/app/private-probe.yaml \
	solarwinds/synthetics-private-probe:latest

Verify your Private Probe is running

  1. Open a new terminal window.

  2. Execute the following to list running containers.

    docker ps

  3. Confirm that a container based on solarwinds/synthetics-private-probe:latest is listed and has a STATUS of Up.

  4. In SolarWinds Observability, go to Digital Experience > Probes > Private Probes. Verify that your probe appears, shows a Connected status, and can be selected when configuring synthetic checks.

Optional: update trusted certificate authorities (cacert.pem)

The private probe uses the cacert.pem file to validate remote HTTPS certificates against trusted root Certificate Authorities (CAs).

A newer image typically includes an updated cacert.pem, but it may still lag behind the very latest CA list. In rare cases where you must immediately trust recently added or custom CAs, you can add your own cacert.pem file to the container.

To fetch the latest CA bundle from the cURL project:

curl https://curl.se/ca/cacert.pem -o ./cacert.pem

Execute the following to run the container and mount your custom cacert.pem.

docker run -d \
	-e SYNTHETICS_COLLECTOR_URL='synthetics.collector.xx-xx.cloud.solarwinds.com:443' \
	-e API_TOKEN='INGESTION_TOKEN' \
	-e LOG_LEVEL='INFO' \
	-e LOCAL_ID='local-private-probe' \
	-e NAME='My local private probe' \
	-v ./cacert.pem:/app/cacert.pem \
	solarwinds/synthetics-private-probe:latest
The file is mounted inside the container at /app/cacert.pem and overrides the default bundle.